CodeQL Code Scanning

このスキルは、GitHub Actions ワークフロー経由とスタンドアロン CodeQL CLI の両方を使用した CodeQL コード スキャンの構成と実行に関する手続きガイダンスを提供します。

このスキルを使用する場合

以下のリクエストが関係する場合にこのスキルを使用します。

• codeql.yml GitHub Actions ワークフローの作成またはカスタマイズ
• コード スキャンのデフォルト設定と高度な設定の選択
• CodeQL 言語マトリックス、ビルド モード、またはクエリ スイートの構成
• CodeQL CLI をローカルで実行 (codeql database create, database analyze, github upload-results)
• CodeQL からの SARIF 出力の理解または解釈
• CodeQL 分析エラーのトラブルシューティング (ビルド モード、コンパイル言語、ランナー要件)
• マルチレポ向け CodeQL のセットアップ (コンポーネント別スキャン)
• 依存関係キャッシング、カスタム クエリ パック、またはモデル パックの構成

サポートされている言語

CodeQL は以下の言語識別子をサポートしています。

言語	識別子	別名
C/C++	c-cpp	c, cpp
C#	csharp	—
Go	go	—
Java/Kotlin	java-kotlin	java, kotlin
JavaScript/TypeScript	javascript-typescript	javascript, typescript
Python	python	—
Ruby	ruby	—
Rust	rust	—
Swift	swift	—
GitHub Actions	actions	—

別の識別子は標準識別子と等価です (例: javascript は TypeScript 分析を除外しません)。

コア ワークフロー — GitHub Actions

ステップ 1: セットアップ タイプの選択

• デフォルト設定 — リポジトリ設定 → Advanced Security → CodeQL analysis から有効化します。クイック スタートに最適です。ほとんどの言語で none ビルド モードを使用します。
• 高度な設定 — .github/workflows/codeql.yml ファイルを作成して、トリガー、ビルド モード、クエリ スイート、マトリックス戦略の完全な制御ができます。

デフォルト設定から高度な設定に切り替えるには、まずデフォルト設定を無効化し、その後ワークフロー ファイルをコミットします。

ステップ 2: ワークフロー トリガーの構成

スキャンを実行するタイミングを定義します。

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

• push — 指定されたブランチへのすべてのプッシュをスキャンします。結果は Security タブに表示されます
• pull_request — PR マージ コミットをスキャンします。結果は PR チェック注釈として表示されます
• schedule — デフォルト ブランチの定期的なスキャン (cron はデフォルト ブランチに存在する必要があります)
• merge_group — リポジトリがマージ キューを使用している場合に追加します

ドキュメント専用の PR のスキャンをスキップするには:

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore はワークフローが実行されるかどうかを制御します。分析対象のファイルではありません。

ステップ 3: パーミッションの構成

最小権限パーミッションを設定します。

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

ステップ 4: 言語マトリックスの構成

マトリックス戦略を使用して、各言語を並行で分析します。

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

コンパイル言語の場合、適切な build-mode を設定します。

• none — ビルド不要 (C/C++、C#、Java、Rust でサポート)
• autobuild — 自動ビルド検出
• manual — カスタム ビルド コマンド (高度な設定のみ)

言語別の詳細な autobuild の動作とランナー要件については、references/compiled-languages.md を検索してください。

ステップ 5: CodeQL Init と分析の構成

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}
      queries: security-extended
      dependency-caching: true

  - name: Perform CodeQL Analysis
    uses: github/codeql-action/analyze@v4
    with:
      category: "/language:${{ matrix.language }}"

クエリ スイート オプション:

• security-extended — デフォルト セキュリティ クエリとその他のカバレッジ
• security-and-quality — セキュリティ + コード品質クエリ
• packs: 入力経由のカスタム クエリ パック (例: codeql/javascript-queries:AlertSuppression.ql)

依存関係キャッシング: init アクションで dependency-caching: true を設定して、実行全体で復元された依存関係をキャッシュします。

分析カテゴリ: category を使用して、マルチレポの SARIF 結果を区別します (例: 言語別、コンポーネント別)。

ステップ 6: マルチレポ構成

複数のコンポーネントを持つマルチレポの場合、category パラメータを使用して SARIF 結果を分離します。

category: "/language:${{ matrix.language }}/component:frontend"

分析を特定のディレクトリに制限するには、CodeQL 構成ファイル (.github/codeql/codeql-config.yml) を使用します。

paths:
  - apps/
  - services/
paths-ignore:
  - node_modules/
  - '**/test/**'

ワークフロー内で参照します。

- uses: github/codeql-action/init@v4
  with:
    config-file: .github/codeql/codeql-config.yml

ステップ 7: 手動ビルド ステップ (コンパイル言語)

autobuild が失敗した場合またはカスタム ビルド コマンドが必要な場合:

- language: c-cpp
  build-mode: manual

その後、init と analyze の間に明示的なビルド ステップを追加します。

- if: matrix.build-mode == 'manual'
  name: Build
  run: |
    make bootstrap
    make release

コア ワークフロー — CodeQL CLI

ステップ 1: CodeQL CLI のインストール

CodeQL バンドル (CLI + プリコンパイル済みクエリを含む) をダウンロードします。

# Download from https://github.com/github/codeql-action/releases
# Extract and add to PATH
export PATH="$HOME/codeql:$PATH"

# Verify installation
codeql resolve packs
codeql resolve languages

スタンドアロン CLI ダウンロードではなく、常に CodeQL バンドルを使用してください。バンドルはクエリ互換性を確保し、パフォーマンス向上のためプリコンパイル済みクエリを提供します。

ステップ 2: CodeQL データベースの作成

# Single language
codeql database create codeql-db \
  --language=javascript-typescript \
  --source-root=src

# Multiple languages (cluster mode)
codeql database create codeql-dbs \
  --db-cluster \
  --language=java,python \
  --command=./build.sh \
  --source-root=src

コンパイル言語の場合、--command 経由でビルド コマンドを提供します。

ステップ 3: データベースの分析

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

一般的なクエリ スイート: <language>-code-scanning.qls, <language>-security-extended.qls, <language>-security-and-quality.qls

ステップ 4: GitHub への結果のアップロード

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

security-events: write パーミッションを持つ GITHUB_TOKEN 環境変数が必要です。

CLI サーバー モード

複数のコマンド実行時に JVM の繰り返し初期化を避けるには:

codeql execute cli-server

詳細な CLI コマンド リファレンスについては、references/cli-commands.md を検索してください。

アラート管理

重大度レベル

アラートは 2 つの重大度ディメンションを持ちます。

• 標準重大度: Error, Warning, Note
• セキュリティ重大度: Critical, High, Medium, Low (CVSS スコアから派生; 表示は優先されます)

Copilot Autofix

GitHub Copilot Autofix は CodeQL アラートの修正提案をプル リクエストで自動的に生成します — Copilot サブスクリプションは不要です。コミット前に提案を注意深く確認してください。

PR でのアラート トリアージ

• アラートは変更行にチェック注釈として表示されます
• error/critical/high 重大度アラートの場合、デフォルトでチェックが失敗します
• マージ保護ルールセットを構成して、しきい値をカスタマイズします
• 監査証跡のために、誤検知をドキュメント理由で却下します

詳細なアラート管理ガイダンスについては、references/alert-management.md を検索してください。

カスタム クエリとパック

カスタム クエリ パックの使用

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/my-security-queries@1.0.0
      codeql/javascript-queries:AlertSuppression.ql

カスタム クエリ パックの作成

CodeQL CLI を使用してパックを作成および公開します。

# Initialize a new pack
codeql pack init my-org/my-queries

# Install dependencies
codeql pack install

# Publish to GitHub Container Registry
codeql pack publish

CodeQL 構成ファイル

高度なクエリとパス構成については、.github/codeql/codeql-config.yml を作成します。

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

コード スキャン ログ

サマリー メトリクス

ワークフロー ログに主要メトリクスが含まれます。

• コードベース内のコード行 — 抽出前のベースライン
• 抽出された行 — 外部ライブラリと自動生成ファイルを含む
• 抽出エラー/警告 — 抽出中に失敗または警告を生成したファイル

デバッグ ロギング

詳細な診断を有効にするには:

• GitHub Actions: "Enable debug logging" をチェックしてワークフローを再実行します
• CodeQL CLI: --verbosity=progress++ と --logdir=codeql-logs を使用します

トラブルシューティング

よくある問題

問題	解決策
ワークフロー が発動しない	on: トリガーがイベントと一致することを確認します。paths/branches フィルタを確認します。ワークフローがターゲット ブランチに存在することを確認します
Resource not accessible エラー	security-events: write と contents: read パーミッションを追加します
Autobuild エラー	build-mode: manual に切り替えて、明示的なビルド コマンドを追加します
ソース コードが見つからない	--source-root、ビルド コマンド、言語識別子を確認します
C# コンパイラ エラー	/p:EmitCompilerGeneratedFiles=true と .sqlproj またはレガシー プロジェクトとの競合をチェックします
スキャン行数が予想より少ない	none から autobuild/manual に切り替えます。ビルドがすべてのソースをコンパイルすることを確認します
no-build モードの Kotlin	デフォルト設定を無効化して再度有効化して、autobuild に切り替えます
実行時にキャッシュ ミスが発生する	init アクションで dependency-caching: true を確認します
ディスク/メモリ不足	より大きなランナーを使用します。paths 構成で分析スコープを縮小します。build-mode: none を使用します
SARIF アップロード失敗	トークンが security-events: write を持つことを確認します。10 MB ファイル サイズ制限をチェックします
SARIF 結果が制限を超える	異なる --sarif-category で複数のアップロードに分割します。クエリ スコープを縮小します
2 つの CodeQL ワークフロー	高度な設定を使用している場合はデフォルト設定を無効化するか、古いワークフロー ファイルを削除します
分析が遅い	依存関係キャッシングを有効化します。--threads=0 を使用します。クエリ スイート スコープを縮小します

詳細なソリューションを含む包括的なトラブルシューティングについては、references/troubleshooting.md を検索してください。

ハードウェア要件 (セルフホストランナー)

コードベース サイズ	RAM	CPU
小 (<100K LOC)	8 GB+	2 cores
中 (100K–1M LOC)	16 GB+	4–8 cores
大 (>1M LOC)	64 GB+	8 cores

すべてのサイズ: ≥14 GB の空き容量を持つ SSD。

アクション バージョン管理

CodeQL アクションを特定のメジャー バージョンにピンします。

uses: github/codeql-action/init@v4      # Recommended
uses: github/codeql-action/autobuild@v4
uses: github/codeql-action/analyze@v4

最大セキュリティについては、バージョン タグの代わりに完全なコミット SHA にピンします。

リファレンス ファイル

詳細なドキュメントについては、必要に応じて次のリファレンス ファイルをロードします。

• references/workflow-configuration.md — 完全なワークフロー トリガー、ランナー、構成オプション
  • 検索パターン: trigger, schedule, paths-ignore, db-location, model packs, alert severity, merge protection, concurrency, config file
• references/cli-commands.md — 完全な CodeQL CLI コマンド リファレンス
  • 検索パターン: database create, database analyze, upload-results, resolve packs, cli-server, installation, CI integration
• references/sarif-output.md — SARIF v2.1.0 オブジェクト モデル、アップロード制限、サードパーティ サポート
  • 検索パターン: sarifLog, result, location, region, codeFlow, fingerprint, suppression, upload limits, third-party, precision, security-severity
• references/compiled-languages.md — 言語別ビルド モードと autobuild の動作
  • 検索パターン: C/C++, C#, Java, Go, Rust, Swift, autobuild, build-mode, hardware, dependency caching
• references/troubleshooting.md — 包括的なエラー診断と解決策
  • 検索パターン: no source code, out of disk, out of memory, 403, C# compiler, analysis too long, fewer lines, Kotlin, extraction errors, debug logging, SARIF upload, SARIF limits
• references/alert-management.md — アラート重大度、トリアージ、Copilot Autofix、および却下
  • 検索パターン: severity, security severity, CVSS, Copilot Autofix, dismiss, triage, PR alerts, data flow, merge protection, REST API