Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。

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

code scanning のセットアップで問題が発生している場合は、問題を解決するためのヒントを使用してトラブルシューティングできます。

Code scanning は、GitHub Enterprise Server の Organization 所有のリポジトリで利用できます。 この機能には、GitHub Advanced Security のライセンスが必要です。 詳細については、「GitHub Advanced Security について」を参照してください。

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

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

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

CodeQL デバッグ成果物の作成

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

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

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

ワークフローでフラグを使用して CodeQL デバッグ成果物を作成できます。 このためには、CodeQL analysis workflow ファイルの 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 でコードを監視できなかったことを示します。 このようなエラーが発生する理由として、次のようなものがあります。

  1. リポジトリには、CodeQL でサポートされている言語で記述されたソースコードが含まれていない場合があります。 サポートされている言語の一覧を確認し、その場合は CodeQL ワークフローを削除します。 詳細については、「CodeQL による code scanning について」を参照してください。

  2. 自動言語検出により、サポートされている言語が特定されたが、リポジトリにその言語の分析可能なコードがない。 一般的な例としては、言語検出サービスが .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」(コンパイル言語の自動ビルドが失敗する) のワークフロー抽出を参照してください。

  3. code scanning ワークフローでコンパイル言語 (C、C++、C#、 または Java) が分析されているが、コードはコンパイルされていない。 デフォルトでは、CodeQL 分析ワークフローには autobuild ステップが含まれていますが、このステップはベスト エフォートプロセスを表しており、特定のビルド環境によっては、コードのビルドに失敗する可能性があります。 autobuild ステップを削除し、ビルド ステップを手動で含めない場合も、コンパイルが失敗する可能性があります。 ビルド ステップの指定の詳細については、「コンパイル言語用の CodeQL ワークフローの構成 を参照してください」。

  4. ワークフローでコンパイル言語 (C、C++、C#、 または Java) が分析されているが、パフォーマンスを向上させるためにビルドの一部がキャッシュされている (Gradle や Bazel などのビルド システムで発生する可能性が最も高い)。 CodeQL はコンパイラのアクティビティを監視してリポジトリ内のデータフローを理解するため、CodeQL は分析を実行するために完全なビルドを実行する必要があります。

  5. ワークフローでコンパイル言語 (C、C++、C#、 または Java) が分析されているが、ワークフローの initanalyze ステップの間でコンパイルが行われていない。 CodeQL では、コンパイラのアクティビティを監視して分析を実行するために、これらの 2 つのステップ間でビルドを行う必要があります。

  6. コンパイル済みコード (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
    

    特定のコンパイラまたは設定で別の問題が発生した場合は、your site administrator までお問い合わせください。

ビルド ステップの指定の詳細については、「コンパイル言語用の CodeQL ワークフローの構成 を参照してください」。

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

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

  1. CodeQL の autobuild 機能では、ヒューリスティックを使用してリポジトリにコードがビルドされます。 ただし、このアプローチではリポジトリの分析が不完全になることがあります。 たとえば、1 つのリポジトリに複数の build.sh コマンドが存在する場合、autobuild ステップで実行されるコマンドは 1 つのみであるため、一部のソース ファイルがコンパイルされない可能性があります。したがって、分析が完了しない可能性があります。
  2. 一部のコンパイラは 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

これにより、ローカル コンピューターにダウンロードできるアクション成果物としてデータベースがアップロードされます。 詳細については、「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 などの言語の場合、追加の構成オプションを指定して分析するコードの量を制限できます。 詳細については、「code scanning のカスタマイズ」を参照してください。

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

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 などの言語の場合、追加の構成オプションを指定して分析するコードの量を制限できます。 詳細については、「code scanning のカスタマイズ」を参照してください。

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

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

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

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

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

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

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

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

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

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

      ...

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