semgrep

Semgrep セキュリティスキャン

言語を自動検出して Semgrep スキャンを実行します。ホストが委任に対応している場合はサブエージェントで並列実行し、対応していない場合は順次スキャンします。SARIF 出力は統合されます。

基本原則

1. 必ず --metrics=off を使用してください — Semgrep はデフォルトでテレメトリーを送信します。また、--config auto も外部に接続します。セキュリティ監査中のデータ漏えいを防ぐため、すべての semgrep コマンドに --metrics=off を含めてください。
2. スキャン計画について、ユーザーの承認が必要です（ステップ 3 は必須の承認ゲートです） — 「このコードベースをスキャンしてください」という最初の依頼は、承認にはなりません。正確なルールセット、対象、エンジン、モードを提示し、スキャナーを起動する前に、明示的な「はい」または「進めてください」という返答を待ってください。
3. サードパーティ製ルールセットは任意ではなく必須です — Trail of Bits、0xdea、Decurity のルールは、公式レジストリにはない脆弱性を検出します。検出された言語に合致する場合は、必ず含めてください。
4. ホストがサブエージェントへの委任に対応している場合は、すべてのスキャンを同時に開始してください — 言語／カテゴリごとの並列実行が、パフォーマンス上の主な利点です。ホストにサブエージェントや並列タスクの仕組みがない場合は、タスクを一つずつ実行せず、スキャンを順次実行してください。
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 でディレクトリを作成してください。

# Resolve output directory
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                 # Approved rulesets (logged after Step 3)
├── raw/                         # Per-scan raw output (unfiltered)
│   ├── python-python.json
│   ├── python-python.sarif
│   ├── python-django.json
│   ├── python-django.sarif
│   └── ...
└── results/                     # Final merged output
    └── 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 でモードを選択してください。モードはスキャナーのフラグと後処理の両方に影響します。

モード	カバレッジ	報告される検出結果
すべて実行	すべてのルールセット、すべての重大度	すべて
重要な項目のみ	すべてのルールセット（事前および事後フィルター適用）	セキュリティ脆弱性のみ、中～高の確信度／影響度

重要な項目のみでは、次の 2 段階のフィルターを適用します。

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

メタデータの判定基準と jq フィルターコマンドについては、scan-modes.md を参照してください。

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

┌──────────────────────────────────────────────────────────────────┐
│ MAIN AGENT (this skill)                                          │
│ Step 1: Detect languages + check Pro availability                │
│ Step 2: Select scan mode + rulesets (ref: rulesets.md)           │
│ Step 3: Present plan + rulesets, get approval [⛔ HARD GATE]     │
│ Step 4: Run one scan per language/category (parallel if the      │
│         host supports subagent delegation, else sequential)      │
│ Step 5: Merge results and report                                 │
└──────────────────────────────────────────────────────────────────┘
         │ Step 4
         ▼
┌─────────────────┐
│ Per-language    │
│ scan            │
├─────────────────┤
│ Python scanner  │
│ JS/TS scanner   │
│ Go scanner      │
│ Docker scanner  │
└─────────────────┘

ワークフロー

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

ステップ	アクション	ゲート	主な参照先
1	出力ディレクトリを解決し、言語と Pro の利用可否を検出する	—	Bash ではなく Glob を使用する
2	スキャンモードとルールセットを選択する	—	rulesets.md
3	計画を提示し、明示的な承認を得る	⛔ HARD	ユーザーに直接尋ねるか、ホストに構造化された質問ツールがある場合はそれを使用する
4	言語／カテゴリごとにスキャンを1回実行する	—	scanner-task-prompt.md — サブエージェントに処理を委任するホスト向けのプロンプトテンプレートです。それ以外の場合は同じ手順を直接実行してください
5	結果を統合して報告する	—	統合スクリプト（以下）

遵守事項： 5つのステップを依存関係の連鎖として追跡し（各ステップが次のステップをブロックします）、利用可能であればホストのタスク追跡ツールを使用してください。ステップ3は HARD GATE です。ユーザーが計画を明示的に承認するまで、ステップ4に進まないでください。

統合コマンド（ステップ5）：

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

退けるべき合理化

近道	それが誤りである理由
「ユーザーがスキャンを依頼した。それが承認だ」	元の依頼は計画の承認ではありません。計画を提示し、AskUserQuestion を使用して、明示的な「はい」を待ってください
「ステップ3のタスクがブロック中なので、完了扱いにすればよい」	タスクのステータスを偽ると、遵守の仕組みが機能しなくなります。実際に承認を得た後にのみ完了扱いにしてください
「ユーザーが何を望んでいるか、すでに分かっている」	思い込みにより、誤ったディレクトリやルールセットをスキャンすることになります。確認のために計画を提示してください
「デフォルトのルールセットを使えばよい」	スキャン前に、正確なルールセットをユーザーに提示して承認を得る必要があります
「追加のルールセットを尋ねずに加える」	承諾を得たリストを同意なく変更すると、信頼を損ないます
「サードパーティのルールセットは任意だ」	Trail of Bits、0xdea、Decurity は公式レジストリにない脆弱性を検出します。必須です
「--config auto を使う」	メトリクスが送信され、ルールセットの制御性が低下します
「並列実行が可能でも、一度に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 ステータスが確認されている
• スキャンモードがユーザーによって選択されている（すべて実行／重要なもののみ）
• 検出されたすべての言語について、ルールセットにサードパーティ製ルールが含まれている
• ユーザーがスキャン計画を明示的に承認している（Step 3 のゲートを通過済み）
• 言語ごとのスキャンがすべて並行して（ホストが委任に対応していない場合は順次）開始され、完了している
• すべての semgrep コマンドで --metrics=off が使用されている
• 承認済みのルールセットが $OUTPUT_DIR/rulesets.txt に記録されている
• スキャンごとの生出力が $OUTPUT_DIR/raw/ に保存されている
• $OUTPUT_DIR/results/ に results.sarif が存在し、有効な JSON である
• 重要なもののみモードでは、マージ前に事後フィルターが適用されている。フィルター前の結果は raw/ に保持されている
• 重要度とカテゴリ別の内訳を含む結果の概要が報告されている
• クローンしたリポジトリ（存在する場合）が $OUTPUT_DIR/repos/ から削除されている