semgrep-rule-variant-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Semgrep Rule Variant Creator

Semgrep规则变体生成工具

Port existing Semgrep rules to new target languages with proper applicability analysis and test-driven validation.

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

When to Use

适用场景

Ideal scenarios:

Porting an existing Semgrep rule to one or more target languages
Creating language-specific variants of a universal vulnerability pattern
Expanding rule coverage across a polyglot codebase
Translating rules between languages with equivalent constructs

理想场景：

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

When NOT to Use

不适用场景

Do NOT use this skill for:

Creating a new Semgrep rule from scratch (use
```
semgrep-rule-creator
```
instead)
Running existing rules against code
Languages where the vulnerability pattern fundamentally doesn't apply
Minor syntax variations within the same language

请勿将此技能用于：

从零开始创建新的Semgrep规则（请改用
```
semgrep-rule-creator
```
）
针对代码运行现有规则
漏洞模式根本不适用的语言
同一语言内的微小语法变体

Input Specification

输入规范

This skill requires:

Existing Semgrep rule - YAML file path or YAML rule content
Target languages - One or more languages to port to (e.g., "Golang and Java")

此技能需要：

现有Semgrep规则 - YAML文件路径或YAML规则内容
目标语言 - 要移植到的一种或多种语言（例如："Golang和Java"）

Output Specification

输出规范

For each applicable target language, produces:

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

Example output for porting

sql-injection

to Go and Java:

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

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

对于每个适用的目标语言，生成：

<original-rule-id>-<language>/
├── <original-rule-id>-<language>.yaml     # 移植后的Semgrep规则
└── <original-rule-id>-<language>.<ext>    # 带注释的测试文件

将

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

Rationalizations to Reject

需避免的错误理由

When porting Semgrep rules, reject these common shortcuts:

Rationalization	Why It Fails	Correct Approach
"Pattern structure is identical"	Different ASTs across languages	Always dump AST for target language
"Same vulnerability, same detection"	Data flow differs between languages	Analyze target language idioms
"Rule doesn't need tests since original worked"	Language edge cases differ	Write NEW test cases for target
"Skip applicability - it obviously applies"	Some patterns are language-specific	Complete applicability analysis first
"I'll create all variants then test"	Errors compound, hard to debug	Complete full cycle per language
"Library equivalent is close enough"	Surface similarity hides differences	Verify API semantics match
"Just translate the syntax 1:1"	Languages have different idioms	Research target language patterns

移植Semgrep规则时，需拒绝以下常见的捷径：

错误理由	失败原因	正确做法
"模式结构完全相同"	不同语言的AST不同	始终导出目标语言的AST
"相同漏洞，相同检测方式"	不同语言的数据流不同	分析目标语言的惯用写法
"原规则有效，所以新规则不需要测试"	不同语言的边缘情况不同	为目标语言编写新的测试用例
"跳过适用性分析 - 显然适用"	某些模式是语言特定的	先完成适用性分析
"先创建所有变体再测试"	错误会叠加，难以调试	为每种语言完成完整周期后再进行下一个
"库的等效实现足够接近"	表面相似隐藏了差异	验证API语义是否匹配
"直接1:1翻译语法"	不同语言有不同的惯用写法	研究目标语言的模式

Strictness Level

严格性要求

This workflow is strict - do not skip steps:

Applicability analysis is mandatory: Don't assume patterns translate
Each language is independent: Complete full cycle before moving to next
Test-first for each variant: Never write a rule without test cases
100% test pass required: "Most tests pass" is not acceptable

此工作流是严格的 - 请勿跳过步骤：

必须进行适用性分析：不要假设模式可以直接移植
每种语言独立处理：完成完整周期后再处理下一种语言
为每个变体采用测试优先的方法：永远不要在没有测试用例的情况下编写规则
必须100%通过测试："大部分测试通过"是不被接受的

Overview

概述

This skill guides the creation of language-specific variants of existing Semgrep rules. Each target language goes through an independent 4-phase cycle:

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规则的特定语言变体。每种目标语言都要经过独立的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)

Foundational Knowledge

基础知识

The
semgrep-rule-creator
skill is the authoritative reference for Semgrep rule creation fundamentals. While this skill focuses on porting existing rules to new languages, the core principles of writing quality rules remain the same.

Consult

semgrep-rule-creator

for guidance on:

When to use taint mode vs pattern matching - Choosing the right approach for the vulnerability type
Test-first methodology - Why tests come before rules and how to write effective test cases
Anti-patterns to avoid - Common mistakes like overly broad or overly specific patterns
Iterating until tests pass - The validation loop and debugging techniques
Rule optimization - Removing redundant patterns after tests pass

When porting a rule, you're applying these same principles in a new language context. If uncertain about rule structure or approach, refer to

semgrep-rule-creator

first.

semgrep-rule-creator
技能是Semgrep规则创建基础的权威参考。虽然此技能专注于将现有规则移植到新语言，但编写高质量规则的核心原则保持不变。

如需以下指导，请参考

semgrep-rule-creator

：

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

移植规则时，你是在新的语言环境中应用这些相同的原则。如果对规则结构或方法不确定，请先参考

semgrep-rule-creator

。

Four-Phase Workflow

四阶段工作流

Phase 1: Applicability Analysis

阶段1：适用性分析

Before porting, determine if the pattern applies to the target language.

Analysis criteria:

Does the vulnerability class exist in the target language?
Does an equivalent construct exist (function, pattern, library)?
Are the semantics similar enough for meaningful detection?

Verdict options:

```
APPLICABLE
```
→ Proceed with variant creation
```
APPLICABLE_WITH_ADAPTATION
```
→ Proceed but significant changes needed
```
NOT_APPLICABLE
```
→ Skip this language, document why

See applicability-analysis.md for detailed guidance.

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

分析标准：

目标语言中是否存在此类漏洞？
是否存在等效的语法结构（函数、模式、库）？
语义是否足够相似，以实现有意义的检测？

结论选项：

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

有关详细指导，请参阅applicability-analysis.md。

Phase 2: Test Creation (Test-First)

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

Always write tests before the rule.

Create test file with target language idioms:

Minimum 2 vulnerable cases (
```
ruleid:
```
)
Minimum 2 safe cases (
```
ok:
```
)
Include language-specific edge cases

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

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

始终在编写规则之前编写测试。

创建包含目标语言惯用写法的测试文件：

至少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)

Phase 3: Rule Creation

阶段3：规则创建

Analyze AST:
```
semgrep --dump-ast -l <lang> test-file
```
Translate patterns to target language syntax
Update metadata: language key, message, rule ID
Adapt for idioms: Handle language-specific constructs

See language-syntax-guide.md for translation guidance.

分析AST：
```
semgrep --dump-ast -l <lang> test-file
```
将模式翻译为目标语言语法
更新元数据：language键、消息、规则ID
适配惯用写法：处理特定语言的语法结构

有关翻译指导，请参阅language-syntax-guide.md。

Phase 4: Validation

阶段4：验证

bash

undefined

bash

undefined

Validate YAML

验证YAML

semgrep --validate --config rule.yaml

Run tests

运行测试

semgrep --test --config rule.yaml test-file


**Checkpoint**: Output MUST show `All tests passed`.

For taint rule debugging:
```bash
semgrep --dataflow-traces -f rule.yaml test-file

See workflow.md for detailed workflow and troubleshooting.

semgrep --test --config rule.yaml test-file


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

如需调试污点规则：
```bash
semgrep --dataflow-traces -f rule.yaml test-file

有关详细工作流和故障排除，请参阅workflow.md。

Quick Reference

快速参考

Task	Command
Run tests	`semgrep --test --config rule.yaml test-file`
Validate YAML	`semgrep --validate --config rule.yaml`
Dump AST	`semgrep --dump-ast -l <lang> <file>`
Debug taint flow	`semgrep --dataflow-traces -f rule.yaml file`

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

Key Differences from Rule Creation

与规则创建的主要区别

Aspect	semgrep-rule-creator	This skill
Input	Bug pattern description	Existing rule + target languages
Output	Single rule+test	Multiple rule+test directories
Workflow	Single creation cycle	Independent cycle per language
Phase 1	Problem analysis	Applicability analysis per language
Library research	Always relevant	Optional (when original uses libraries)

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

Documentation

文档

REQUIRED: Before porting rules, read relevant Semgrep documentation:

Rule Syntax - YAML structure and operators
Pattern Syntax - Pattern matching and metavariables
Pattern Examples - Per-language pattern references
Testing Rules - Testing annotations
Trail of Bits Testing Handbook - Advanced patterns

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

Rule Syntax - YAML结构和运算符
Pattern Syntax - 模式匹配和元变量
Pattern Examples - 各语言的模式参考
Testing Rules - 测试注释
Trail of Bits Testing Handbook - 高级模式

Next Steps

下一步

For applicability analysis guidance, see applicability-analysis.md
For language translation guidance, see language-syntax-guide.md
For detailed workflow and examples, see workflow.md

如需适用性分析指导，请参阅applicability-analysis.md
如需语言翻译指导，请参阅language-syntax-guide.md
如需详细工作流和示例，请参阅workflow.md