semgrep-rule-variant-creator

Semgrep 规则变体创建器

将现有 Semgrep 规则移植到新的目标语言，并进行恰当的适用性分析和测试驱动验证。

适用场景

理想场景：

• 将现有 Semgrep 规则移植到一种或多种目标语言
• 为通用漏洞模式创建特定语言的变体
• 扩展规则在多语言代码库中的覆盖范围
• 在具有等效结构的语言之间转换规则

不适用场景

以下情况请勿使用此技能：

• 从头开始创建新的 Semgrep 规则（请改用 semgrep-rule-creator）
• 对代码运行现有规则
• 漏洞模式从根本上不适用于的语言
• 同一语言中的细微语法差异

输入规范

此技能需要：

1. 现有 Semgrep 规则 —— YAML 文件路径或 YAML 规则内容
2. 目标语言 —— 要移植到的一种或多种语言（例如，“Golang 和 Java”）

输出规范

针对每种适用的目标语言，生成：

<original-rule-id>-<language>/
├── <original-rule-id>-<language>.yaml     # Ported Semgrep rule
└── <original-rule-id>-<language>.<ext>    # Test file with annotations

将 sql-injection 移植到 Go 和 Java 的输出示例：

sql-injection-golang/
├── sql-injection-golang.yaml
└── sql-injection-golang.go

sql-injection-java/
├── sql-injection-java.yaml
└── sql-injection-java.java

需要避免的错误判断

移植 Semgrep 规则时，请避免以下常见捷径：

错误判断	失败原因	正确做法
“模式结构完全相同”	不同语言的 AST 各异	始终转储目标语言的 AST
“漏洞相同，检测方式也相同”	不同语言的数据流各异	分析目标语言的惯用写法
“原规则有效，所以不需要测试”	各语言的边缘情况不同	为目标语言编写新的测试用例
“适用性显而易见，可以跳过分析”	有些模式具有语言特异性	先完成适用性分析
“先创建所有变体，再进行测试”	错误会不断累积，难以调试	针对每种语言完成完整流程
“库的等效实现足够接近”	表面相似会掩盖差异	确认 API 语义一致
“只要逐字转换语法即可”	不同语言有不同的惯用写法	研究目标语言的模式

严格程度

此工作流要求严格遵循，不得跳过步骤：

• 必须进行适用性分析：不要假设模式可以直接移植
• 每种语言相互独立：完成完整流程后再处理下一种语言
• 每个变体均采用测试优先：编写测试用例前，绝不编写规则
• 测试必须 100% 通过：“大多数测试通过”不可接受

概述

此技能指导如何为现有 Semgrep 规则创建特定语言的变体。每种目标语言都要独立完成一个包含 4 个阶段的周期：

FOR EACH target language:
  Phase 1: Applicability Analysis → Verdict
  Phase 2: Test Creation (Test-First)
  Phase 3: Rule Creation
  Phase 4: Validation
  (Complete full cycle before moving to next language)

基础知识

semgrep-rule-creator 技能是 Semgrep 规则创建基础知识的权威参考。 此技能侧重于将现有规则移植到新语言，而编写高质量规则的核心原则仍然相同。

有关以下内容，请参阅 semgrep-rule-creator：

• 何时使用污点模式而非模式匹配 —— 根据漏洞类型选择合适的方法
• 测试优先的方法 —— 了解为何测试要先于规则，以及如何编写有效的测试用例
• 需要避免的反模式 —— 常见错误，例如模式过于宽泛或过于具体
• 迭代直至测试通过 —— 验证循环和调试技巧
• 规则优化 —— 测试通过后移除冗余模式

移植规则时，你需要在新的语言环境中应用这些相同的原则。如果不确定规则结构或方法，请先参阅 semgrep-rule-creator。

四阶段工作流

阶段 1：适用性分析

在移植之前，先确定此模式是否适用于目标语言。

分析标准：

1. 目标语言中是否存在这类漏洞？
2. 是否存在等效的构造（函数、模式、库）？
3. 语义是否足够相似，能够进行有意义的检测？

结论选项：

• APPLICABLE → 继续创建变体
• APPLICABLE_WITH_ADAPTATION → 继续，但需要进行重大修改
• NOT_APPLICABLE → 跳过此语言，并记录原因

详细指南请参阅 applicability-analysis.md。

阶段 2：创建测试（测试优先）

始终先编写测试，再编写规则。

创建符合目标语言习惯的测试文件：

• 至少 2 个易受攻击的案例（ruleid:）
• 至少 2 个安全案例（ok:）
• 包含语言特定的边缘案例

// ruleid: sql-injection-golang
db.Query("SELECT * FROM users WHERE id = " + userInput)

// ok: sql-injection-golang
db.Query("SELECT * FROM users WHERE id = ?", userInput)

阶段 3：创建规则

1. 分析 AST：semgrep --dump-ast -l <lang> test-file
2. 转换模式以适配目标语言语法
3. 更新元数据：语言键、消息、规则 ID
4. 适配语言习惯：处理语言特定的构造

转换指南请参阅 language-syntax-guide.md。

阶段 4：验证

# Validate YAML
semgrep --validate --config rule.yaml

# Run tests
semgrep --test --config rule.yaml test-file

检查点：输出必须显示 All tests passed。

调试污点规则：

semgrep --dataflow-traces -f rule.yaml test-file

详细工作流和故障排除信息请参阅 workflow.md。

快速参考

任务	命令
运行测试	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

与规则创建的主要区别

方面	semgrep-rule-creator	此技能
输入	漏洞模式描述	现有规则 + 目标语言
输出	单个规则+测试	多个规则+测试目录
工作流	单次创建周期	每种语言各自独立的周期
阶段 1	问题分析	按语言进行适用性分析
库调研	始终相关	可选（原规则使用库时进行）

文档

必读：移植规则之前，请阅读相关的 Semgrep 文档：

• 规则语法 - YAML 结构和运算符
• 模式语法 - 模式匹配和元变量
• 模式示例 - 各语言的模式参考
• 测试规则 - 测试注解
• Trail of Bits 测试手册 - 高级模式

后续步骤

• 适用性分析指南请参阅 applicability-analysis.md
• 语言转换指南请参阅 language-syntax-guide.md
• 详细工作流和示例请参阅 workflow.md