CodeQL の詳細セットアップのトラブルシューティング

注: プライベートおよびインターナルリポジトリについては、code scanning は GitHub Advanced Security 機能がそのリポジトリで有効化されている場合に利用できます。エラー Advanced Security must be enabled for this repository to use code scanning が表示された場合は、GitHub Advanced Security が有効化されていることを確認します。詳しくは、「リポジトリのセキュリティと分析設定を管理する」を参照してください。

デバッグ用の詳細なログを生成する

詳細なログ出力を生成するため、ステップのデバッグロギングを有効化することができます。詳しくは、「デバッグログを有効にする」を参照してください。

CodeQL デバッグ成果物の作成

CodeQL のデバッグに役立つ成果物を取得できます。デバッグ成果物は、debug-artifacts という名前の成果物としてワークフローの実行にアップロードされます。このデータには、CodeQL ログ、CodeQL データベース、およびワークフローで生成されたすべての SARIF ファイルが含まれています。

これらの成果物は、CodeQL code scanningに関する問題をデバッグするのに役立ちます。 GitHub サポートに問い合わせた場合、このデータを要求される場合があります。

デバッグログが有効な状態でのジョブの再実行による、CodeQL デバッグ成果物の作成

デバッグログを有効にし、ジョブを再実行することで、CodeQL デバッグ成果物を作成できます。 GitHub Actions のワークフローとジョブの再実行について詳しくは、「ワークフローとジョブの再実行」を参照してください。

必ず [デバッグログの有効化] を選ぶ必要があります。このオプションにより、実行でランナー診断ログとステップデバッグログが有効になります。これで、debug-artifacts をダウンロードしてさらに調査できるようになります。ジョブを再実行して CodeQL デバッグ成果物を作成するときに、ワークフローファイルを変更する必要はありません。

ワークフローフラグを使用した CodeQL デバッグ成果物の作成

ワークフローでフラグを使用して CodeQL デバッグ成果物を作成できます。このためには、CodeQL 分析ワークフローファイルの init ステップを変更して debug: true を設定する必要があります。

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

結果が予想と異なる

code scanning の結果が予想と異なる場合、リポジトリに code scanning の既定と詳細の両方のセットアップが含まれている可能性があります。既定のセットアップを有効にすると、既存の CodeQL ワークフローファイルが無効になり、CodeQL API 分析による結果のアップロードがブロックされます。

既定のセットアップが有効になっているかどうかを確認するには、リポジトリのメインページに移動し、 [設定] をクリックします。サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。ページの [Code scanning] セクションで、[CodeQL 分析] の横にあるをクリックします。 [詳細に切り替える] オプションが表示されている場合、現在は既定のセットアップを使用しています。

高度なセットアップの使用に戻り、カスタムワークフローファイルから code scanning の結果を取得するには、 [CodeQL を無効にする] をクリックして、既定の設定を無効にします。その後、既存のワークフローをもう一度有効にして、高度なセットアップから結果のトリガーとアップロードを開始する必要があります。詳しくは、「ワークフローの無効化と有効化」と「リポジトリの code scanning を構成する」をご覧ください。

場合によっては、リポジトリで code scanning の複数の構成を使用できます。これらの構成により、重複するアラートが生成される可能性があります。さらに、実行されなくなった古い構成では、古いアラートの状態が表示され、古いアラートは無期限に開いたままになります。古いアラートを発生させないようにするには、ブランチから code scanning の古い構成を削除する必要があります。複数の構成について、および古い構成を削除する方法の詳細については、「Code scanningアラートについて」と「リポジトリのコードスキャンのアラートを管理する」を参照してください。

コンパイル言語の自動ビルドの失敗

プロジェクト内のコンパイル言語のコードの自動ビルドが失敗した場合は、次のトラブルシューティングのステップを試してください。

code scanning ワークフローから autobuild ステップを削除し、特定のビルドステップを追加します。ワークフローの編集方法については、「code scanning のカスタマイズ」をご覧ください。 autobuild ステップの置換方法については、コンパイル済み言語の CodeQL ワークフローを構成するをご覧ください。
ワークフローが解析する言語を明示的に指定していない場合、CodeQL はコードベースでサポートされている言語を暗黙的に検出します。この構成では、コンパイル言語である C/C++、C#、Go、Java のうち、ソースファイルが最も多い言語のみが CodeQL によって分析されます。ワークフローを編集し、解析する言語を指定するマトリックスを追加してください。既定の CodeQL 分析ワークフローでは、このようなマトリックスが使用されます。

以下はワークフローからの抜粋で、まず言語を指定するジョブ戦略におけるマトリクスの使用法を示し、次に「Initialize CodeQL」のステップで各言語を参照しています。
```
jobs:
  analyze:
    permissions:
      security-events: write
      actions: read
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['csharp', 'cpp', 'javascript']

    steps:
    ...
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: ${{ matrix.language }}
```
ワークフローの編集方法について詳しくは、「code scanning のカスタマイズ」をご覧ください。

ビルド中にコードが見つからない

ワークフローがエラー No source code was seen during the build または The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32 で失敗した場合は、CodeQL でコードを監視できなかったことを示します。このようなエラーが発生する理由として、次のようなものがあります。

リポジトリには、CodeQL でサポートされている言語で記述されたソースコードが含まれていない場合があります。サポートされている言語の一覧を確認し、その場合は CodeQL ワークフローを削除します。詳しくは、「CodeQL によるコードスキャンについて」をご覧ください
自動言語検出により、サポートされている言語が特定されたが、リポジトリにその言語の分析可能なコードがない。一般的な例としては、言語検出サービスが .h ファイルや .gyp ファイルなどの特定のプログラミング言語に関連付けられたファイルを見つけたが、対応する実行可能コードがリポジトリに存在しない場合です。この問題を解決するには、language マトリクスにある言語のリストを更新し、解析する言語を手動で定義します。たとえば、次の設定では Go と JavaScript のみを分析します。
```
strategy:
  fail-fast: false
  matrix:
    # Override automatic language detection by changing the list below.
    # Supported options are listed in a comment in the default workflow.
    language: ['go', 'javascript']
```
詳細については、前述の「Automatic build for a compiled language fails」(コンパイル言語の自動ビルドが失敗する) のワークフロー抽出を参照してください。
code scanning ワークフローでコンパイル言語 (C、C++、C#、Go、または Java) が分析されているが、コードはコンパイルされていない。デフォルトでは、CodeQL 分析ワークフローには autobuild ステップが含まれていますが、このステップはベストエフォートプロセスを表しており、特定のビルド環境によっては、コードのビルドに失敗する可能性があります。 autobuild ステップを削除し、ビルドステップを手動で含めない場合も、コンパイルが失敗する可能性があります。ビルドステップの指定方法について詳しくは、「コンパイル済み言語の CodeQL ワークフローを構成する」をご覧ください。
ワークフローでコンパイル言語 (C、C++、C#、Go、または Java) が分析されているが、パフォーマンスを向上させるためにビルドの一部がキャッシュされている (Gradle や Bazel などのビルドシステムで発生する可能性が最も高い)。 CodeQL はコンパイラのアクティビティを監視してリポジトリ内のデータフローを理解するため、CodeQL は分析を実行するために完全なビルドを実行する必要があります。
ワークフローでコンパイル言語 (C、C++、C#、Go、または Java) が分析されているが、ワークフローの init と analyze ステップの間でコンパイルが行われていない。 CodeQL では、コンパイラのアクティビティを監視して分析を実行するために、これらの 2 つのステップ間でビルドを行う必要があります。
コンパイル済みコード (C、C++、C#、Go、または Java) は正常にコンパイルされたが、CodeQL でコンパイラの呼び出しを検出できない。最も一般的な原因を次に示します。
- ビルドプロセスを CodeQL とは別のコンテナで実行している。詳しくは、「コンテナで CodeQL Code scanningを実行する」を参照してください。
- デーモンプロセスを使用して、GitHub Actions の外部で分散ビルドシステムによりビルドしている。
- CodeQL は、使用されているコンパイラを認識していない。
.NET Framework プロジェクトの場合、および dotnet build または msbuild を使用する C# プロジェクトの場合は、コードをビルドするときにワークフローの run ステップで /p:UseSharedCompilation=false を指定する必要があります。

たとえば、次の C# に対する設定では、最初のビルドステップ中にフラグが渡されます。
```
- run: |
    dotnet build /p:UseSharedCompilation=false
```
特定のコンパイラまたは設定で別の問題が発生した場合は、GitHub Support までお問い合わせください。

ビルドステップの指定方法について詳しくは、「コンパイル済み言語の CodeQL ワークフローを構成する」をご覧ください。

スキャンされたコード行が想定よりも少ない

C/C++、C#、Go、Java などのコンパイル言語の場合、CodeQL では、分析中にビルドされたファイルのみがスキャンされます。そのため、一部のソースコードが正しくコンパイルされていない場合、スキャンされるコード行の数は想定よりも少なくなります。これは、いくつかの理由で発生します。

CodeQL の autobuild 機能では、ヒューリスティックを使用してリポジトリにコードがビルドされます。ただし、このアプローチではリポジトリの分析が不完全になることがあります。たとえば、1 つのリポジトリに複数の build.sh コマンドが存在する場合、autobuild ステップで実行されるコマンドは 1 つのみであるため、一部のソースファイルがコンパイルされない可能性があります。したがって、分析が完了しない可能性があります。
一部のコンパイラは CodeQL で動作せず、コードの分析中に問題が発生する可能性があります。たとえば、Project Lombok では、パブリックでないコンパイラ API を使用してコンパイラの動作が変更されます。これらのコンパイラの変更で用いられる想定は、CodeQL の Java 抽出子では有効ではないため、コードを分析することができません。

CodeQL 分析でスキャンされるコード行が想定よりも少ない場合は、必要なすべてのソースファイルがコンパイルされるようにいくつかのアプローチを試すことができます。

`autobuild` ステップを置き換える

autobuild ステップを、運用環境で使用するのと同じビルドコマンドに置き換えます。これにより、CodeQL では、スキャンするすべてのソースファイルをコンパイルする方法を正確に認識できます。詳しくは、「コンパイル済み言語の CodeQL ワークフローを構成する」を参照してください。

CodeQL データベース内のソースファイルのコピーを調べる

CodeQL データベースに含まれるソースコードのコピーを調べることで、一部のソースファイルが分析されていない理由を理解できる場合があります。 Actions ワークフローからデータベースを取得するには、CodeQL ワークフローファイルの init ステップを変更し、debug: true を設定します。

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

これにより、ローカルコンピューターにダウンロードできるアクション成果物としてデータベースがアップロードされます。詳しくは、「ワークフローデータを成果物として保存する」を参照してください。

成果物には、CodeQL によってスキャンされたソースファイルのアーカイブされたコピー (src.zip と呼ばれる) が含まれます。リポジトリ内のソースコードファイルと src.zip 内のファイルを比較すると、不足しているファイルの種類を確認できます。分析されていないファイルの種類がわかったら、CodeQL 分析のワークフローをどのように変更する必要があるかを容易に理解できます。

生成されたコードで検出されたアラート

Java、Kotlin、Go、C、C++、C# などのコンパイル言語の場合、CodeQL ではワークフローの実行中にビルドされたすべてのコードを分析します。分析するコードの量を制限するには、run ブロックで独自のビルドステップを指定して、分析するコードのみをビルドします。独自のビルドステップの指定と、pull_request イベントや push イベントでの paths フィルターまたは paths-ignore フィルターの使用を組み合わせることで、特定のコードが変更されたときにのみワークフローが実行されるようにすることができます。詳しくは、「GitHub Actions のワークフロー構文」を参照してください。

ソースコードをコンパイルせずに CodeQL で分析されるJavaScript、Python、TypeScript などの言語の場合、追加の構成オプションを指定して分析するコードの量を制限できます。詳しくは、「code scanning のカスタマイズ」を参照してください。

データベースの抽出エラー

CodeQL チームは、すべてのソースファイルを確実にスキャンできるように、重大な抽出エラーに常に対処しています。ただし、CodeQL 抽出子では、データベースの作成時にエラーが発生することがあります。 CodeQL では、データベースの作成時にログファイル内に生成された抽出エラーおよび警告に関する情報が提供されます。抽出診断情報は、データベースの全体的な正常性を示します。ほとんどの抽出エラーは、分析に大きな影響を及ぼすことはありません。少数の抽出エラーは正常であり、通常は良好な分析状態を示します。

ただし、データベースの作成時にコンパイルされたファイルの大部分に抽出エラーが生じる場合は、エラーを詳しく調べて、一部のソースファイルが正しく抽出されなかった原因を特定する必要があります。

ビルドに時間がかかりすぎる

CodeQL 分析でのビルドの実行に時間がかかりすぎる場合は、ビルド時間を短縮するための方法がいくつかあります。

メモリまたはコアを増やす

セルフホストランナーを使用して CodeQL 解析を実行している場合、ランナーのメモリやコア数を増やすことができます。

マトリックスビルドを使用して分析を並列化する

既定の CodeQL 分析ワークフローでは、言語のマトリックスを使います。これにより、各言語の解析が並列で実行されます。「Initialize CodeQL」ステップで解析する言語を直接指定している場合、各言語の解析は順次行われます。複数の言語で解析を高速化するには、マトリクスを使用するようワークフローを変更してください。詳細については、前述の「Automatic build for a compiled language fails」(コンパイル言語の自動ビルドが失敗する) のワークフロー抽出を参照してください。

1 つのワークフローで分析されるコードの量を減らす

通常、分析時間は、分析対象のコードの量に比例します。たとえば、テストコードを除外したり、一度にコードのサブセットのみを分析する複数のワークフローに分析を分割したりするなど、一度に分析されるコードの量を減らすことで、分析時間を短縮できます。

Java、Kotlin、Go、C、C++、C# などのコンパイル言語の場合、CodeQL ではワークフローの実行中にビルドされたすべてのコードを分析します。分析するコードの量を制限するには、run ブロックで独自のビルドステップを指定して、分析するコードのみをビルドします。独自のビルドステップの指定と、pull_request イベントや push イベントでの paths フィルターまたは paths-ignore フィルターの使用を組み合わせることで、特定のコードが変更されたときにのみワークフローが実行されるようにすることができます。詳しくは、「GitHub Actions のワークフロー構文」を参照してください。

ソースコードをコンパイルせずに CodeQL で分析されるJavaScript、Python、TypeScript などの言語の場合、追加の構成オプションを指定して分析するコードの量を制限できます。詳しくは、「code scanning のカスタマイズ」を参照してください。

上記のように分析を複数のワークフローに分割する場合でも、リポジトリ内のすべてのコードを分析する schedule で実行されるワークフローを少なくとも 1 つ用意することをお勧めします。 CodeQL はコンポーネント間のデータフローを分析するため、一部の複雑なセキュリティ動作は完全なビルドでのみ検出される場合があります。

`schedule` イベント中にのみ実行する

push イベント中または pull_request イベント中の分析の実行に引き続き時間がかかりすぎる場合は、schedule イベントでのみ分析をトリガーすることをお勧めします。詳しくは、「GitHub Actions を理解する」を参照してください。

ワークフローが実行されているクエリスイートを確認する

既定では、言語ごとに 3 つの主要なクエリスイートを使用できます。 CodeQL データベースのビルドを最適化してもプロセスに時間がかかりすぎる場合は、実行するクエリの数を減らすことで対処できます。既定のクエリスイートは自動的に実行されます。これには、誤検知結果の割合が最も低い最速のセキュリティクエリが含まれています。

既定のクエリに加えて、追加のクエリまたはクエリスイートを実行している可能性があります。ワークフローで、queries 要素を使用して実行する追加のクエリスイートまたは追加のクエリが定義されているかどうかを確認します。追加のクエリスイートまたはクエリを無効にして試験を行うことができます。詳しくは、「code scanning のカスタマイズ」を参照してください。

メモ: JavaScript で security-extended または security-and-quality クエリスイートを実行する場合、一部のクエリでは試験的なテクノロジが使用されます。詳しくは、「Code scanningアラートについて」を参照してください。

分析プラットフォーム間で異なる結果

Pythonで書かれたコードを分析している場合は、CodeQL 分析ワークフローを Linux、macOS、Windows のどれで実行するかによって、表示される結果が異なることがあります。

Linux が使用されている Github ホステッドランナーの場合、CodeQL 分析ワークフローによって、Python 依存関係のインストールと分析が試行されて、さらに多くの結果が得られることがあります。自動インストールを無効にするには、ワークフローの "Initialize CodeQL" ステップに setup-python-dependencies: false を追加します。 Python 依存関係の分析を構成する方法の詳細については、「code scanning のカスタマイズ」を参照してください。

エラー: "サーバーエラー"

サーバーエラーにより code scanning のワークフローが実行できない場合は、ワークフローを再実行してください。問題が解決しない場合は、GitHub Support にお問い合わせください。

エラー: "Out of disk (ディスク不足)" または "メモリ不足"

非常に大規模なプロジェクトでは、CodeQL でランナーのディスクまたはメモリが不足する場合があります。ホストされた GitHub Actions ランナーでこの問題が生じた場合は、弊社が問題を調査できるよう GitHub Supportに連絡してください。

Dependabotを使用している際のError: 403 "Resource not accessible by integration"

Dependabotは、ワークフローの実行をトリガーする際に信頼できないと見なされ、ワークフローは読み取りのみのスコープで実行されます。ブランチに対するcode scanningの結果をアップロードするには、通常 security_events: write スコープが必要になります。ただし、pull_request イベントによってアクションの実行がトリガーされると、code scanningで常に結果のアップロードが許可されます。そのため、Dependabot ブランチでは push イベントの代わりに pull_request イベントを使用することをお勧めします。

シンプルなアプローチは、このブランチ群に対してオープンされたPull Requestとともに、デフォルトブランチやその他の重要な長時間実行されるブランチに対するプッシュで実行することです。

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

別のアプローチは、Dependabotブランチを除くすべてのプッシュに対して実行することです。

on:
  push:
    branches-ignore:
      - 'dependabot/**'
  pull_request:

既定のブランチでも分析が失敗する

CodeQL 分析ワークフローが、既定のブランチに作成されたコミットでそれでも失敗する場合は、次を確認する必要があります。

Dependabotがそのコミットを作成したか
コミットを含む pull 要求が @dependabot squash and merge を使用してマージされたかどうか

この種のマージコミットはDependabotによって作成されるので、このコミットで実行されるワークフローは読み取りのみの権限を持つことになります。 code scanningと Dependabot のセキュリティ更新またはバージョン更新をリポジトリで有効化した場合は、Dependabot の @dependabot squash and merge コマンドは使用しないことをお勧めします。代わりに、リポジトリで自動マージを有効にすることができます。つまり、必要なすべてのレビューが満足され、状態チェックに合格すると、pull request は自動的にマージされます。自動マージの有効化方法について詳しくは、「プルリクエストを自動的にマージする」をご覧ください。

エラー: ".ql ファイル、.qls ファイル、ディレクトリ、またはクエリパック仕様ではありません"

このエラーは、CodeQL によって、ワークフローで要求されている場所で名前付きクエリ、クエリスイート、またはクエリパックを見つけることができない場合に表示されます。一般に、このエラーには 2 つの理由があります。

ワークフローに入力ミスがあります。
ワークフローでパスにより参照されているリソースが、名前を変更、削除、または新しい場所に移動されました。

リソースの場所を確認した後、正しい場所を指定するようにワークフローを更新できます。

警告: "git checkout HEAD^2 is no longer necessary (git checkout HEAD^2 は不要になりました)"

古いCodeQLワークフローを使っていると、"Initialize CodeQL"アクションからの出力に以下の警告が含まれていることがあります。

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer
necessary. Please remove this step as Code Scanning recommends analyzing the merge
commit for best results.

これは、以下の行をCodeQLワークフローから削除することによって修正してください。これらの行は、初期バージョンの CodeQL ワークフロー内の Analyze ジョブの steps セクションに含まれています。

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

ワークフローの変更された steps セクションは次のようになります。

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

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

CodeQL ワークフローファイルの編集方法について詳しくは、「code scanning のカスタマイズ」をご覧ください。

CodeQL の詳細セットアップのトラブルシューティング

この記事の内容