CodeQL ワークフローのトラブルシューティング

メモ: この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。最新バージョンの使用については、「アプライアンスのコードスキャンを設定する」を参照してください。

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

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

CodeQL デバッグ成果物の作成

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

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

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

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

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

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

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

code scanning ワークフローから autobuild ステップを削除し、特定のビルドステップを追加します。ワークフローの編集方法については、「code scanning のカスタマイズ」をご覧ください。 autobuild ステップの置換方法については、コンパイル済み言語の CodeQL ワークフローを構成するをご覧ください。
ワークフローが解析する言語を明示的に指定していない場合、CodeQL はコードベースでサポートされている言語を暗黙的に検出します。この構成では、コンパイル言語である C/C++、C#、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#、または Java) が分析されているが、コードはコンパイルされていない。デフォルトでは、CodeQL 分析ワークフローには autobuild ステップが含まれていますが、このステップはベストエフォートプロセスを表しており、特定のビルド環境によっては、コードのビルドに失敗する可能性があります。 autobuild ステップを削除し、ビルドステップを手動で含めない場合も、コンパイルが失敗する可能性があります。ビルドステップの指定方法について詳しくは、「コンパイル済み言語の CodeQL ワークフローを構成する」をご覧ください。
ワークフローでコンパイル言語 (C、C++、C#、または Java) が分析されているが、パフォーマンスを向上させるためにビルドの一部がキャッシュされている (Gradle や Bazel などのビルドシステムで発生する可能性が最も高い)。 CodeQL はコンパイラのアクティビティを監視してリポジトリ内のデータフローを理解するため、CodeQL は分析を実行するために完全なビルドを実行する必要があります。
ワークフローでコンパイル言語 (C、C++、C#、または Java) が分析されているが、ワークフローの init と analyze ステップの間でコンパイルが行われていない。 CodeQL では、コンパイラのアクティビティを監視して分析を実行するために、これらの 2 つのステップ間でビルドを行う必要があります。
コンパイル済みコード (C、C++、C#、または 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
```
特定のコンパイラまたは設定で別の問題が発生した場合は、サイト管理者までお問い合わせください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

非常に大規模なプロジェクトでは、CodeQL でランナーのディスクまたはメモリが不足する場合があります。この問題が生じたら、ランナー上のメモリを増やしてみてください。

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

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

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

リソースの場所を確認した後、正しい場所を指定するようにワークフローを更新できます。 Go 分析で追加のクエリを実行する場合、ソースファイルの場所の変更の影響を受けている可能性があります。詳しくは、github/codeql-go リポジトリで「場所の変更のお知らせ: github/codeql への github/codeql-go の移動」を参照してください。

警告: "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 ワークフローのトラブルシューティング

この記事の内容