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

メモ: この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。企業でより新しいバージョンの CodeQL アクションを使用している� �合は、最新の機能の詳細について GitHub Enterprise Cloud の記事を参照してく� さい。最新バージョンの使用については、「Configuring code scanning for your appliance」(アプライアンスのコードスキャニングの構成) を参照してく� さい。

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

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

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

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

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@v1
        with:
          languages: ${{ matrix.language }}
```
ワークフローの編集の詳細については、「Configuring 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 とは別のコンテナで実行している。詳細については、「Running CodeQL code scanning in a container」(コンテナーでの CodeQL コードスキャンの実行) を参照してく� さい。
- デーモンプロセスを使用して、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@v1
  with:
    debug: true

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

成果物には、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 などの言語の� �合、追� の構成オプションを指定して分析するコードの量を制限できます。詳細については、「Specifying directories to scan」(スキャンするディレクトリの指定) を参照してく� さい。

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

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

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

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

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

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

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

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

既定の CodeQL analysis workflowでは、言語のマトリックスを使います。これにより、各言語の解析が並列で実行されます。「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 などの言語の� �合、追� の構成オプションを指定して分析するコードの量を制限できます。詳細については、「Specifying directories to scan」(スキャンするディレクトリの指定) を参照してく� さい。

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

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

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

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

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

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

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

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

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

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

エラー: ".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@v2

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

      ...

CodeQL ワークフローファイルの編集の詳細については、「code scanning の構成」を参照してく� さい。