codeql

CodeQL 分析

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

スキルリソース： 参照ファイルとテンプレートは references/ と workflows/ にあります。

基本原則

1. データベースの品質は妥協できません。 データベースをビルドできたからといって、品質が良いとは限りません。必ず品質評価（ファイル数、ベースライン LoC、エクストラクターのエラー）を実行し、想定されるソースファイルと比較してください。キャッシュされたビルドでは、有用な抽出結果がまったく得られません。

2. データ拡張で CodeQL が見逃す問題を検出できます。 標準的なフレームワーク（Django、Spring、Express）を使うプロジェクトでも、データベース呼び出し、リクエスト解析、シェル実行にはカスタムラッパーが使われています。create-data-extensions ワークフローを省略すると、プロジェクト固有のコードパスにある脆弱性を見逃します。

3. スイートを明示的に指定して、クエリがひそかに除外されるのを防ぎます。 codeql database analyze にパック名を直接渡してはいけません。各パックの defaultSuiteFile は隠れたフィルターを適用し、結果がゼロになることがあります。必ずカスタムの .qls スイートファイルを生成してください。

4. 検出結果がゼロでも、喜ぶのではなく調査が必要です。 結果がゼロなのは、データベースの品質が低い、モデルが不足している、クエリパックが誤っている、スイートのフィルターでひそかに除外されている、といった可能性を示しています。問題がないと報告する前に調査してください。

5. macOS の Apple Silicon でコンパイル言語を使う場合は、回避策が必要です。 終了コード 137 はビルドの失敗ではなく、arm64e と arm64 の不一致を示しています。build-mode=none に切り替える前に、Homebrew の arm64 ツールまたは Rosetta を試してください。

6. ワークフローを手順どおりに進めてください。 ワークフローを選択したら、フェーズを省略せず、順番に実行してください。各フェーズが次のフェーズに進む条件となっているため、品質評価やデータ拡張を省略すると、分析が不完全になります。

出力ディレクトリ

生成されるすべてのファイル（データベース、ビルドログ、診断情報、拡張機能、結果）は、1 つの出力ディレクトリに保存されます。

• ユーザーがプロンプトで出力ディレクトリを指定した場合は、そのディレクトリを OUTPUT_DIR として使用します。
• 指定がない場合は、デフォルトで ./static_analysis_codeql_1 を使用します。すでに存在する場合は、_2、_3 のように番号を増やします。

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

# Resolve output directory
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                 # Selected query packs (logged after Step 3)
├── codeql.db/                   # CodeQL database (dir containing codeql-database.yml)
├── build.log                    # Build log
├── codeql-config.yml            # Exclusion config (interpreted languages)
├── diagnostics/                 # Diagnostic queries and CSVs
├── extensions/                  # Data extension YAMLs
├── raw/                         # Unfiltered analysis output
│   ├── results.sarif
│   └── <mode>.qls
└── results/                     # Final results (filtered for important-only, copied for run-all)
    └── results.sarif

データベースの検出

CodeQL データベースは、そのディレクトリ内に codeql-database.yml マーカーファイルが存在することで識別されます。既存のデータベースを検索する際は、必ず該当するものをすべて収集してください。以前の実行で作成されたデータベースや、異なる言語向けのデータベースが複数存在する場合があります。

検出コマンド：

# Find ALL CodeQL databases (top-level and one subdirectory deep)
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 each database, extract language and creation time
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. Verify CodeQL is installed
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. Resolve output directory
BASE="static_analysis_codeql"; N=1
while [ -e "${BASE}_${N}" ]; do N=$((N + 1)); done
OUTPUT_DIR="${BASE}_${N}"; mkdir -p "$OUTPUT_DIR"

次に、以下のワークフローを使って、パイプライン全体（データベースのビルド → データ拡張の作成 → 分析の実行）を実行します。

使用する場面

• データフローを詳細に分析して、コードベースのセキュリティ脆弱性をスキャンする場合
• ソースコードから CodeQL データベースをビルドする場合（コンパイル言語ではビルド機能を使用）
• 手続き間の汚染追跡や AST/CFG 分析が必要な複雑な脆弱性を見つける場合
• 複数のクエリパックを使って包括的なセキュリティ監査を実施する場合

使用しない場合

• カスタムクエリを作成する場合 - 専用のクエリ開発スキルを使用してください
• CI/CD との統合 - GitHub Actions のドキュメントを直接参照してください
• パターンを素早く検索する場合 - 高速に検索できる Semgrep または grep を使用してください
• コンパイル言語でビルド機能がない場合 - Semgrep の使用を検討してください
• 単一ファイルまたは軽量な分析 - 単純なパターンマッチングには Semgrep の方が高速です

退けるべき合理化

これらの近道は検出漏れにつながります。受け入れないでください。

• 「security-extended で十分」 - これはベースラインです。その言語で Trail of Bits のパックと Community Packs が利用できるか、必ず確認してください。これらのパックは security-extended がまったく検出できないカテゴリも検出します。
• 「データベースをビルドできたので問題ない」 - データベースをビルドできても、適切に抽出できたとは限りません。必ず品質を評価し、ファイル数を想定されるソースファイル数と照合してください。
• 「標準的なフレームワークではデータ拡張は不要」 - Django／Spring アプリでも、CodeQL がモデル化していないカスタムラッパーが使われています。拡張を省略すると、脆弱性を見逃します。
• 「コンパイル言語でも build-mode=none で問題ない」 - 分析が大幅に不完全になります。最後の手段としてのみ使用してください。macOS では、まず arm64 ツールチェーンの回避策または Rosetta を試してください。
• 「macOS でビルドに失敗したら、build-mode=none を使えばいい」 - 終了コード 137 は、根本的なビルドの失敗ではなく、arm64e／arm64 の不一致が原因です。macos-arm64e-workaround.md を参照してください。
• 「検出結果がないのでコードは安全」 - 検出結果がゼロの場合、データベースの品質不良、モデルの欠落、または誤ったクエリパックが原因である可能性があります。問題なしと報告する前に調査してください。
• 「デフォルトのスイートを実行すればいい」／「パック名をそのまま渡せばいい」 - 各パックの defaultSuiteFile には非表示のフィルターが適用され、結果がゼロになることがあります。必ずスイートを明示的に指定してください。
• 「ファイルはカレントディレクトリに置けばいい」 - 生成されるすべてのファイルは $OUTPUT_DIR に配置してください。作業ディレクトリにファイルを散在させると、クリーンアップができなくなり、以前の実行結果を上書きするリスクもあります。
• 「最初に見つけたデータベースを使えばいい」 - 言語ごと、または以前の実行結果として、複数のデータベースが存在する場合があります。複数見つかった場合は、すべての選択肢をユーザーに提示してください。ユーザーがすでに使用するデータベースを指定している場合に限り、質問を省略してください。
• 「ユーザーが『スキャン』と言ったのだから、使うデータベースはこちらで選べばいい」 - 「スキャン」はデータベースの選択を意味しません。複数のデータベースが存在し、ユーザーがそのうちの1つを指定していない場合は、質問してください。

---

ワークフローの選択

このスキルには3つのワークフローがあります。ワークフローを選択したら、フェーズを省略せず、手順に沿って実行してください。

ワークフロー	目的
build-database	ビルド方法を順番に試して CodeQL データベースを作成する
create-data-extensions	プロジェクトの API 用のデータ拡張モデルを検出または生成する
run-analysis	ルールセットを選択し、クエリを実行して、結果を処理する

自動検出のロジック

ユーザーが実行内容を明示的に指定した場合（例：「データベースをビルドして」「./my-db を分析して」）、該当するワークフローを直接実行してください。ユーザーのプロンプトから意図が明らかな場合は、データベースの選択について AskUserQuestion を呼び出さないでください。例：「新しいデータベースをビルドして」「static_analysis_codeql_2 にある CodeQL データベースを分析して」「最初から完全なスキャンを実行して」。

**「test」「scan」「analyze」など、同様の依頼に対するデフォルトのパイプライン：**まず既存のデータベースを検索してから判断してください。

# Find ALL CodeQL databases by looking for codeql-database.yml marker file
# Search top-level dirs and one subdirectory deep
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 を使用して、メタデータとともにすべてを一覧表示し、ユーザーに選択するか、新しくビルドするかを尋ねる
ユーザーが意図を明示している	AskUserQuestion を省略し、指示に従って直接実行する

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

既存のデータベースが見つかり、ユーザーが使用するデータベースを明示的に指定していない場合は、AskUserQuestion を使って提示します。

header: "Existing CodeQL Databases"
question: "I found existing CodeQL database(s). What would you like to do?"
options:
  - label: "<db_path_1> (language: python, created: 2026-02-24)"
    description: "Reuse this database"
  - label: "<db_path_2> (language: cpp, created: 2026-02-23)"
    description: "Reuse this database"
  - label: "Build a new database"
    description: "Create a fresh database in a new output directory"

選択後：

• ユーザーが既存のデータベースを選択した場合： $OUTPUT_DIR をその親ディレクトリ（またはデータベースを含むディレクトリ）に設定し、$DB_NAME を選択したパスに設定してから、拡張機能 → 分析に進みます。
• ユーザーが「新規作成」を選択した場合： 新しい $OUTPUT_DIR を解決し、ビルド → 拡張機能 → 分析を実行します。

一般的な判断プロンプト

ユーザーの意図が曖昧な場合（データベースの選択もワークフローも明確でない場合）は、次のように質問します。

I can help with CodeQL analysis. What would you like to do?

1. **Full scan (Recommended)** - Build database, create extensions, then run analysis
2. **Build database** - Create a new CodeQL database from this codebase
3. **Create data extensions** - Generate custom source/sink models for project APIs
4. **Run analysis** - Run security queries on existing database

[If databases found: "I found N existing database(s): <list paths with language>"]
[Show output directory: "Output will be stored in <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	重要項目のみのスイートテンプレートと生成
references/run-all-suite.md	すべて実行するスイートテンプレート
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 に保存されている（重要項目のみの場合はフィルタリング、すべて実行の場合はコピー）
• 検出結果がゼロの場合、その原因が調査されている（データベースの品質、モデルのカバレッジ、スイートの選択）
• すべてのコマンド、修正、品質評価を含むビルドログが $OUTPUT_DIR/build.log に保存されている