semgrep-rule-creator

Semgrep ルール作成

適切なテストと検証を行い、本番環境で使える品質の Semgrep ルールを作成します。

使用する場面

最適なシナリオ：

• 特定のバグパターンを検出する Semgrep ルールを作成する場合
• コードベース内のセキュリティ脆弱性を検出するルールを作成する場合
• データフローの脆弱性に対応する taint mode ルールを作成する場合
• コーディング規約を適用するルールを作成する場合

使用しない場面

以下の用途には、このスキルを使用しないでください。

• 既存の Semgrep ルールセットを実行する場合
• カスタムルールを使わずに一般的な静的解析を行う場合（static-analysis スキルを使用してください）

退けるべき合理化

Semgrep ルールを作成する際は、次のようなよくある近道を退けてください。

• 「パターンは完成しているように見える」 → それでも semgrep --test --config <rule-id>.yaml <rule-id>.<ext> を実行して検証してください。テストされていないルールには、見えにくい誤検出や見逃しがあります。
• 「脆弱なケースには一致する」 → 脆弱性に一致することは作業の半分にすぎません。安全なケースには一致しないことも確認してください（誤検出があると信頼を損ないます）。
• 「このケースに taint mode は過剰だ」 → ユーザー入力から危険なシンクへデータが流れる場合、taint mode を使うとパターンマッチングより高い精度が得られます。
• 「テストは1つで十分だ」 → コーディングスタイルの違い、サニタイズ済みの入力、安全な代替手段、境界条件などのエッジケースも含めてください。
• 「まずパターンを最適化する」 → まず正しいパターンを書き、すべてのテストに合格してから最適化してください。早まった最適化は回帰を引き起こします。
• 「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%が必須：「ほとんどのテストに合格」は認められません
• 最適化は最後に行う：すべてのテストに合格してから、パターンを簡素化してください
• 汎用的なパターンを避ける：ルールは具体的でなければならず、広範なパターンに一致してはいけません
• taint mode を優先する：データフローの脆弱性に対して使用してください
• YAML ファイル1つにつき Semgrep ルールは1つ：各 YAML ファイルに含める Semgrep ルールは1つだけにしてください。1つのファイルに複数のルールをまとめないでください
• 汎用ルールは禁止：Semgrep ルールの対象言語を指定する場合、汎用的なパターンマッチング（languages: generic）は避けてください
• todook および todoruleid のテスト注釈は禁止：将来のルール改善を目的としたテストファイル内の todoruleid: <rule-id> および todook: <rule-id> 注釈は禁止されています

概要

このスキルでは、セキュリティ脆弱性やコードパターンを検出する Semgrep ルールの作成方法を説明します。ルールは反復的に作成します。問題を分析し、まずテストを書き、AST 構造を分析してからルールを作成し、すべてのテストに合格するまで反復し、最後にルールを最適化します。

アプローチの選択：

• taint mode（優先）：信頼できない入力が危険なシンクに到達するデータフローの問題
• パターンマッチング：データフローの要件がない単純な構文パターン

taint mode を優先する理由：パターンマッチングでは構文は見つけられますが、コンテキストは見逃します。パターン eval($X) は、eval(user_input)（脆弱）と eval("safe_literal")（安全）の両方に一致します。taint mode はデータフローを追跡するため、信頼できないデータが実際にシンクに到達した場合にのみ警告します。これにより、インジェクションの脆弱性における誤検出を大幅に減らせます。

アプローチ間の切り替え：試行錯誤してかまいません。taint mode から始めてうまく機能しない場合（たとえば、taint が想定どおりに伝播しない、誤検出や見逃しが多すぎる場合）は、パターンマッチングに切り替えてください。逆に、パターンマッチングで安全なケースに対する誤検出が多すぎる場合は、taint mode を試してください。目標は機能するルールを作ることであり、どちらか一方のアプローチに固執することではありません。

出力構成 - ルール 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>

クイックリファレンス

• コマンド、パターン演算子、taint モードの構文については、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 を使って Semgrep のドキュメントにある以下の7つのリンクをすべて読んでください。

1. ルールの構文
2. パターンの構文
3. ルールのテスト
4. taint 分析
5. taint 分析の高度な手法
6. 定数伝播
7. Trail of Bits Testing Handbook - Semgrep の章