コンパイル済み言語の CodeQL コード スキャン

必要に応じて CodeQL によるコンパイル型言語の分析方法、利用可能なビルド オプション、データベース作成プロセスのカスタマイズ方法について理解しましょう。

この機能を使用できるユーザーについて

書き込み アクセスを持つユーザー if advanced setup is already enabled

Code scanning は、次のリポジトリの種類で使用できます。

  • GitHub.com 上のパブリックリポジトリ
  • GitHub Code Security が有効になっている GitHub Team または GitHub Enterprise Cloud 上の organization 所有のリポジトリ

この記事の内容

CodeQL 分析ワークフローとコンパイル型言語について

Code scanning は、1 つ以上の CodeQL データベースに対してクエリを実行することにより機能します。 各データベースには、リポジトリにあるコードが 1 つの言語で表わされたものが含まれています。 C/C++、C#、Go、Java、Kotlin、Rust (パブリック プレビュー)、、Swift のようなコンパイル言語では、こうしたデータベースの作成プロセスにコードのビルドとデータの抽出が必要になることがよくあります。

code scanning を有効にすると、既定のセットアップおよび拡張されたセットアップの両方で、利用できる最も簡単な方法で分析用の CodeQL データベースが作成されます。 C/C++、C#、 Java の場合、CodeQL データベースは、ビルド (none ビルド モード) を必要とせずにコードベースから直接作成されます。 他のコンパイル型言語の場合、autobuild ビルド モードを使用して CodeQL によりコードベースがビルドされます。 または、manual ビルド モードを使用して明示的なビルド コマンドを指定し、これらのカスタム コマンドによってビルドされたファイルのみを分析することもできます。

CodeQL で依存関係キャッシュを使用して、依存関係をレジストリからダウンロードするのではなく、GitHub Actions キャッシュとして格納できます。 詳細については、この記事で後述する「CodeQL の依存関係キャッシュについて」を参照してください。

CodeQL ビルド モデル

CodeQL アクションでは、コンパイル型言語に対して次の 3 つの異なるビルド モードがサポートされています。

  • none - CodeQL データベースは、コードベースをビルドすることなくコードベースから直接作成されます (すべてのインタプリタ型言語でサポートされ、C/C++、C#、 Java でもサポートされています)。
  • autobuild - CodeQL は、可能性が最も高いビルド方法を検出します。また、これを使用してコードベースをビルドし、分析用のデータベースを作成します (すべてのコンパイル型言語でサポートされています)。
  • manual - ワークフローでコードベースに使うビルド ステップを定義します (Rust を除くすべてのコンパイル言語でサポートされています)。

ビルド モードの比較

ビルド モードの特性なしAutobuild手動
既定のセットアップと組織レベルの有効化に使用はい (C/C++、C#、 Java)はい (none がサポートされていない場所)いいえ
分析はユーザー構成なしで成功はい変数いいえ
分析の完全性生成されたコードが分析されない変数ユーザー制御
分析の正確性[良い][良い]最高

推奨事項

code scanning を初めて設定する場合、または複数のリポジトリ間で設定する場合は、既定のセットアップを使用することをお勧めします。 既定のセットアップでは、CodeQL データベースを生成してコードを分析するための最も簡単な方法が使用されるため、すぐにアラートの変更を開始できます。 最初のアラートを解決したら、リスクの高いリポジトリ用の手動のビルド プロセスを使用して高度なセットアップに切り替えることができます。

多言語リポジトリでの複数のビルド モードの使用

複数のコンパイル型言語を持つリポジトリの場合は、言語ごとに異なるビルド モードを使用できます。 たとえば、リポジトリに C/C++、C#、Java が含まれている場合は、1 つの言語 (ここでは C/C++) に手動でビルド ステップを指定できます。 このワークフローでは、言語ごとに異なるビルド モードを指定します。

strategy:
  matrix:
    include:
      # Analyzes C and C++ code using the commands in `Build C and C++ code`
      - language: c-cpp
        build-mode: manual
      # Analyzes C# code by automatically detecting a build
      - language: csharp
        build-mode: autobuild
      # Analyzes Java code directly from the codebase without a build
      - language: java-kotlin
        build-mode: none # analyzes Java only
steps:
- name: Checkout repository
  uses: actions/checkout@v4

# Initializes CodeQL tools and creates a codebase for analysis.
- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
- if: ${{ matrix.build-mode == 'manual' }}
  name: Build C and C++ code
  run: |
    echo 'If you are using a "manual" build mode for one or more of the' \
      'languages you are analyzing, replace this with the commands to build' \
      'your code, for example:'
    echo ' make bootstrap'
    echo ' make release'
    exit 1

最新バージョンの CodeQL でサポートされている言語、ライブラリ、フレームワークについては、CodeQL ドキュメントの「サポートされている言語とフレームワーク」を参照してください。 最新バージョンの CodeQL を実行するためのシステム要件については、CodeQL ドキュメントの「システム要件」を参照してください。

CodeQL の依存関係キャッシュについて

CodeQL で依存関係キャッシュを使用して、依存関係をレジストリからダウンロードするのではなく、GitHub Actions キャッシュとして格納できます。 これにより、サードパーティのレジストリがうまく機能しない場合にアラートが失われるリスクが軽減され、多数の依存関係を持つプロジェクトや低速のレジストリで動作するプロジェクトのパフォーマンスが向上する可能性があります。 依存関係をキャッシュしてワークフローを高速化する方法の詳細については、「依存関係キャッシュのリファレンス」を参照してください。

依存関係キャッシュはすべてのビルド モードで機能し、Java、Go、C# でサポートされています。

メモ

依存関係キャッシュを使用すると、リポジトリのキャッシュ クォータの対象となる CodeQL 固有のキャッシュが格納されます。 「依存関係キャッシュのリファレンス」を参照してください。

CodeQL の依存関係キャッシュを有効にする

既定のセットアップ ワークフローでは、依存関係キャッシュは、パブリックおよびプライベート リポジトリ内の GitHub ホステッド ランナーに対してのみ有効になっています。

高度なセットアップ ワークフローの場合、依存関係キャッシュは既定で無効になっています。 CodeQL の依存関係キャッシュを有効にするには、高度なセットアップ ワークフローで CodeQL アクション用に dependency-caching 設定を使用します。 この設定は、次の値を受け入れます。

  • false/none/off: 依存関係キャッシュが無効 (既定)
  • restore: 既存のキャッシュのみを復元し、新しいキャッシュを格納しない
  • store: 新しいキャッシュのみを格納し、既存のキャッシュを復元しない
  • true/full/on: 既存のキャッシュを復元し、新しいキャッシュを格納する

たとえば、次の設定を使用すると、CodeQL アクションの依存関係キャッシュが有効になります。

    # Initializes CodeQL with dependency caching enabled
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: java
        dependency-caching: true

CodeQL の Build mode none について

C/C++、C#、 Java では、リポジトリに Kotlin コードも含まれている場合を除き、code scanning のデフォルトのセットアップを有効にすると、CodeQL はビルドを必要とせずにデータベースを作成します。 リポジトリに、Java コードに加えて Kotlin コードも含まれている場合、Kotlin 解析にはビルドが必要であるため、自動ビルド プロセスでデフォルトのセットアップが有効になります。

ビルドなしで CodeQL データベースを作成すると、次の場合に、autobuild または手動のビルド手順を使用するよりも精度の低い結果が生成される可能性があります。

  • ビルド スクリプトが依存関係情報をクエリできないため、依存関係の推測が不正確です。
  • 通常、リポジトリはビルド プロセス中にコードを生成します。

autobuild または手動のビルド手順を使用するには、高度なセットアップを使用します。

メモ

Java 解析で build-mode が none に設定され、リポジトリ内に Kotlin コードが含まれている場合、Kotlin コードは解析されず、警告が生成されます。 「Java と Kotlin のビルド」を参照してください。

CodeQL の Autobuild について

CodeQL アクションでは、次の場合に autobuild を使用してコンパイル型言語を分析します。

  • 既定のセットアップが有効になっており、その言語が none ビルドをサポートしていない (C/C++、C#、 Java ではサポートされています)。
  • 詳細設定が有効になっており、ワークフローで build-mode: autobuild が指定されている。
  • 高度なセットアップが有効で、ワークフローに autobuild アクション (github/codeql-action/autobuild@v3) を使用した言語用の Autobuild ステップがある。

build-mode オプションの使用例

# Initializes the CodeQL tools for scanning.
name: Analyze
strategy:
  matrix:
    include:
      # Analyze C and C++ code
      - language: c-cpp
        build-mode: autobuild
      # Analyze Go code
      - language: go
        build-mode: autobuild

steps:
  - uses: github/codeql-action/init@v3
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}

Autobuild ステップの使用例

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}

    - name: Autobuild
      uses: github/codeql-action/autobuild@v3

ビルド ステップを手動で指定する方法について

手動のビルド手順は、高度なセットアップを有効にした場合にのみ指定できます。「コード スキャンの高度なセットアップの構成」を参照してください。

autobuild が失敗した場合、または autobuild プロセスによってビルドされたソース ファイルとは異なるソース ファイルのセットを分析する場合は、次の操作を行う必要があります。

  • ワークフローで言語のビルド モードを指定する場合は、ビルド モードを manual に変更します。
  • ワークフローに autobuild ステップが含まれている場合は、ワークフロー内の autobuild ステップを削除するかコメントにします。

次に、run ステップをコメント解除し、使用するビルド プロセスを手動で指定します。 C/C++、C#、Go、Java、Kotlin、Rust (パブリック プレビュー)、、Swift の場合、CodeQL は、指定したビルド ステップによってビルドされたソース コードを分析します。ワークフロー ファイルの編集方法については、「コード スキャン用の高度なセットアップのカスタマイズ」を参照してください。

ワークフローを更新して、build-mode を manual と定義します。

# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    build-mode: manual
- uses: github/codeql-action/analyze@v3
  with:
    category: "/language:${{ matrix.language }}"

または「Autobuild」ステップをコメントにして、ワークフローを更新します。

    # Autobuild attempts to build any compiled languages.
    # - name: Autobuild
    #  uses: github/codeql-action/autobuild@v3

ビルド コマンドの指定

手動ビルドが有効になっている場合は、ワークフローの run ステップをコメント解除し、リポジトリに適したビルド コマンドを追加します。 run ステップでは、オペレーティング システムのシェルを使用してコマンド ライン プログラムが実行されます。 これらのコマンドを変更し、別のコマンドを追加してビルド プロセスをカスタマイズできます。

- run: |
    make bootstrap
    make release

run キーワードの詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

コンパイル言語にマニュアルのビルドステップを追加しても、リポジトリで依然としてcode scanningが動作しない場合は、GitHub サポート ポータルにお問い合わせください。

コンパイル型言語の Autobuild ステップ

GitHub でホストされるランナーは、常に autobuild が必要とするソフトウェアで実行されます。 GitHub Actions にセルフホスト ランナーを使用する場合は、autobuild プロセスを使用するために追加のソフトウェアのインストールが必要になる場合があります。 さらに、リポジトリに特定のバージョンのビルドツールが必要な場合は、手動でインストールする必要があります。 自己ホスト ランナーの場合は、依存関係をランナー自体に直接インストールする必要があります。 これらの言語については、この記事の各 autobuild セクションで C/C++、C#、Java の一般的な依存関係の例を示します。 詳細については、「セルフホステッド ランナー」を参照してください。

メモ

ワークフローで language マトリックスを使っている場合、autobuild はマトリックスに列記された各コンパイル型言語のビルドを試行します。 マトリックスがない場合、autobuild は、サポートされているコンパイル型言語で、リポジトリ内のソース ファイルの数が最も多いもののビルドを試みます。 Go を除いて、明示的にビルドコマンドを使用しない限り、リポジトリにある他のコンパイル型言語の解析は失敗します。

C/C++ のビルド

C/C++ コードの場合、CodeQL は、ビルド モード none、autobuild、または manual をサポートしています。

C/C++ コードを含むリポジトリに対して既定のセットアップを有効にすると、ビルド モードは自動的に none に設定されます。

メモ

C/C++ コードベースのビルド モード none のサポートは現在 パブリック プレビュー 段階であり、変更される可能性があります。

C/C++ の自動ビルドの概要

サポートされているシステムの種類システム名
オペレーティング システムWindows、macOS、Linux
ビルドシステムWindows: MSbuild スクリプトと build スクリプト
Linux と macOS: Autoconf、Make、CMake、qmake、 Meson、Waf、SCons、Linux Kbuild、build の各スクリプト

autobuild ステップの動作は、抽出を実行するオペレーティング システムによって異なります。

Windows の自動検出

Windows の autobuild ステップでは、以下の方法を使って C/C++ に適したビルド方法の自動検出が試みられます。

  1. ルートに最も近いソリューション (.sln) またはプロジェクト (.vcxproj) ファイルで MSBuild.exe を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクト ファイルを検出した場合、それらすべてのビルドが試みられます。
  2. ビルド スクリプトのように見えるスクリプト、つまり build.bat、build.cmd、build.exe を、この順番で呼び出します。

Linux と macOS の自動検出

Linux と macOS の autobuild ステップでは、リポジトリ内にあるファイルが確認されて、使われているビルド システムが特定されます。

  1. ルートディレクトリでビルドシステムを探します。
  2. 何も見つからない場合は、C/C++ のビルドシステムで一意のディレクトリをサブディレクトリで検索します。
  3. 適切なコマンドを実行してシステムを設定します。

C/C++ のランナー要件

Ubuntu Linux ランナー上で autobuild を使うと、検出された構成とビルド ステップに必要な依存関係を自動的にインストールしようとする場合があります。 デフォルトでこの動作は、GitHub でホストされるランナーでは有効化され、セルフホストされる ランナーでは無効化されます。 この機能を明示的に有効または無効にするには、環境内の CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES に true あるいは false を設定します。 環境変数の定義の詳細な情報については、「変数に情報を格納する」を参照してください。

セルフホステッド ランナーの場合、依存関係の自動インストールが有効になっていない限り、gcc コンパイラをインストールする必要があり、特定のプロジェクトでは、clang または msvc の実行可能ファイルへのアクセスも必要になる場合があります。 また、プロジェクトが依存するビルド システム (msbuild、make、cmake、bazel など) とユーティリティ (python、perl、lex、yacc など) をインストールする必要もあります。 依存関係の自動インストールを有効にする場合は、ランナーで Ubuntu を使っていること、パスワードなしで sudo apt-get を実行できることを確認する必要があります。

Windows ランナーでは、PATH が powershell.exe に存在する必要があります。

C# のビルド

C# コードの場合、CodeQL は、ビルド モード none、autobuild、または manual をサポートしています。

C# コードを含むリポジトリに対してデフォルトのセットアップを有効にすると、ビルド モードは自動的に none に設定されます。

C# のビルドなし

CodeQL では、すべてのソース ファイルと依存関係からデータベースを作成する前に依存関係が復元され、さらにいくつかのソース ファイルが生成されて、より正確な結果が得られます。

依存関係は、複数のヒューリスティックと戦略を使用して復元されます。 情報の主なソースは、*.csproj、*.sln、nuget.config、packages.config、global.json、project.assets.json です。 Organization に対してプライベート NuGet フィードが定義されている場合は、それも使われます。詳細については、「プライベート レジストリに対するコード スキャンの既定の設定アクセス」と「コード スキャンの既定の設定でプライベート レジストリが使われているかどうかを判断する」を参照してください。

次の生成されたソース ファイルは省略可能ですが、CodeQL データベースの正確性を大幅に向上させます。

  • MSbuild の暗黙的な using 機能を処理する using ディレクティブを生成する global。
  • ASP.NET Core ビュー ファイル、.cshtml ファイルは、.cs ファイルに変換されます。

依存関係アセンブリ名、生成されたソース ファイル、プライベート フィードに格納されている依存関係、リポジトリ内のソース ファイルの情報がコンパイルされ、CodeQL データベースの作成に使われます。

C# のビルド解析なしの正確性

完全なコードをビルドせずに CodeQL データベースを作成することは、依存関係を復元できること、およびリポジトリ内のソース ファイルをまとめてコンパイルできることに依存します。 依存関係の復元またはソース コードのコンパイルで問題が発生すると、CodeQL データベースと code scanning 解析結果の正確性に影響する可能性があります。

次の手順を実行すると、より正確な解析を行うことができます。

  • パブリック インターネットへのアクセスを提供するか、プライベート NuGet フィードへのアクセスを使用できることを確認します。「プライベート レジストリに対するコード スキャンの既定の設定アクセス」を参照してください。
  • リポジトリに同じ NuGet 依存関係の複数のバージョンが必要かどうかをチェックします。 CodeQL は 1 つのバージョンのみを使用できます。通常は、複数のバージョンがあるより新しいバージョンを選択します。 この方法は、すべてのリポジトリでは機能しない場合があります。
  • net48、net5.0、netstandard1.6 など、複数のバージョンの NET が参照されているかどうかをチェックします。 CodeQL は 1 つのバージョンしか使用できないため、正確性に影響する可能性があります。
  • クラス名の競合を避けてください。競合すると、メソッド呼び出しターゲットが見つからない可能性があり、データフロー解析に影響を及ぼします。

C# の自動ビルドの概要

サポートされているシステムの種類システム名
オペレーティング システムWindows、macOS、Linux
ビルドシステム.NET と MSbuild、およびビルドスクリプト

Windows の自動検出

autobuild プロセスは、次の方法を使って C# に適したビルド方法の自動検出を試みます。

  1. ルートに最も近いソリューション (.sln) またはプロジェクト (.csproj) ファイルで dotnet build を呼び出します。
  2. ルートに最も近いソリューションまたはプロジェクトファイルで MSBuild.exe を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクト ファイルを検出した場合、それらすべてのビルドが試みられます。
  3. ビルド スクリプトのように見えるスクリプト build.bat、build.cmd、build.exe を、この順番で呼び出します。

Windows での C# のランナー要件

セルフホステッド ランナーでの .NET Core アプリケーション開発では、(dotnet には) .NET SDK が必要です (for )。

.NET Framework アプリケーション開発の場合、Microsoft Build Tools (msbuild 用) と NuGet CLI (nuget 用) が必要です。

Windows ランナーでは、PATH が powershell.exe に存在する必要があります。

CodeQL データベースを作成する場合は、build-mode: none を使用してパブリック インターネットへのアクセスも提供する必要があります。また、プライベート NuGet フィードへのアクセスを確実に使用できるようにする必要があります。

Linux と macOS の自動検出

  1. ルートに最も近いソリューション (.sln) またはプロジェクト (.csproj) ファイルで dotnet build を呼び出します。
  2. ルートに最も近いソリューションまたはプロジェクトファイルで MSbuild を呼び出します。 autobuild が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクト ファイルを検出した場合、それらすべてのビルドが試みられます。
  3. ビルド スクリプトのように見えるスクリプト build、build.sh を、この順番で呼び出します。

Linux および macOS での C# のランナー要件

セルフホステッド ランナーでの .NET Core アプリケーション開発では、(dotnet には) .NET SDK が必要です (for )。

.NET Framework アプリケーション開発では、Mono ランタイム (mono、msbuild、または nuget を実行するため) が必要です。

CodeQL データベースを作成する場合は、build-mode: none を使用してパブリック インターネットへのアクセスも提供する必要があります。また、プライベート NuGet フィードへのアクセスを確実に使用できるようにする必要があります。

手動ビルド用に CodeQL によって挿入された C# コンパイラ フラグ

CodeQL トレーサーを使用すると、ビルド プロセスをインターセプトし、関連する CodeQL 言語エクストラクターに情報を転送することで、すべてのコンパイル済み言語を抽出できます。 トレーサーは、C# コンパイラの呼び出しに特定のフラグを挿入して、すべてのコンポーネントが CodeQL データベースに確実に組み込まれるようにします。これにより、C# コードが CodeQL 分析時に予想される内容とは異なる方法でビルドされる可能性があります。

/p:MvcBuildViews=true

このオプションを true に設定すると、ASP.NET model-view-controller (MVC) プロジェクトのビューがビルド プロセスの一部としてプリコンパイルされるため、エラーを取得してパフォーマンスを向上させることができます。 トレーサーによりこのフラグが挿入されることで、これらのビューから生成されたコードを通るデータフローを含む可能性のあるセキュリティ問題が CodeQL により検出されハイライトされるようにします。 詳細については、Microsoft Learn の「MVC アプリケーションへのビューの追加」を参照してください。

/p:UseSharedCompilation=false

このオプションを false に設定すると、共有コンパイル機能の使用が無効になります。これにより、ビルド時間が遅くなる可能性があります。 /p:UseSharedCompilation=false が指定されていない場合、msbuild によりコンパイラ サーバー プロセスが開始され、その 1 つのプロセスによってすべてのコンパイルが実行されます。 ただし、CodeQL トレーサーは、新しく作成されたプロセスの引数の検査に依存します。

/p:EmitCompilerGeneratedFiles=true

このオプションを true に設定すると、ビルド プロセス中にコンパイラによって生成されたファイルが出力されます。 このオプションにより、正規表現のサポートの強化、シリアル化、Web アプリケーション ビューの作成などの機能のサポートに使用される追加のソース ファイルがコンパイラにより生成されます。 これらの生成されたアーティファクトは、通常、コンパイラによってディスクに書き込まれるのではなく、オプションを true に設定すると、強制的にファイルがディスクに書き込まれるので、エクストラクターがファイルを処理できます。

一部のレガシ プロジェクトや、.sqlproj ファイルを使用するプロジェクトでは、挿入された /p:EmitCompilerGeneratedFiles=true プロパティによって、msbuild で予期しない問題が発生する場合があります。 このトラブルシューティングの詳細については、「C# コンパイラの予期せぬ失敗」を参照してください。

Go のビルド

Go コードの場合、CodeQL は、ビルド モード autobuild または manual をサポートしています。

Go の自動ビルドの概要

サポートされているシステムの種類システム名
オペレーティング システムWindows、macOS、Linux
ビルドシステムGo モジュール、dep、Glide、およびメイクファイルや Ninja スクリプトを含むビルド スクリプト

Go の自動検出

autobuild プロセスは、すべての .go ファイルを抽出する前に、Go リポジトリで必要な依存関係をインストールする適切な方法の自動検出を試みます。

  1. make、ninja、または ./build を、これらのコマンドのいずれかが成功し、その後の ./build.sh も成功して、必要な依存関係がインストールされたことを示すまで、(この順序で) 呼び出go list ./...します。
  2. これらのコマンドがいずれも成功しなかった場合は、go.mod、Gopkg.toml、または glide.yaml を探し、それぞれの go get (ベンダーが使用していない場合)、dep ensure -v、または glide install を実行して、依存関係のインストールを試みます。
  3. 最後に、これらの依存関係マネージャーの構成ファイルが見つからない場合は、GOPATH に追加するのに適したリポジトリ ディレクトリ構造に調整し直し、go get を使って依存関係をインストールします。 抽出が完了すると、ディレクトリ構造は通常に戻ります。
  4. go build ./... を実行するのと同じようにして、リポジトリ内のすべての Go コードを抽出します。

メモ

既定のセットアップを使用すると、go.mod ファイルが検索され、互換性のあるバージョンの Go 言語が自動的にインストールされます。

Go のエクストラクター オプション

既定では、テスト コード (_test.go で終わるファイル内のコード) は分析されません。 これは、CodeQL CLI を使用する場合、または環境変数 CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS を true に設定することで、オプション --extractor-option extract_tests=true でオーバーライドできます。

さらに、既定では、vendor ディレクトリは CodeQL Go 分析から除外されます。 これをオーバーライドするには、CodeQL CLI を使用する場合に --extractor-option extract_vendor_dirs=true オプションを渡すか、環境変数 CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS を true に設定します。

Java と Kotlin のビルド

CodeQL は次のビルド モードをサポートしています。

  • Java: none、autobuild、または manual
  • Kotlin: autobuild または manual

リポジトリの既定のセットアップを最初に有効にし、Java コードのみが検出された場合、ビルド モードは none に設定されます。 Kotlin、または Java および Kotlin コードの組み合わせが検出された場合、ビルド モードは autobuild に設定されます。

none ビルド モードを使用するリポジトリに Kotlin コードを後から追加すると、CodeQL 分析によって、Kotlin がサポートされていないことを説明する警告メッセージが報告されます。 既定のセットアップを無効にして、再度有効にする必要があります。 既定のセットアップを再度有効にすると、両方の言語を分析できるようにビルド モードが autobuild に変更されます。 または、高度なセットアップに変更することもできます。 詳しくは、「警告: ビルドなしでは処理できない X Kotlin ファイルがプロジェクト内で検出されました」をご覧ください。

Java のビルドなし

CodeQL は、存在するすべての Java ファイルからデータベースを作成する前に、(ビルドを起動するためではなく) 正確な依存関係情報を抽出するために Gradle または Maven を実行しようとします。 すべてのルート Maven または Gradle プロジェクト ファイル (上位ディレクトリにビルド スクリプトが存在しないビルド スクリプト) では依存関係情報の照会が行われ、競合がある場合は、より新しい依存関係バージョンが優先されます。 Maven または Gradle を実行するためのランナー要件については、「Java のランナー要件」を参照してください。

Organization に対してプライベート Maven レジストリが定義されている場合は、それも使われます。詳細については、「プライベート レジストリに対するコード スキャンの既定の設定アクセス」と「コード スキャンの既定の設定でプライベート レジストリが使われているかどうかを判断する」を参照してください。

Java のビルド解析なしの正確性

ビルドなしで CodeQL の Java データベースを作成すると、次の場合に、autobuild または手動のビルド手順を使用するよりも精度の低い結果が生成される可能性があります。

  • Gradle または Maven ビルド スクリプトの依存関係情報を照会できないため、依存関係の推測 (Java パッケージ名に基づく) が不正確です。
  • 通常、リポジトリはビルド プロセス中にコードを生成します。 これは、別のモードを使用して CodeQL データベースを作成した場合に分析されます。

次の手順を実行すると、より正確な解析を行うことができます。

  • パブリック インターネットへのアクセスを提供するか、プライベート成果物リポジトリへのアクセスを使用できることを確認します。「プライベート レジストリに対するコード スキャンの既定の設定アクセス」を参照してください。
  • リポジトリに同じ依存関係の複数のバージョンが必要かどうかをチェックします。 CodeQL は 1 つのバージョンのみを使用できます。通常は、複数のバージョンがあるより新しいバージョンを選択します。 この方法は、すべてのリポジトリでは機能しない場合があります。
  • 異なるソース Java ファイルで複数のバージョンの JDK API が必要かどうかを確認します。 複数のバージョンが表示された場合、CodeQL では、ビルド スクリプトに必要な最高のバージョンが使用されます。 これは、より低いバージョンの JDK を必要とする一部のファイルが部分的に分析されることを意味する場合があります。 たとえば、一部のファイルで JDK 8 が必要だが、JDK 17 の要件が 1 つ以上のビルド スクリプトで見つかった場合、CodeQL は JDK 17 を使用します。 JDK 8 を必要とし、JDK 17 を使用してビルドできなかったファイルは、部分的に分析されます。
  • クラス名の競合を避けてください (たとえば、org.myproject.Test を定義している複数のファイル)。競合すると、メソッド呼び出しターゲットが見つからない可能性があり、データフロー解析に影響を及ぼします。

Java の自動ビルドの概要

サポートされているシステムの種類システム名
オペレーティング システムWindows、macOS、Linux (制限なし)
ビルドシステムGradle、Maven、Ant

Java の自動検出

autobuild プロセスは、この戦略を適用して、Java コードベース用のビルド システムの特定を試みます。

  1. ルートディレクトリでビルドファイルを検索します。 Gradle、Maven、Ant の各ビルドファイルを確認します。
  2. 最初に見つかったビルドファイルを実行します。 Gradle ファイルと Maven ファイルの両方が存在する場合は、Gradle ファイルが使用されます。
  3. それ以外の場合は、ルートディレクトリの直接サブディレクトリ内でビルドファイルを検索します。 1 つのサブディレクトリにのみビルドファイルが含まれている場合は、そのサブディレクトリで識別された最初のファイルを実行します（1 と同じ環境設定を使用）。 複数のサブディレクトリにビルドファイルが含まれている場合は、エラーを報告します。

Java のランナー要件

セルフホステッド ランナーを使用している場合は、必要なバージョンの Java が存在する必要があります。

  • 1 つのバージョンの Java を必要とするリポジトリの分析にランナーを使用する場合は、適切な JDK バージョンをインストールする必要があり、(java と javac の) PATH が設定されている必要があります。

  • 複数のバージョンの Java を必要とするリポジトリの分析にランナーを使用する場合は、適切な JDK バージョンをインストールする必要があり、toolchains.xml ファイルで指定できます。 これは、通常 Apache Maven によって使用される構成ファイルで、ツールの場所、ツールのバージョン、およびツールの使用に必要な追加の構成を指定できます。 詳細については、Apache Maven ドキュメントの「Guide to Using Toolchains」(ツールチェーンの使用ガイド) を参照してください。

次の実行可能ファイルは、さまざまな Java プロジェクトで必要になる可能性があるため、PATH 変数に設定しておく必要があります。ただし、実行ファイルはすべてのプロジェクトで必要ということではありません。

  • mvn (Apache Maven)
  • gradle (Gradle)
  • ant (Apache Ant)

また、プロジェクトが依存するビルド システム (make、cmake、bazel など) とユーティリティ (python、perl、lex、yacc など) をインストールする必要があります。

Windows ランナーでは、PATH が powershell.exe に存在する必要があります。

Swift のビルド

Swift コードの場合、CodeQL は、ビルド モード autobuild または manual をサポートしています。

Swift の自動ビルドの概要

サポートされているシステムの種類システム名
オペレーティング システムmacOS
ビルドシステムXcode

この autobuild プロセスは 、Xcode プロジェクトまたはワークスペースから最大のターゲットを構築しようとします。

Swift コードのコード スキャンでは、既定で macOS ランナーが使用されます。

Swift コードの Code scanning は、Actions Runner Controller (ARC) の一部であるランナーではサポートされていません。ARC をキャプチャするランナーでは Linux のみが使用されるため、Swift には macOS ランナーが必要です。 ただし、ARC をキャプチャする ランナーとセルフホストの macOS ランナーの両方を組み合わせることもできます。 詳しくは、「Actions Runner Controller」をご覧ください。

CodeQL 分析ワークフロー での Swift コンパイルのカスタマイズ

xcodebuild と swift build はどちらも Swift ビルドでサポートされています。 ビルド中は 1 つのアーキテクチャのみを対象にすることをお勧めします。 たとえば、xcodebuild の場合は ARCH=arm64、swift build の場合は --arch arm64 です。

archive オプションと test オプションを xcodebuild に渡すことができます。 ただし、標準の xcodebuild コマンドが推奨されています。これは最も高速で、CodeQL が成功するために必要なものがすべて揃っています。

Swift 分析では、CodeQL データベースを生成する前に、CocoaPods または Carthage によって管理される依存関係を常に明示的にインストールする必要があります。