codeql

CodeQL コードスキャン

このスキルでは、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 の初期化と分析を設定する

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 のサブスクリプションは不要です。コミットする前に、修正案を慎重に確認してください。

プルリクエストでのアラートのトリアージ

• アラートは、変更された行にチェックの注釈として表示されます
• デフォルトでは、重要度が error／critical／high のアラートがあるとチェックは失敗します
• マージ保護ルールセットを設定して、しきい値をカスタマイズします
• 監査証跡を残すため、誤検知を却下する際は理由を記録してください

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

カスタムクエリとパック

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

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/[email protected]
      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 の権限を追加します
自動ビルドの失敗	build-mode: manual に切り替え、明示的なビルドコマンドを追加します
ソースコードが検出されない	--source-root、ビルドコマンド、言語識別子を確認します
C# コンパイラーの失敗	/p:EmitCompilerGeneratedFiles=true が .sqlproj またはレガシープロジェクトと競合していないか確認します
スキャンされた行数が想定より少ない	none から autobuild／manual に切り替え、ビルドですべてのソースがコンパイルされることを確認します
ビルドなしモードでの Kotlin	デフォルトのセットアップを無効にしてから再度有効にし、autobuild に切り替えます
実行のたびにキャッシュミスが発生する	init アクションで dependency-caching: true が設定されていることを確認します
ディスク容量／メモリ不足	より大規模なランナーを使用します。paths 設定で解析範囲を縮小するか、build-mode: none を使用します
SARIF のアップロードに失敗する	トークンに security-events: write があることを確認し、ファイルサイズの上限 10 MB を確認します
SARIF の結果が上限を超える	異なる --sarif-category を指定して複数回に分けてアップロードし、クエリ範囲を縮小します
CodeQL ワークフローが 2 つある	高度なセットアップを使用している場合はデフォルトのセットアップを無効にするか、古いワークフローファイルを削除します
解析が遅い	依存関係のキャッシュを有効にし、--threads=0 を使用して、クエリスイートの範囲を縮小します

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

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

コードベースの規模	RAM	CPU
小規模（<100K LOC）	8 GB 以上	2 コア
中規模（100K～1M LOC）	16 GB 以上	4～8 コア
大規模（>1M LOC）	64 GB 以上	8 コア

すべての規模で、空きディスク容量が 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 — 言語ごとのビルドモードと自動ビルドの動作
  • 検索パターン：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