🔒 安全工具 全难度 📦 TrailOfBits

semgrep-rule-creator

编写自定义 Semgrep 规则，把公司内部规范固化。

7.6 /10 ★★★★☆
#免费#安全#代码审查
📄 相关文章

📊 评分明细

📦 打包完整度
1.9 1.9 / 2.5
🎯 实用性
1.9 1.9 / 2.5
📖 文档清晰度
1.5 1.5 / 2
👥 社区影响力
1.1 1.1 / 1.5
🔗 集成度
1.1 1.1 / 1.5

🎯 适用场景

免费安全代码审查

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 文件。

参考链接

semgrep-rule-creator Skill 多维度简评

类别:安全工具 来源:trailofbits/skills 定位:编写自定义 Semgrep 规则,补充默认规则集未覆盖的模式。

注意:本文基于官方文档和公开资料整理,未经过 MagicNetWorld 实测。

一、核心定位与价值

Trail of Bits（成立于 2012 年,全球知名的安全审计公司）将内部使用的 Semgrep 规则编写工作流 Skill 化。该 Skill 引导用户按照”测试先行”的流程编写生产级 Semgrep 规则:先编写测试用例、分析 AST（抽象语法树）、编写规则、迭代直至所有测试通过。

核心价值:编写生产级 Semgrep 规则,支持 pattern matching 和 taint mode 两种模式,通过 AST 分析和强制测试用例确保规则质量,减少误报。

二、核心能力清单

能力说明
测试先行工作流强制先编写 test file（含 ruleid 和 ok 标记）,再编写规则
AST 分析指导用户分析代码的 AST 结构,避免模式匹配遗漏语法变体
Taint 模式支持数据流追踪,从用户输入（source）追踪到危险函数（sink）
Pattern 模式基于结构化模式匹配,适合编码规范和简单模式检测
安全用例和误报验证必需包含 safe 测试用例验证规则不会误报
CI 集成规则产出后可直接用于 semgrep --config 在 CI 流水线中运行

三、使用场景

适用场景

  • 编写 taint 模式规则检测 SQL 注入、命令注入（如 eval/exec 的参数来自用户请求）
  • 检测 Python/JavaScript/Go 等代码库中不安全 API 调用
  • 为代码库编写组织专属的编码规范检测规则（如禁止使用已废弃的 API）
  • 安全审计中发现特定漏洞模式后,编写检测规则防范同类问题
  • 在 CI 流水线中添加针对项目特定 bug 模式的自定义检测

不适用场景

  • 仅运行现有 Semgrep 规则集（应使用 static-analysis Skill）
  • 不做自定义规则编写的一般性静态分析

四、SKILL.md 工作流

Skill 内置的 SKILL.md 规定了严格的规则创建流程:

  1. 编写测试用例:创建测试文件,用 # ruleid: <rule-id> 标记应匹配的代码,# ok: <rule-id> 标记不应匹配的安全代码变体
  2. 分析 AST:运行 semgrep --dump-ast 查看目标代码的 AST 结构,确保规则覆盖所有语法变体
  3. 编写规则:基于 AST 分析编写 YAML 格式的规则文件
  4. 迭代测试:运行 semgrep --test --config <rule>.yaml <test-dir>/ 验证规则,调整直到所有测试通过

Skill 内置了反偷懒检查表,防止常见错误:

  • “pattern 看起来没问题” → 仍须运行 --test 验证
  • “匹配了漏洞用例就足够了” → 必须同时验证 safe 用例不会匹配
  • “taint 模式太复杂” → 如果数据从用户输入流向危险函数,taint 模式比 pattern 更精确

五、安装与配置

# 方式 1: npx（推荐）
npx skills add https://github.com/trailofbits/skills --skill semgrep-rule-creator

# 方式 2: Claude Code 内置安装
/plugin install trailofbits/skills/plugins/semgrep-rule-creator

安装后 Claude Code 会自动在合适的场景（如”帮我写一个检测 XSS 的 Semgrep 规则”）触发该 Skill。

六、Trail of Bits 安全 Skill 生态

Trail of Bits 官方发布了一组安全审计 Skills,均基于其多年安全审计经验:

Skill用途
static-analysisCodeQL + Semgrep + SARIF 聚合的静态分析工具链
semgrep-rule-creator自定义 Semgrep 规则编写
variant-analysisCVE 变体排查
supply-chain-risk-auditor供应链依赖审计
insecure-defaults硬编码和默认不安全配置检查
fix-review修复验证
constant-time-analysis侧信道分析
zeroize-audit内存清零审计

Trail of Bits 在区块链安全领域有深度积累,曾审计 Uniswap V4、Solana 等顶级项目。

七、总结

semgrep-rule-creator 将 Trail of Bits 的安全审计方法论封装为可复用的 AI Skill。其核心价值在于强制执行”测试先行”的规则编写流程,通过 AST 分析避免只凭直觉写 pattern,并要求同时验证漏洞用例和安全用例,从而产出低误报率的生产级规则。

适用人群:安全工程师、审计师、需要为代码库编写自定义检测规则的后端/智能合约开发者。

参考资料

📊 评分与标签

评分说明

总分 7.6/10 · S_入选

测评日期：2026-07-07 | 质量等级：资料核验（基于公开文档整理）

📊 可观测社区指标（数据核验日期：2026-07-07）

  • GitHub: trailofbits/skills ★5.2k, 🔱约600, 活跃维护中
  • 维护者: Trail of Bits（顶级安全公司）
  • 许可: CC-BY-SA-4.0
  • 定位: trailofbits/skills 仓库核心 Skill 之一，专注 Semgrep 自定义规则编写

📦 可安装性 1.7/2.5

  • git clone 后手动软链到 Agent skills 目录，无 npx 一键安装支持
  • CC-BY-SA-4.0 许可，商用需注意署名和相同方式共享要求
  • 依赖 Semgrep CLI (pip install semgrep)，非纯 Markdown 即用
  • 竞品对比 1: addyosmani/agent-skills 提供 MIT 许可 + .claude-plugin 自动发现，安装更便捷
  • 竞品对比 2: Semgrep 官方规则库无需额外安装但无 AI Agent 编写指导

🎯 实用性 2.3/2.5

  • 测试驱动 Semgrep 规则生成：先写测试用例，分析 AST，迭代直到规则通过
  • 覆盖 taint analysis、pattern-either、metavariable-pattern 等高级特性
  • 竞品对比 1: Semgrep Playground 在线编写但不含 AI Agent 引导式工作流
  • 竞品对比 2: CodeQL 更强大但学习曲线陡峭，本 Skill 轻量入门更快

📖 文档质量 1.8/2.0

  • SKILL.md 含规则模板库、AST 分析指南、SARIF 输出格式说明
  • Trail of Bits 专业安全文档背景，含 CWE 分类和常见漏洞模式
  • 竞品对比 1: Semgrep 官方规则编写指南覆盖更全面但不含 Skill 集成视角
  • 竞品对比 2: r2c（Semgrep 母公司）博客有深度文章但不成体系

👥 社区活跃 0.8/1.5

  • GitHub ★5.2k (trailofbits/skills)，安全专业受众精准但规模较小
  • Trail of Bits 品牌背书（Aave/Coinbase/GitHub 审计商），专业可信度高
  • 竞品对比 1: Semgrep 官方社区 ★11k+，活跃度更高
  • 竞品对比 2: obra/superpowers ★247k，社区规模远超

🔗 兼容性 1.0/1.5

  • CC-BY-SA-4.0 许可限制商用分发，需遵守署名和相同方式共享
  • 纯 Markdown 格式兼容 Claude Code、Cursor 等 Agent Skills 标准工具
  • 依赖 Semgrep CLI 运行环境，非完全平台无关
  • 竞品对比 1: addyosmani/agent-skills MIT 许可且多平台适配文件，兼容性更广
  • 竞品对比 2: Semgrep 官方规则纯 YAML 格式无许可限制，但无 AI Agent 集成

评分依据可追溯至公开来源，每项分数均有明确理由和数据支撑。

🏷️ 标签说明

  • 免费: CC-BY-SA-4.0 许可，核心功能免费使用。来源: trailofbits/skills
  • 安全: Trail of Bits 专业安全公司出品，聚焦安全审计和漏洞检测。来源: trailofbits/skills
  • 代码审查: 以 AI 驱动的代码审查和 Semgrep 规则编写为核心。来源: trailofbits/skills

📋 来源与核验记录