semgrep-rule-variant-creator

Semgrep ルールのバリアント作成

既存の Semgrep ルールを新しい対象言語に移植し、適用可能性を適切に分析して、テスト駆動で検証します。

使用する場面

最適なシナリオ：

• 既存の Semgrep ルールを 1 つ以上の対象言語に移植する
• 汎用的な脆弱性パターンの言語固有のバリアントを作成する
• 多言語コードベース全体でルールの適用範囲を広げる
• 同等の構文を持つ言語間でルールを変換する

使用しない場面

次の場合は、このスキルを使用しないでください。

• Semgrep ルールをゼロから作成する場合（代わりに semgrep-rule-creator を使用してください）
• 既存のルールをコードに対して実行する場合
• 脆弱性パターンが根本的に適用されない言語の場合
• 同じ言語内での軽微な構文の違いに対応する場合

入力仕様

このスキルには次の情報が必要です。

1. 既存の Semgrep ルール - YAML ファイルのパスまたは YAML ルールの内容
2. 対象言語 - 移植先の言語を 1 つ以上（例：「Golang and 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 の意味論が一致することを確認してください
「構文をそのまま 1 対 1 で変換すればよいです」	言語ごとにイディオムが異なります	対象言語のパターンを調査してください

厳格さのレベル

このワークフローは厳格です。手順を省略しないでください。

• 適用可能性の分析は必須です：パターンを移植できると決めつけないでください
• 各言語は独立しています：次の言語に進む前に、一連の作業を完了してください
• 各バリアントはテストファーストです：テストケースなしでルールを作成しないでください
• テストは 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 を参照してください。

4 フェーズのワークフロー

フェーズ 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 と表示される必要があります。

taint ルールのデバッグ：

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>
taint フローをデバッグ	semgrep --dataflow-traces -f rule.yaml file

ルール作成との主な違い

項目	semgrep-rule-creator	このスキル
入力	バグパターンの説明	既存のルールと対象言語
出力	単一のルールとテスト	複数のルールとテストのディレクトリ
ワークフロー	1 回の作成サイクル	言語ごとの独立したサイクル
フェーズ 1	問題の分析	言語ごとの適用可能性の分析
ライブラリの調査	常に関連あり	任意（元のルールでライブラリを使用している場合）

ドキュメント

必須：ルールを移植する前に、関連する Semgrep のドキュメントを読んでください。

• ルール構文 - YAML の構造と演算子
• パターン構文 - パターンマッチングとメタ変数
• パターンの例 - 言語ごとのパターンリファレンス
• ルールのテスト - テスト用アノテーション
• Trail of Bits テストハンドブック - 高度なパターン

次のステップ

• 適用可能性の分析に関するガイダンスは、applicability-analysis.md を参照してください
• 言語の変換に関するガイダンスは、language-syntax-guide.md を参照してください
• 詳しいワークフローと例については、workflow.md を参照してください