semgrep

Semgrep 静态分析

基于模式的快速静态分析，用于安全扫描和自定义规则创建。

可用的 MCP 工具

如果你的环境中有 Semgrep MCP 工具，请优先使用它们进行扫描：

• semgrep_scan — 使用内置规则集扫描代码文件中的安全漏洞。传入绝对文件路径和可选配置（例如，p/security-audit、auto）。
• semgrep_scan_with_custom_rule — 使用你编写的自定义 YAML 规则扫描代码。以内联方式传入代码内容和规则。
• semgrep_findings — 从 Semgrep AppSec Platform 获取某个仓库的现有发现。
• semgrep_rule_schema — 获取编写 Semgrep 规则所需的完整架构。
• get_supported_languages — 列出 Semgrep 支持的所有语言。

如果无法使用 MCP 工具，请使用以下 CLI 命令。

何时使用 Semgrep

适用场景：

• 快速安全扫描（几分钟，而非几小时）
• 基于模式的 Bug 和漏洞检测
• 强制执行编码标准和最佳实践
• 查找已知漏洞模式（OWASP、CWE）
• 为你的代码库创建自定义检测规则
• 使用污点模式进行数据流分析

安装（CLI）

# pip (recommended)
python3 -m pip install semgrep

# Homebrew
brew install semgrep

# Docker
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep --config auto /src

---

第 1 部分：运行扫描

快速扫描

semgrep --config auto .                    # Auto-detect rules

使用规则集

semgrep --config p/<RULESET> .             # Single ruleset
semgrep --config p/security-audit --config p/trailofbits .  # Multiple

规则集	描述
p/default	通用安全性和代码质量
p/security-audit	全面的安全规则
p/owasp-top-ten	OWASP Top 10 漏洞
p/cwe-top-25	CWE Top 25 漏洞
p/trailofbits	Trail of Bits 安全规则
p/python	Python 专用
p/javascript	JavaScript 专用
p/golang	Go 专用

输出格式

semgrep --config p/security-audit --sarif -o results.sarif .   # SARIF
semgrep --config p/security-audit --json -o results.json .     # JSON

扫描指定路径

semgrep --config p/python app.py           # Single file
semgrep --config p/javascript src/         # Directory
semgrep --config auto --include='**/test/**' .  # Include tests

配置

.semgrepignore

tests/fixtures/
**/testdata/
generated/
vendor/
node_modules/

抑制误报

password = get_from_vault()  # nosemgrep: hardcoded-password
dangerous_but_safe()  # nosemgrep

---

第 2 部分：创建自定义规则

何时创建自定义规则

• 检测项目特有的漏洞模式
• 强制执行内部编码标准
• 为自定义框架构建安全检查
• 创建用于数据流分析的污点模式规则

选择方法

方法	适用场景
污点模式	数据从不可信来源流向危险接收点（注入漏洞）
模式匹配	无需数据流要求的语法模式（已弃用的 API、硬编码值）

对于注入漏洞，优先使用污点模式。仅靠模式匹配无法区分 eval(user_input)（有漏洞）和 eval("safe_literal")（安全）。

快速入门：模式匹配

rules:
  - id: hardcoded-password
    languages: [python]
    message: "Hardcoded password detected: $PASSWORD"
    severity: ERROR
    pattern: password = "$PASSWORD"

快速入门：污点模式

rules:
  - id: command-injection
    languages: [python]
    message: User input flows to command execution
    severity: ERROR
    mode: taint
    pattern-sources:
      - pattern: request.args.get(...)
      - pattern: request.form[...]
    pattern-sinks:
      - pattern: os.system(...)
      - pattern: subprocess.call($CMD, shell=True, ...)
    pattern-sanitizers:
      - pattern: shlex.quote(...)

模式语法速查

语法	描述	示例
...	匹配任意内容	func(...)
$VAR	捕获元变量	$FUNC($INPUT)
<... ...>	深层表达式匹配	<... user_input ...>

运算符	描述
pattern	匹配精确模式
patterns	必须全部匹配（AND）
pattern-either	匹配任意一个（OR）
pattern-not	排除匹配项
pattern-inside	仅匹配上下文内部
pattern-not-inside	仅匹配上下文外部
metavariable-regex	对捕获的值应用正则表达式

测试规则

必须先编写测试。 创建带有注释的测试文件：

# test_rule.py
def test_vulnerable():
    user_input = request.args.get("id")
    # ruleid: my-rule-id
    cursor.execute("SELECT * FROM users WHERE id = " + user_input)

def test_safe():
    user_input = request.args.get("id")
    # ok: my-rule-id
    cursor.execute("SELECT * FROM users WHERE id = ?", (user_input,))

运行测试：

semgrep --test --config rule.yaml test-file

命令参考

任务	命令
运行测试	semgrep --test --config rule.yaml test-file
验证 YAML	semgrep --validate --config rule.yaml
转储 AST	semgrep --dump-ast -l <lang> <file>
调试污点流	semgrep --dataflow-traces -f rule.yaml file

规则创建工作流

1. 分析问题 - 理解漏洞模式，确定采用污点分析还是模式匹配方法
2. 先创建测试用例 - 在编写规则前添加 ruleid: 和 ok: 注释
3. 分析 AST - 运行 semgrep --dump-ast，了解代码结构
4. 编写规则 - 从简单开始，逐步迭代
5. 测试直至 100% 通过 - 不得有“遗漏行”或“错误行”
6. 优化模式 - 仅在测试通过后删除冗余项

输出结构：

<rule-id>/
├── <rule-id>.yaml     # Semgrep rule
└── <rule-id>.<ext>    # Test file

详细参考资料

Semgrep 官方文档：

• 规则语法 - 完整的 YAML 结构、运算符和选项
• 规则 Schema - 完整的 JSON Schema 规范

本地参考资料：

• 工作流指南 - 完整的逐步规则创建流程
• 快速参考 - 模式运算符和污点分析组件

应避免的反模式

范围过宽：

# BAD: Matches any function call
pattern: $FUNC(...)

# GOOD: Specific dangerous function
pattern: eval(...)

缺少安全用例：

# BAD: Only tests vulnerable case
# ruleid: my-rule
dangerous(user_input)

# GOOD: Include safe cases
# ruleid: my-rule
dangerous(user_input)

# ok: my-rule
dangerous(sanitize(user_input))

应拒绝的自我辩解

捷径	错误原因
“Semgrep 没有发现问题，代码就是安全的”	Semgrep 基于模式匹配，无法跟踪复杂的跨函数数据流
“模式看起来很完整”	未经测试的规则可能隐藏误报或漏报
“它能匹配存在漏洞的用例”	匹配漏洞只是工作的一半；还要确认安全用例不会匹配
“污点分析模式太复杂了”	对于注入漏洞，污点分析模式能提供更高的精确度
“一个测试用例就够了”	应包含边缘情况：不同的编码风格、经过清理的输入和安全的替代方案

---

CI/CD 集成

GitHub Actions

name: Semgrep

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 1 * *'

jobs:
  semgrep:
    runs-on: ubuntu-latest
    container:
      image: returntocorp/semgrep

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Semgrep
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            semgrep ci --baseline-commit ${{ github.event.pull_request.base.sha }}
          else
            semgrep ci
          fi
        env:
          SEMGREP_RULES: >-
            p/security-audit
            p/owasp-top-ten
            p/trailofbits

---

资源

规则编写：

• 规则语法：https://semgrep.dev/docs/writing-rules/rule-syntax
• 模式语法：https://semgrep.dev/docs/writing-rules/pattern-syntax
• 规则 Schema：https://github.com/semgrep/semgrep-interfaces/blob/main/rule_schema_v1.yaml

常规资源：

• 规则库：https://semgrep.dev/explore
• Playground：https://semgrep.dev/playground
• 文档：https://semgrep.dev/docs/
• Trail of Bits 规则：https://github.com/trailofbits/semgrep-rules