semgrep-rule-creator

Semgrep 规则创建器

创建具有适当测试和验证的生产级 Semgrep 规则。

适用场景

理想场景：

• 针对特定错误模式编写 Semgrep 规则
• 编写用于检测代码库中安全漏洞的规则
• 编写用于检测数据流漏洞的污点模式规则
• 编写用于强制执行编码规范的规则

不适用场景

请勿将此技能用于：

• 运行现有 Semgrep 规则集
• 不使用自定义规则进行常规静态分析（请使用 static-analysis 技能）

应避免的借口

编写 Semgrep 规则时，请避免以下常见捷径：

• “模式看起来很完整” → 仍须运行 semgrep --test --config <rule-id>.yaml <rule-id>.<ext> 进行验证。未经测试的规则可能暗藏误报或漏报。
• “它能匹配易受攻击的情况” → 匹配漏洞只完成了一半工作。请确认安全情况不会匹配（误报会损害信任）。
• “对这个问题使用污点模式太复杂了” → 如果数据从用户输入流向危险接收点，污点模式比模式匹配更精准。
• “一个测试就够了” → 请包含边缘情况：不同的编码风格、经过净化的输入、安全替代方案和边界条件。
• “我先优化模式” → 先编写正确的模式，通过所有测试后再进行优化。过早优化会导致回归。
• “AST 转储太复杂了” → AST 能准确展示 Semgrep 如何解析代码。跳过这一步会导致模式无法匹配语法变体。

反模式

范围过广——匹配所有内容，无法有效检测：

# 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 to verify no false positives
# ruleid: my-rule
dangerous(user_input)

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

# ok: my-rule
dangerous("hardcoded_safe_value")

模式过于具体——无法匹配各种变体：

# BAD: Only matches exact format
pattern: os.system("rm " + $VAR)

# GOOD: Matches all os.system calls with taint tracking
mode: taint
pattern-sources:
  - pattern: input(...)
pattern-sinks:
  - pattern: os.system(...)

严格程度

此工作流要求严格执行——不得跳过步骤：

• 先阅读文档：编写 Semgrep 规则前，请参阅文档
• 必须先编写测试：不得在没有测试的情况下编写规则
• 测试通过率必须达到 100%：“大部分测试通过”不可接受
• 最后进行优化：只有全部测试通过后才能简化模式
• 避免通用模式：规则必须具体，不得匹配范围过广的模式
• 优先使用污点模式：适用于数据流漏洞
• 一个 YAML 文件对应一条 Semgrep 规则：每个 YAML 文件只能包含一条 Semgrep 规则；不得在单个文件中合并多条规则
• 禁止通用规则：针对特定语言编写 Semgrep 规则时，避免使用通用模式匹配（languages: generic）
• 禁止使用 todook 和 todoruleid 测试注释：禁止在测试文件中使用 todoruleid: <rule-id> 和 todook: <rule-id> 注释来记录未来的规则改进

概述

此技能指导如何创建用于检测安全漏洞和代码模式的 Semgrep 规则。规则通过迭代创建：分析问题、先编写测试、分析 AST 结构、编写规则，并反复调整直到所有测试通过，最后优化规则。

选择方法：

• 污点模式（优先）：不受信任的输入流向危险接收点的数据流问题
• 模式匹配：不涉及数据流的简单语法模式

为什么优先使用污点模式？ 模式匹配能发现语法，却无法识别上下文。模式 eval($X) 既会匹配 eval(user_input)（易受攻击），也会匹配 eval("safe_literal")（安全）。污点模式会跟踪数据流，因此只有不受信任的数据实际到达接收点时才会发出警报——这能大幅减少注入漏洞的误报。

在不同方法间迭代： 可以进行尝试。如果从污点模式开始，但效果不佳（例如，污点传播不符合预期，或误报／漏报过多），可以改用模式匹配。反之，如果模式匹配在安全情况下产生过多误报，可以改用污点模式。目标是得到可用的规则，而不是僵化地坚持某种方法。

输出结构——目录以规则 ID 命名，且其中恰好包含 2 个文件：

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

快速开始

rules:
  - id: insecure-eval
    languages: [python]
    severity: HIGH
    message: User input passed to eval() allows code execution
    mode: taint
    pattern-sources:
      - pattern: request.args.get(...)
    pattern-sinks:
      - pattern: eval(...)

测试文件（insecure-eval.py）：

# ruleid: insecure-eval
eval(request.args.get('code'))

# ok: insecure-eval
eval("print('safe')")

运行测试（在规则目录中）：semgrep --test --config <rule-id>.yaml <rule-id>.<ext>

快速参考

• 有关命令、模式运算符和污点模式语法，请参阅 quick-reference.md。
• 有关详细的工作流和示例，必须参阅 workflow.md

工作流

复制此清单并跟踪进度：

Semgrep Rule Progress:
- [ ] Step 1: Analyze the Problem
- [ ] Step 2: Write Tests First
- [ ] Step 3: Analyze AST structure
- [ ] Step 4: Write the rule
- [ ] Step 5: Iterate until all tests pass (semgrep --test)
- [ ] Step 6: Optimize the rule (remove redundancies, re-test)
- [ ] Step 7: Final Run

文档

必需：编写任何规则之前，使用 WebFetch 阅读以下 7 个 Semgrep 文档链接中的全部内容：

1. 规则语法
2. 模式语法
3. 测试规则
4. 污点分析
5. 污点分析高级技巧
6. 常量传播
7. Trail of Bits 测试手册 — Semgrep 章节