semgrep-rule-creator 快速入门

把”代码规范”从口头约定,变成 CI 里自动执行的扫描规则。

这是什么?解决什么问题?

semgrep-rule-creator 是 Trail of Bits 在 trailofbits/skills 仓库中提供的一个 Skill,核心用途只有一个:教会 AI 编程助手(比如 Claude Code)如何帮你写 Semgrep 规则。

Semgrep 本身是一个轻量级的静态分析工具,可以把它理解成”代码版的 grep”,但匹配的不是字符串而是代码的抽象语法树(AST)。它内置了不少规则,但很多团队的内部规范——比如”禁止使用 eval""所有 SQL 拼接必须走 ORM""日志里不许出现明文手机号”——Semgrep 自带规则里是没有的。

这个 Skill 解决的问题,就是当你跟 AI 说”帮我写个 Semgrep 规则禁止 XXX”时,它不再瞎写一气,而是按 Trail of Bits 沉淀下来的 Semgrep 规则编写规范来产出 YAML,包括正确的 pattern、message、metadata、fix 字段,以及 SARIF 兼容的输出格式。

它适合的场景包括:安全团队想把”过往踩过的坑”变成规则、产品团队想把”接口返回字段必须非空”这类业务规则工程化、CTF 出题时写”找 flag”的检测规则。规则一旦写好,就可以在本地 semgrep --config rules/ 跑,也可以塞进 GitHub Actions、GitLab CI 跑。

准备工作

在用这个 Skill 之前,你需要先把 Semgrep 装好,推荐用 pip:

python3 -m pip install semgrep
semgrep --version

确认 semgrep 命令在终端能跑通,然后再让 AI 加载 semgrep-rule-creator 这个 Skill。如果是 Claude Code,需要把 trailofbits/skills 仓库 clone 下来:

git clone https://github.com/trailofbits/skills.git

把里面的 skills/semgrep-rule-creator/SKILL.md 通过 Claude Code 的 Skill 加载机制让 AI 看到即可。

3 步快速上手

第 1 步:安装 Skill

把 semgrep-rule-creator 这个 Skill 加载到你的 AI 编程助手里。如果用 Claude Code,可以这样:

# 把 SKILL.md 软链到 Claude Code 的 skills 目录
ln -s skills/semgrep-rule-creator ~/.claude/skills/semgrep-rule-creator

加载完成后,AI 在看到”写 Semgrep 规则""代码扫描""静态检查”这类关键词时,会自动调用这个 Skill 指导自己。

第 2 步:验证安装

重启 AI 助手,问一句:“请用 semgrep-rule-creator 的格式,给我写一个禁止使用 eval() 的 Python 规则。“如果 AI 输出了一段标准格式的 YAML 规则文件,说明 Skill 加载成功。

另外,你可以让 AI 帮你跑一遍验证:

semgrep --validate --config rules/no-eval.yaml

看到 Valid 字样就说明规则语法没问题。

第 3 步:用 Skill 跑第一个任务

新建一个工作目录,准备一段测试代码:

# test.py
user_input = "1 + 1"
result = eval(user_input)
print(result)

让 AI 帮你写一个 Semgrep 规则文件 rules/no-eval-python.yaml:

rules:
  - id: no-eval-python
    patterns:
      - pattern: eval(...)
    message: "禁止使用 eval(),存在代码注入风险"
    languages: [python]
    severity: ERROR
    metadata:
      category: security
      cwe: "CWE-95: Improper Neutralization of Directives in Dynamically Evaluated Code"

然后跑:

semgrep --config rules/no-eval-python.yaml test.py

终端会输出”找到 1 个匹配”,并指出 eval(user_input) 这一行。

常见踩坑

1. 把字符串当代码匹配:Semgrep 匹配的是 AST,不是字符串。新手常写出 pattern: "eval(" 这样的规则,这种是匹配不到的,必须用 pattern: eval(...)。
2. 忘记声明 languages:规则不写 languages,Semgrep 会尝试对所有语言解析,容易报奇怪的语法错误。
3. pattern 写得太严格:很多新手只写 pattern: requests.get(...),结果 requests.get(...).json() 这种链式调用匹配不到。要学会用 pattern-either 组合多个 pattern。
4. 忽略 metadata.cwe:不带 CWE 编号的规则在很多安全报告里无法被分类,审计场景下会扣分。
5. fix 写错语法:fix 字段必须用 $VAR 占位符代表捕获的变量,直接写完整替换表达式会报错。
6. 规则没跑通就进 CI:本地 semgrep --test 都过不了,直接 push 到 GitHub Actions,只会浪费 CI 时间。

初级用法

用法 1:禁止危险函数。让 AI 帮你写规则禁止 os.system、subprocess.call(shell=True)、pickle.loads 等危险调用,这是安全团队最常见的入门需求。

用法 2:统一日志规范。写规则强制要求 logger.info(...) 这样的标准日志调用,禁止直接用 print() 输出业务日志,这样后续接入日志平台更省事。

用法 3:检测硬编码密钥。利用 pattern-regex 加 metavariable-pattern,写一条规则扫描代码里的 api_key = "..."、password = "..." 等疑似硬编码。

高级玩法

玩法 1:taint analysis 追踪数据流。Semgrep 支持 mode: taint,可以追踪”用户输入 → 危险函数”这种跨函数的数据流。比如跟踪 request.form["x"] 是否最终流到了 SQL 拼接。这个 Skill 里有专门的 taint 模式模板,可以让 AI 帮你生成。

玩法 2:把规则托管成团队资产。写好的规则直接放到 Git 仓库的 semgrep/ 目录,所有项目通过 semgrep --config https://raw.githubusercontent.com/your-org/rules/main/ 远程引用,避免每个项目维护一份。

玩法 3:联动 SARIF + GitHub Code Scanning。semgrep ci 命令支持输出 SARIF 格式,把结果直接喂给 GitHub 的 Code Scanning,合并请求页面会直接显示违规位置,这个流程在 trailofbits/skills 的官方文档里有详细步骤。

小技巧

1. 用 semgrep --test 跑自带测试用例。每条规则建议配一对正/反例,放在同目录,Semgrep 会自动跑 *.yaml + *.py 配对测试。
2. 用 pattern-inside 限定上下文。比如只想匹配”在 try 块外的 eval”,用 pattern-inside 把作用域圈住,误报会少很多。
3. 善用 metavariable-pattern。可以基于变量名进一步约束,例如只匹配变量名含 password 的赋值。
4. 跑 --metrics off 关闭上报。在 CI 环境下建议加 SEMGREP_SEND_METRICS=off,避免每次扫描都上传统计数据。
5. 规则命名用连字符全小写。no-eval-python 而不是 noEvalPython,这样在 semgrep --config 引用时更清晰。

常见问题 FAQ

Q1: 这个 Skill 跟 semgrep-rule-creator 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: semgrep-rule-creator 来自 TrailOfBits,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 semgrep-rule-creator 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• Trail of Bits skills 仓库总目录:https://github.com/trailofbits/skills
• semgrep-rule-creator Skill 路径:https://github.com/trailofbits/skills/tree/main/skills/semgrep-rule-creator
• Semgrep 官方文档:https://semgrep.dev/docs/
• Semgrep 规则编写指南:https://semgrep.dev/docs/writing-rules/rule-ideas/
• SARIF 规范:https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。