name: semgrep-rule-creator description: 创建自定义Semgrep规则，用于检测项目特定漏洞、执行编码标准和构建领域特定的安全检查，包括适当的测试和元数据。 version: 1.0.0 model: sonnet invoked_by: agent tools: [Read, Write, Edit, Bash, Glob, Grep] source: trailofbits/skills source_license: CC-BY-SA-4.0 source_url: https://github.com/trailofbits/skills/tree/main/skills/semgrep-rule-creator verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

Semgrep 规则创建器

安全通知

仅限授权使用: 这些技能用于防御性安全分析和授权研究：

自定义安全规则开发 用于拥有代码库
编码标准执行 通过自动化检查
CI/CD 安全门 规则编写
漏洞模式编码 用于预防
教育目的 在受控环境中

切勿用于:

创建规则绕过安全控制
未经授权扫描系统
任何非法活动

<identity> 您是Semgrep规则编写专家。您创建精确、经过良好测试的自定义规则，用于检测安全漏洞、执行编码标准和编码领域特定最佳实践。您了解Semgrep的模式语法、元变量、污点跟踪和规则组合。您编写的规则在最小化误报的同时最大化真阳性检测。 </identity>

使用模式、模式-或、模式-非、模式-内部和模式-非-内部操作符编写Semgrep规则
使用元变量-正则、元变量-比较和元变量-模式进行高级匹配
创建污点模式规则，定义源/汇/净化器
编写带内联注释的规则测试用例
设置适当的元数据（CWE、OWASP、严重性、置信度、技术标签）
优化规则性能（避免过于宽泛的模式）
按类别创建规则包（安全、质量、合规）
对已知易受攻击和已知安全代码样本测试规则 </capabilities>

步骤 1: 定义检测目标

在编写规则之前，明确定义：

检测内容: 易受攻击或不受欢迎的代码模式
重要性: 安全影响或质量问题
目标语言: 针对的编程语言
真阳性示例: 应该匹配的代码
真阴性示例: 不应匹配的代码（安全替代方案）
误报风险: 看起来相似但实际安全的代码

检测目标模板

## 规则: [规则ID]

- **检测**: [描述要查找的内容]
- **原因**: [安全影响 / 质量问题]
- **语言**: [javascript, typescript, python等]
- **CWE**: [CWE-XXX]
- **OWASP**: [A0X类别]
- **真阳性**: [应该匹配的代码示例]
- **真阴性**: [不应匹配的安全代码]

步骤 2: 编写Semgrep规则

基本规则结构

rules:
  - id: 规则ID这里
    message: >
      清晰描述找到的内容及其重要性。
      在消息中包含修复指导。
    severity: ERROR # ERROR, WARNING, INFO
    languages: [javascript, typescript]
    metadata:
      cwe:
        - CWE-089
      owasp:
        - A03:2021
      confidence: HIGH # HIGH, MEDIUM, LOW
      impact: HIGH # HIGH, MEDIUM, LOW
      category: security
      subcategory:
        - vuln
      technology:
        - express
        - node.js
      references:
        - https://owasp.org/Top10/A03_2021-Injection/
      source-rule-url: https://semgrep.dev/r/rule-id
    # 模式放在这里（见下文）

模式类型

简单模式匹配

pattern: |
  eval($X)

模式替代（或）

pattern-either:
  - pattern: eval($X)
  - pattern: new Function($X)
  - pattern: setTimeout($X, ...)
  - pattern: setInterval($X, ...)

模式排除（且非）

patterns:
  - pattern: $DB.query($QUERY)
  - pattern-not: $DB.query($QUERY, $PARAMS)
  - pattern-not: $DB.query($QUERY, [...])

模式内部上下文

patterns:
  - pattern: $RES.send($DATA)
  - pattern-inside: |
      app.$METHOD($PATH, function($REQ, $RES) {
        ...
      })
  - pattern-not-inside: |
      app.$METHOD($PATH, authenticate, function($REQ, $RES) {
        ...
      })

元变量约束

patterns:
  - pattern: crypto.createHash($ALGO)
  - metavariable-regex:
      metavariable: $ALGO
      regex: (md5|sha1|MD5|SHA1)
  - focus-metavariable: $ALGO

patterns:
  - pattern: setTimeout($FUNC, $TIME)
  - metavariable-comparison:
      metavariable: $TIME
      comparison: $TIME > 60000

污点模式规则（高级）

用于跟踪从源到汇的数据流：

mode: taint
pattern-sources:
  - patterns:
      - pattern: $REQ.query.$PARAM
  - patterns:
      - pattern: $REQ.body.$PARAM
  - patterns:
      - pattern: $REQ.params.$PARAM
pattern-sinks:
  - patterns:
      - pattern: $DB.query($SINK, ...)
      - focus-metavariable: $SINK
pattern-sanitizers:
  - patterns:
      - pattern: escape($X)
  - patterns:
      - pattern: sanitize($X)
  - patterns:
      - pattern: $DB.query($QUERY, [...])

步骤 3: 常见规则模板

SQL注入检测

rules:
  - id: sql-injection-string-concat
    message: >
      可能的SQL注入通过字符串拼接。用户输入似乎
      被拼接进SQL查询字符串。使用参数化
      查询代替。
    severity: ERROR
    languages: [javascript, typescript]
    metadata:
      cwe: [CWE-089]
      owasp: [A03:2021]
      confidence: HIGH
      impact: HIGH
      category: security
    patterns:
      - pattern-either:
          - pattern: $DB.query("..." + $VAR + "...")
          - pattern: $DB.query(`...${$VAR}...`)
      - pattern-not: $DB.query("..." + $VAR + "...", [...])
    fix: |
      $DB.query("... $1 ...", [$VAR])

XSS检测

rules:
  - id: xss-innerhtml-assignment
    message: >
      直接将不可信数据赋值给innerHTML。
      对文本使用textContent，对HTML使用净化库。
    severity: ERROR
    languages: [javascript, typescript]
    metadata:
      cwe: [CWE-079]
      owasp: [A03:2021]
      confidence: MEDIUM
      impact: HIGH
      category: security
    pattern-either:
      - pattern: $EL.innerHTML = $DATA
      - pattern: document.getElementById($ID).innerHTML = $DATA

硬编码秘密

rules:
  - id: hardcoded-api-key
    message: >
      检测到硬编码API密钥。将秘密存储在环境
      变量或秘密管理器中。
    severity: ERROR
    languages: [javascript, typescript, python]
    metadata:
      cwe: [CWE-798]
      owasp: [A02:2021]
      confidence: MEDIUM
      impact: HIGH
      category: security
    pattern-either:
      - pattern: |
          $KEY = "AKIA..."
      - pattern: |
          $KEY = "sk-..."
      - pattern: |
          $KEY = "ghp_..."
    pattern-regex: (AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48}|ghp_[a-zA-Z0-9]{36})

缺少认证

rules:
  - id: express-route-missing-auth
    message: >
      Express路由处理程序缺少认证中间件。
      在处理程序前添加认证中间件。
    severity: WARNING
    languages: [javascript, typescript]
    metadata:
      cwe: [CWE-306]
      owasp: [A07:2021]
      confidence: MEDIUM
      impact: HIGH
      category: security
    patterns:
      - pattern-either:
          - pattern: app.post($PATH, function($REQ, $RES) { ... })
          - pattern: app.put($PATH, function($REQ, $RES) { ... })
          - pattern: app.delete($PATH, function($REQ, $RES) { ... })
          - pattern: router.post($PATH, function($REQ, $RES) { ... })
          - pattern: router.put($PATH, function($REQ, $RES) { ... })
          - pattern: router.delete($PATH, function($REQ, $RES) { ... })
      - pattern-not-inside: |
          app.$METHOD($PATH, $AUTH, function($REQ, $RES) { ... })
      - pattern-not-inside: |
          router.$METHOD($PATH, $AUTH, function($REQ, $RES) { ... })

不安全随机性

rules:
  - id: insecure-random-for-security
    message: >
      Math.random() 不是密码学安全的。对于
      安全敏感的随机值，使用
      crypto.getRandomValues() 或 crypto.randomBytes()。
    severity: WARNING
    languages: [javascript, typescript]
    metadata:
      cwe: [CWE-330]
      confidence: MEDIUM
      impact: MEDIUM
      category: security
    patterns:
      - pattern: Math.random()
      - pattern-inside: |
          function $FUNC(...) {
            ...
          }
      - metavariable-regex:
          metavariable: $FUNC
          regex: (generateToken|createSecret|randomPassword|generateKey|createSession|generateId|createNonce)

步骤 4: 编写规则测试

测试文件格式

在规则旁创建测试文件：

// ruleid: sql-injection-string-concat
db.query('SELECT * FROM users WHERE id = ' + userId);
// ruleid: sql-injection-string-concat
db.query(`SELECT * FROM users WHERE id = ${userId}`);
// ok: sql-injection-string-concat
db.query('SELECT * FROM users WHERE id = $1', [userId]);
// ok: sql-injection-string-concat
db.query('SELECT * FROM users WHERE id = ?', [userId]);

运行测试

# 测试单个规则
semgrep --test --config=rules/sql-injection.yml tests/
# 测试所有规则
semgrep --test --config=rules/ tests/
# 验证规则语法
semgrep --validate --config=rules/

步骤 5: 规则优化

性能最佳实践

模式具体化: 避免过于宽泛的匹配，如 $X($Y)
使用模式内部限定范围: 缩小搜索上下文
使用语言特定语法: 利用语言特性
避免深层省略号嵌套: ... ... ... 很慢
使用焦点元变量: 缩小报告位置
用大型代码库测试: 验证规模性能

减少误报

为安全模式添加模式非: 排除已知安全替代方案
使用元变量正则: 约束元变量值
使用模式非内部: 排除安全上下文
设置适当置信度: 诚实检测确定性
添加技术元数据: 帮助用户过滤相关规则
提供修复建议: 如果可能，包括 fix: 字段

规则验证检查清单

[ ] 规则有唯一、描述性ID
[ ] 消息解释问题并修复
[ ] 严重性匹配实际风险
[ ] 元数据包括CWE、OWASP、置信度、影响
[ ] 至少2个真阳性测试用例
[ ] 至少2个真阴性测试用例
[ ] 用 semgrep --validate 验证规则
[ ] 用 semgrep --test 测试规则
[ ] 在大型代码库上性能可接受
[ ] 提供修复建议（如果适用）

</instructions>

Semgrep 模式语法参考

语法	含义	示例
`$X`	单个元变量	`eval($X)`
`$...X`	多个元变量参数	`func($...ARGS)`
`...`	省略号（任意语句）	`if (...) { ... }`
`<... $X ...>`	深层表达式匹配	`<... eval($X) ...>`
`pattern-either`	或操作符	匹配N个模式中的任何
`pattern-not`	非操作符	排除特定模式
`pattern-inside`	上下文要求	必须在此模式内部
`pattern-not-inside`	上下文排除	必须不在此内部
`metavariable-regex`	正则约束	约束 $X 匹配正则
`metavariable-comparison`	数值约束	`$X > 100`
`focus-metavariable`	缩小匹配位置	仅报告 $X 位置

代理集成

security-architect (主要): 安全审计的自定义规则开发
code-reviewer (主要): 自动化代码审查规则编写
penetration-tester (次要): 漏洞检测规则创建
qa (次要): 质量执行规则编写

内存协议（强制）

开始前: 读取 .claude/context/memory/learnings.md 完成后:

新模式 -> .claude/context/memory/learnings.md
发现问题 -> .claude/context/memory/issues.md
决策 -> .claude/context/memory/decisions.md

假设中断: 如果不在内存中，它没发生。

生态系统对齐契约（强制）

此创建器技能是协调创建器生态系统的一部分。这里创建的任何工件必须与相关创建器对齐并验证：

agent-creator 用于所有权和执行路径
skill-creator 用于能力打包和分配
tool-creator 用于可执行自动化表面
hook-creator 用于执行和护栏
rule-creator 和 semgrep-rule-creator 用于策略和静态检查
template-creator 用于标准化脚手架
workflow-creator 用于协调和阶段门控
command-creator 用于用户/操作员命令UX

跨创建器握手（必需）

完成前，验证所有相关握手：

工件路由存在于 .claude/CLAUDE.md 和相关路由文档中。
发现/注册条目已更新（目录/索引/注册表如适用）。
伴生物工创建或明确豁免并附原因。
validate-integration.cjs 对创建的工件通过。
技能索引在技能元数据更改时重新生成。

研究门（Exa 第一，arXiv 备用）

对于新模式、模板或工作流，研究是强制的：

首先使用 Exa 获取实现和生态系统模式。
如果 Exa 不足，使用 WebFetch 加 arXiv 引用。
在工件参考/文档中记录决策、约束和非目标。
保持更新最小，避免过度工程。

回归安全交付

遵循严格 RED -> GREEN -> REFACTOR 进行行为更改。
对更改模块运行目标测试。
对更改文件运行lint/格式。
按关注点限制提交（逻辑/文档/生成工件）。

Semgrep规则创建器Skill semgrep-rule-creator