CodeQL 分析

対応言語: Python、JavaScript/TypeScript、Go、Java/Kotlin、C/C++、C#、Ruby、Swift。

スキルリソース: リファレンスファイルとテンプレートは {baseDir}/references/ および {baseDir}/workflows/ に配置されています。

重要な原則

1. データベースの品質は譲歩の余地がない。 データベースがビルドできたからといって自動的に良いわけではありません。常に品質評価 (ファイル数、ベースライン LoC、エクストラクタエラー) を実施し、予期されるソースファイルと比較してください。キャッシュされたビルドは有用な抽出をもたらしません。

2. データ拡張機能は CodeQL が見落とすものを検出します。 Django、Spring、Express などの標準フレームワークを使用しているプロジェクトでさえ、データベース呼び出し、リクエスト解析、またはシェル実行の周辺にカスタムラッパーがあります。create-data-extensions ワークフローをスキップすると、プロジェクト固有のコードパスの脆弱性を見落とします。

3. 明示的なスイートリファレンスはサイレントなクエリドロップを防止します。 パック名を直接 codeql database analyze に渡してはいけません。各パックの defaultSuiteFile は隠されたフィルタを適用し、ゼロの結果を生成することができます。常にカスタム .qls スイートファイルを生成してください。

4. ゼロの検出は祝賀ではなく調査が必要です。 ゼロの結果は、データベース品質の低さ、モデルの欠落、間違ったクエリパック、またはサイレントなスイートフィルタリングを示す可能性があります。クリーンとして報告する前に調査してください。

5. macOS Apple Silicon は compiled languages に対する回避策が必要です。 終了コード 137 は arm64e/arm64 のミスマッチであり、ビルド失敗ではありません。build-mode=none にフォールバックする前に、Homebrew arm64 ツールまたは Rosetta を試してください。

6. ワークフローはステップバイステップで従うこと。 ワークフローが選択されたら、フェーズをスキップせずにステップバイステップで実行してください。各フェーズは次のゲートになります。品質評価またはデータ拡張をスキップすると、不完全な分析につながります。

出力ディレクトリ

生成されたすべてのファイル (データベース、ビルドログ、診断、拡張機能、結果) は、単一の出力ディレクトリに保存されます。

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

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

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

出力ディレクトリは、開始時に一度だけ 解決されます。その後、すべてのワークフロー実行前に。すべてのワークフローが $OUTPUT_DIR を受け取り、そこにアーティファクトを保存します:

$OUTPUT_DIR/
├── rulesets.txt                 # 選択されたクエリパック (Step 3 の後にログ出力)
├── codeql.db/                   # CodeQL データベース (codeql-database.yml を含むディレクトリ)
├── build.log                    # ビルドログ
├── codeql-config.yml            # 除外設定 (interpreted languages)
├── diagnostics/                 # 診断クエリと CSV
├── extensions/                  # データ拡張 YAML
├── raw/                         # フィルタ不使用の分析出力
│   ├── results.sarif
│   └── <mode>.qls
└── results/                     # 最終結果 (important-only 用にフィルタ、run-all 用にコピー)
    └── results.sarif

データベースの発見

CodeQL データベースは、そのディレクトリ内に codeql-database.yml マーカーファイルがあることで識別されます。既存のデータベースを検索するときは、常にすべてのマッチを収集してください。以前の実行や異なる言語からの複数のデータベースが存在する可能性があります。

発見コマンド:

# すべての CodeQL データベースを検索 (トップレベルと 1 つ下のサブディレクトリ)
find . -maxdepth 3 -name "codeql-database.yml" -not -path "*/\.*" 2>/dev/null \
  | while read -r yml; do dirname "$yml"; done

• $OUTPUT_DIR 内: find "$OUTPUT_DIR" -maxdepth 2 -name "codeql-database.yml"
• プロジェクト全体 (自動検出用): find . -maxdepth 3 -name "codeql-database.yml" — プロジェクトトップレベル (./db-name/) と 1 つ下のサブディレクトリ (./subdir/db-name/) のデータベースをカバーします。さらに深く検索しません。

データベースの名前が codeql.db であると仮定しないでください。マーカーファイルで発見してください。

複数のデータベースが見つかった場合:

発見されたデータベースごとにメタデータを収集して、ユーザーが選択できるようにします:

# 各データベースについて、言語と作成時刻を抽出
for db in $FOUND_DBS; do
  CODEQL_LANG=$(codeql resolve database --format=json -- "$db" 2>/dev/null | jq -r '.languages[0]')
  CREATED=$(grep '^creationMetadata:' -A5 "$db/codeql-database.yml" 2>/dev/null | grep 'creationTime' | awk '{print $2}')
  echo "$db — language: $CODEQL_LANG, created: $CREATED"
done

その後、AskUserQuestion を使用してユーザーが使用するデータベースを選択できるようにします。また、新しく構築するオプションも用意します。ユーザーが明示的にプロンプトで使用するデータベースまたは新規構築を指定した場合は、AskUserQuestion をスキップしてください。

クイックスタート

一般的なケース ("脆弱性についてこのコードベースをスキャンする"):

# 1. CodeQL がインストールされているか確認
if ! command -v codeql >/dev/null 2>&1; then
  echo "NOT INSTALLED: codeql binary not found on PATH"
else
  codeql --version || echo "ERROR: codeql found but --version failed (check installation)"
fi

# 2. 出力ディレクトリを解決
BASE="static_analysis_codeql"; N=1
while [ -e "${BASE}_${N}" ]; do N=$((N + 1)); done
OUTPUT_DIR="${BASE}_${N}"; mkdir -p "$OUTPUT_DIR"

その後、フルパイプラインを実行: データベースをビルド → データ拡張機能を作成 → 分析を実行 (下のワークフロー参照)。

使用時期

• データフロー分析を用いたコードベースのセキュリティ脆弱性スキャン
• compiled languages のビルド機能を使った CodeQL データベースの構築
• 手続き間のタイント追跡や AST/CFG 分析が必要な複雑な脆弱性の検出
• 複数のクエリパックを使用した包括的なセキュリティ監査

使用しない時期

• カスタムクエリの作成 - 専用のクエリ開発スキルを使用
• CI/CD 統合 - GitHub Actions ドキュメントを直接使用
• 高速パターン検索 - 速度のために Semgrep または grep を使用
• compiled languages でのビルド機能がない - Semgrep を検討
• 単一ファイルまたは軽量な分析 - シンプルなパターンマッチングは Semgrep の方が高速

却下する合理化

これらのショートカットは検出漏れにつながります。受け入れないでください:

• "security-extended で十分" - これはベースラインです。Trail of Bits パックとコミュニティパックが言語に利用可能かどうかを常に確認してください。これらは security-extended が完全に見逃すカテゴリを検出します。
• "security-and-quality が最も広いスイート" - security-and-quality はすべての experimental/ クエリパスを除外します。run-all モードでは、security-and-quality と security-experimental の両方をインポートしてください。差分は言語に応じて 1～52 クエリです。
• "データベースはビルドされたから良い" - データベースがビルドされたからといって、良く抽出されたわけではありません。常に品質評価を実施し、ファイル数を予期されるソースファイルと比較してください。
• "標準フレームワークではデータ拡張は不要" - Django/Spring アプリでさえ、CodeQL がモデル化しないカスタムラッパーがあります。拡張をスキップすると脆弱性を見落とします。
• "compiled languages には build-mode=none で十分" - 非常に不完全な分析を生成します。絶対に必要な最後の手段としてのみ使用してください。macOS では、arm64 ツールチェーンの回避策または Rosetta を最初に試してください。
• "macOS でビルドが失敗する、ちょうど build-mode=none を使う" - 終了コード 137 は arm64e/arm64 ミスマッチが原因であり、根本的なビルド失敗ではありません。macos-arm64e-workaround.md を参照。
• "検出がないということはコードが安全" - ゼロの検出は、データベース品質の低さ、モデルの欠落、または間違ったクエリパックを示す可能性があります。クリーン結果として報告する前に調査してください。
• "デフォルトスイートを実行するだけ" / "パック名を直接渡すだけ" - 各パックの defaultSuiteFile は隠されたフィルタを適用し、ゼロの結果を生成する可能性があります。常に明示的なスイートリファレンスを使用してください。
• "ファイルを現在のディレクトリに配置するだけ" - 生成されたすべてのファイルは $OUTPUT_DIR に入らなければなりません。ファイルを作業ディレクトリに散らすとクリーンアップが不可能になり、以前の実行を上書きするリスクがあります。
• "見つけた最初のデータベースを使う" - 異なる言語や以前の実行のための複数のデータベースが存在する可能性があります。複数が見つかった場合、すべてのオプションをユーザーに提示してください。ユーザーが既にどのデータベースを使用するかを指定した場合のみプロンプトをスキップしてください。
• "ユーザーが 'scan' と言ったから、データベースを選ぶ必要がある" - "Scan" はデータベース選択ではありません。複数のデータベースが存在し、ユーザーが名前を指定しなかった場合、確認してください。

---

ワークフロー選択

このスキルには 3 つのワークフローがあります。ワークフローが選択されたら、フェーズをスキップせずにステップバイステップで実行してください。

ワークフロー	目的
build-database	シーケンスでビルドメソッドを使用して CodeQL データベースを作成
create-data-extensions	プロジェクト API のデータ拡張機能モデルを検出または生成
run-analysis	ルールセットを選択、クエリを実行、結果を処理

自動検出ロジック

ユーザーが明示的に指定する場合 (例: "データベースをビルド"、"./my-db の CodeQL データベースを分析") は、そのワークフローを直接実行してください。ユーザーのプロンプトが既に意図を明確にしている場合、データベース選択に対して AskUserQuestion を呼び出さないでください — 例えば、"新しいデータベースをビルド"、"static_analysis_codeql_2 の codeql データベースを分析"、"最初からフルスキャンを実行"。

"test"、"scan"、"analyze" などの場合のデフォルトパイプライン: 既存のデータベースを最初に発見し、その後決定します。

# codeql-database.yml マーカーファイルを見つけてすべての CodeQL データベースを検索
# トップレベルのディレクトリと 1 つ下のサブディレクトリを検索
FOUND_DBS=()
while IFS= read -r yml; do
  db_dir=$(dirname "$yml")
  codeql resolve database -- "$db_dir" >/dev/null 2>&1 && FOUND_DBS+=("$db_dir")
done < <(find . -maxdepth 3 -name "codeql-database.yml" -not -path "*/\.*" 2>/dev/null)

echo "Found ${#FOUND_DBS[@]} existing database(s)"

条件	アクション
データベースが見つからない	新しい $OUTPUT_DIR を解決し、ビルド → 拡張機能 → 分析を実行 (フルパイプライン)
1 つのデータベースが見つかった	AskUserQuestion を使用: 再利用するか新規ビルドするか?
複数のデータベースが見つかった	AskUserQuestion を使用: すべてをメタデータ付きでリスト、ユーザーが 1 つを選択するか新規ビルド
ユーザーが明示的に意図を述べた	AskUserQuestion をスキップ、指示に基づいて実行

データベース選択プロンプト

既存のデータベースが見つかったかつユーザーがどれを使用するかを明示的に指定しなかった場合は、AskUserQuestion 経由で提示:

header: "既存の CodeQL データベース"
question: "既存の CodeQL データベースが見つかりました。何をしたいですか?"
options:
  - label: "<db_path_1> (language: python, created: 2026-02-24)"
    description: "このデータベースを再利用"
  - label: "<db_path_2> (language: cpp, created: 2026-02-23)"
    description: "このデータベースを再利用"
  - label: "新しいデータベースをビルド"
    description: "新しい出力ディレクトリに新しいデータベースを作成"

選択後:

• ユーザーが既存のデータベースを選択: $OUTPUT_DIR をその親ディレクトリに設定 (またはそれを含むディレクトリ)、$DB_NAME を選択されたパスに設定、拡張機能 → 分析に進む。
• ユーザーが "新規ビルド" を選択: 新しい $OUTPUT_DIR を解決、ビルド → 拡張機能 → 分析を実行。

一般的な決定プロンプト

ユーザーの意図が曖昧な場合 (データベース選択もワークフローも明確でない場合) は、確認してください:

CodeQL 分析をお手伝いします。何をしたいですか?

1. **フルスキャン (推奨)** - データベースをビルド、拡張機能を作成、分析を実行
2. **データベースをビルド** - このコードベースから新しい CodeQL データベースを作成
3. **データ拡張機能を作成** - プロジェクト API 用のカスタムソース/シンクモデルを生成
4. **分析を実行** - 既存のデータベースに対してセキュリティクエリを実行

[見つかったデータベースがある場合: "N 個の既存データベースが見つかりました: <パスリスト (言語付き)>"]
[出力ディレクトリを表示: "出力は <OUTPUT_DIR> に保存されます"]

---

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

ファイル	内容
ワークフロー
workflows/build-database.md	ビルドメソッドシーケンスを使用したデータベース作成
workflows/create-data-extensions.md	データ拡張機能生成パイプライン
workflows/run-analysis.md	クエリ実行と結果処理
リファレンス
references/macos-arm64e-workaround.md	Apple Silicon ビルドトレーシング回避策
references/build-fixes.md	ビルド失敗修正カタログ
references/quality-assessment.md	データベース品質メトリクスと改善
references/extension-yaml-format.md	データ拡張機能 YAML カラム定義と例
references/sarif-processing.md	SARIF 出力処理用の jq コマンド
references/diagnostic-query-templates.md	ソース/シンク列挙用 QL クエリ
references/important-only-suite.md	Important-only スイートテンプレートと生成
references/run-all-suite.md	Run-all スイートテンプレート
references/ruleset-catalog.md	言語別利用可能なクエリパック
references/threat-models.md	脅威モデル設定
references/language-details.md	言語固有のビルドと抽出の詳細
references/performance-tuning.md	メモリ、スレッド、タイムアウト設定

---

成功条件

完全な CodeQL 分析実行は以下を満たす必要があります:

• 出力ディレクトリが解決 (ユーザー指定またはオートインクリメント デフォルト)
• すべての生成ファイルが $OUTPUT_DIR 内に保存
• データベースがビルド (codeql-database.yml マーカーで発見)、品質評価に合格 (ベースライン LoC > 0、エラー < 5%)
• データ拡張機能が評価 — $OUTPUT_DIR/extensions/ で作成されるか、正当な理由でスキップ
• 明示的なスイートリファレンス (デフォルト パック スイートではなく) で分析を実行
• すべてのインストール済みクエリパック (公式 + Trail of Bits + コミュニティ) が使用されるか明示的に除外
• 選択されたクエリパックが $OUTPUT_DIR/rulesets.txt にログ出力
• フィルタなしの結果が $OUTPUT_DIR/raw/results.sarif に保存
• 最終結果が $OUTPUT_DIR/results/results.sarif に保存 (important-only 用にフィルタ、run-all 用にコピー)
• ゼロ検出の結果が調査 (データベース品質、モデルカバレッジ、スイート選択)
• ビルドログが $OUTPUT_DIR/build.log に保存 (すべてのコマンド、修正、品質評価を含む)