Semgrep セキュリティスキャン

自動言語検出、Task サブエージェントによる並列実行、およびマージされた SARIF 出力を備えた Semgrep スキャンを実行します。

必須原則

1. 常に --metrics=off を使用する — Semgrep はデフォルトでテレメトリを送信します。--config auto もホームに通信します。セキュリティ監査中のデータ漏洩を防ぐため、すべての semgrep コマンドに --metrics=off を含める必要があります。
2. ユーザーはスキャン計画を承認する必要があります（ステップ3は硬いゲートです） — 元の「このコードベースをスキャンして」というリクエストは承認ではありません。正確なルールセット、ターゲット、エンジン、およびモードを提示し、スキャナーを生成する前に明示的な「yes」/「proceed」を待ってください。
3. サードパーティ製ルールセットは必須、オプションではありません — Trail of Bits、0xdea、および Decurity ルールは、公式レジストリにない脆弱性を検出します。検出された言語が一致する場合は、常にこれらを含めてください。
4. すべてのスキャンタスクを1つのメッセージで生成する — 並列実行はコアなパフォーマンス上の利点です。タスクを順次生成しないでください。常に1つのレスポンスで すべてのタスク ツール呼び出しを発行してください。
5. スキャン前に必ず Semgrep Pro を確認する — Pro はファイル間タイント追跡を有効にし、約250% 多くの真の陽性を検出します。確認をスキップすると、重大なファイル間の脆弱性を静かに見逃すことになります。

使用場面

• コードベースのセキュリティ監査
• コードレビュー前の脆弱性検出
• 既知のバグパターンのスキャン
• 初回の静的解析

使用しない場面

• バイナリ解析 → バイナリ解析ツールを使用
• 既に Semgrep CI を構成している → 既存パイプラインを使用
• ファイル間解析が必要だが Pro ライセンスがない → CodeQL を代わりに検討
• カスタム Semgrep ルールを作成 → semgrep-rule-creator スキルを使用
• 既存ルールを他の言語に移植 → semgrep-rule-variant-creator スキルを使用

出力ディレクトリ

すべてのスキャン結果、SARIF ファイル、および一時データは、単一の出力ディレクトリに保存されます。

• ユーザーがプロンプトで出力ディレクトリを指定した場合、それを OUTPUT_DIR として使用します。
• 指定しない場合、デフォルトは ./static_analysis_semgrep_1 です。既に存在する場合は、_2、_3 などにインクリメントします。

どちらの場合も、常にディレクトリを作成して mkdir -p でファイルを書き込む前に作成してください。

# 出力ディレクトリを解決
if [ -n "$USER_SPECIFIED_DIR" ]; then
  OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
  BASE="static_analysis_semgrep"
  N=1
  while [ -e "${BASE}_${N}" ]; do
    N=$((N + 1))
  done
  OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR/raw" "$OUTPUT_DIR/results"

出力ディレクトリはステップ1の開始時に 一度だけ 解決され、その後のすべてのステップ全体で使用されます。

$OUTPUT_DIR/
├── rulesets.txt                 # 承認されたルールセット（ステップ3後にログされる）
├── raw/                         # スキャンごとの生出力（未フィルタリング）
│   ├── python-python.json
│   ├── python-python.sarif
│   ├── python-django.json
│   ├── python-django.sarif
│   └── ...
└── results/                     # 最終的なマージ出力
    └── results.sarif

前提条件

必須： Semgrep CLI（semgrep --version）。インストールされていない場合は、Semgrep インストールドキュメントを参照してください。

オプション： Semgrep Pro — ファイル間タイント追跡、手続き間分析、および追加言語（Apex、C#、Elixir）を有効にします。確認方法：

semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro available" || echo "OSS only"

制限事項： OSS モードはファイル間のデータフロー追跡ができません。Pro モードはファイル間解析のために -j 1 を使用します（ルールセットごとには遅いですが、並列ルールセットが補います）。

スキャンモード

ワークフローのステップ2でモードを選択します。モードはスキャナーフラグと後処理の両方に影響します。

モード	カバレッジ	報告される検出結果
Run all	すべてのルールセット、すべての重大度レベル	すべて
Important only	すべてのルールセット、事前および事後フィルタリング	セキュリティ脆弱性のみ、中～高信頼度/影響

Important only は2つのフィルタレイヤーを適用します：

1. 事前フィルタ： --severity MEDIUM --severity HIGH --severity CRITICAL（CLI フラグ）
2. 事後フィルタ： JSON メタデータ — category=security、confidence∈{MEDIUM,HIGH}、impact∈{MEDIUM,HIGH} のみを保持

scan-modes.md でメタデータ基準と jq フィルタコマンドを参照してください。

オーケストレーションアーキテクチャ

┌──────────────────────────────────────────────────────────────────┐
│ メインエージェント（このスキル）                                │
│ ステップ1：言語検出 + Pro 可用性確認                            │
│ ステップ2：スキャンモード + ルールセット選択（参照：rulesets.md）│
│ ステップ3：計画 + ルールセット提示、承認取得 [⛔ 硬いゲート]     │
│ ステップ4：並列スキャンタスク生成（承認ルールセット + モード）   │
│ ステップ5：結果をマージして報告                                 │
└──────────────────────────────────────────────────────────────────┘
         │ ステップ4
         ▼
┌─────────────────┐
│ スキャンタスク  │
│ （並列）        │
├─────────────────┤
│ Python スキャナ │
│ JS/TS スキャナ  │
│ Go スキャナ     │
│ Docker スキャナ │
└─────────────────┘

ワークフロー

scan-workflow.md の詳細ワークフローに従ってください。 概要：

ステップ	アクション	ゲート	主要参照
1	出力ディレクトリ解決、言語検出 + Pro 可用性確認	—	Glob を使用、Bash ではなく
2	スキャンモード + ルールセット選択	—	rulesets.md
3	計画提示、明示的な承認取得	⛔ 硬い	AskUserQuestion
4	並列スキャンタスク生成	—	scanner-task-prompt.md
5	結果をマージして報告	—	マージスクリプト（下記）

タスク実行： 呼び出し時、5つのタスクを blockedBy 依存関係で作成します（各ステップが前のものをブロック）。ステップ3は硬いゲートです — ユーザーが明示的に承認した後にのみ完了にマークしてください。

マージコマンド（ステップ5）：

uv run {baseDir}/scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif

エージェント

エージェント	ツール	目的
static-analysis:semgrep-scanner	Bash	言語カテゴリの並列 semgrep スキャンを実行

ステップ4で Task サブエージェントを生成するときに、subagent_type: static-analysis:semgrep-scanner を使用します。

却下する正当化

ショートカット	なぜ間違いか
「ユーザーがスキャンを求めた、それは承認」	元々のリクエスト ≠ 計画承認。計画を提示し、AskUserQuestion を使用して、明示的な「yes」を待つ
「ステップ3タスクはブロッキングなので、ただ完了にマーク」	タスク状態について嘘をつくと実行を無効にします。実際の承認後にのみ完了にマークしてください
「既に彼らが何を望んでいるか知っている」	仮定により間違ったディレクトリ/ルールセットをスキャンします。確認のため計画を提示してください
「デフォルトルールセットを使用するだけ」	ユーザーはスキャン前に正確なルールセットを確認して承認する必要があります
「承認なしに追加ルールセットを追加」	同意なしに承認されたリストを変更すると信頼が損なわれます
「サードパーティ製ルールセットはオプション」	Trail of Bits、0xdea、Decurity は公式レジストリにない脆弱性を検出します — 必須です
「--config auto を使用」	メトリクスを送信します。ルールセットの制御が少ないです
「1回に1つのタスク」	並列処理を無効にします。常にすべてのタスクを一緒に生成してください
「Pro は遅い、--pro をスキップ」	ファイル間解析は真の陽性を250% 多く検出します。時間に見合う価値があります
「Semgrep は GitHub URL をネイティブに処理」	非標準YAML を持つリポジトリで URL 処理が失敗します。常に最初にクローンしてください
「クリーンアップはオプション」	クローンされたリポジトリはユーザーのワークスペースを汚し、実行全体に蓄積します
「. または相対パスをターゲットとして使用」	サブエージェントは曖昧性を避けるため絶対パスが必要です
「後からユーザーに出力ディレクトリを選ばせる」	出力ディレクトリはステップ1で解決される必要があります。ファイルが作成される前に

リファレンスインデックス

ファイル	コンテンツ
rulesets.md	完全なルールセットカタログと選択アルゴリズム
scan-modes.md	事前/事後フィルタ基準と jq コマンド
scanner-task-prompt.md	スキャナーサブエージェント生成のテンプレート

ワークフロー	目的
scan-workflow.md	完全な5ステップスキャン実行プロセス

成功基準

• 出力ディレクトリが解決されている（ユーザー指定またはオート増分デフォルト）
• すべての生成ファイルが $OUTPUT_DIR 内に保存されている
• 言語がファイル数とともに検出され、Pro ステータスが確認されている
• スキャンモードがユーザーによって選択されている（run all / important only）
• ルールセットに検出されたすべての言語のサードパーティ製ルールが含まれている
• ユーザーがスキャン計画を明示的に承認している（ステップ3ゲート合格）
• すべてのスキャンタスクが1つのメッセージで生成され完了している
• すべての semgrep コマンドが --metrics=off を使用している
• 承認されたルールセットが $OUTPUT_DIR/rulesets.txt にログされている
• スキャンごとの生出力が $OUTPUT_DIR/raw/ に保存されている
• results.sarif が $OUTPUT_DIR/results/ に存在し、有効な JSON である
• Important only モード：マージ前に事後フィルタを適用。未フィルタリング結果は raw/ に保存
• 重大度とカテゴリ分類による結果サマリーが報告されている
• クローンされたリポジトリ（存在する場合）が $OUTPUT_DIR/repos/ からクリーンアップされている