コンパイル済み言語の CodeQL ビルド オプションと手順

CodeQL がコンパイルされた言語を構築する方法について説明します。これには、C/C++、C#、Go、Java、Kotlin、Rust、Swift で使用可能なビルド モードと言語固有の自動ビルド動作が含まれます。

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

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

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

  • GitHub.com 上のパブリックリポジトリ
  • GitHub Team、GitHub Enterprise Cloud、または GitHub Enterprise Server 上の組織所有リポジトリ。 GitHub Code Security が 有効になっています。

この記事で

コンパイル型言語のオートビルドステップ

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

メモ

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

C/C++ のビルド

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

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

C/C++ 用のビルドなし

CodeQL は、ソース ファイル拡張子を介して C/C++ コンパイル ユニットを推論します。 見つかったソース ファイルごとに、コンパイル フラグとインクルード パスは、動作するビルド コマンドを必要とせずにコードベースを調べることによって推論されます。

C/C++ のビルドを伴わない分析の精度

ビルドなしで CodeQL C/C++ データベースを作成すると、場合によっては autobuild または手動のビルド 手順を使用するよりも正確な結果が得にくい場合があります。たとえば、次のような場合です。

  • このコードは、既存のヘッダーでは使用できないカスタム マクロ/定義に大きく依存します
  • コードベースには多くの外部依存関係があります

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

  • 関連するソース ファイルに含まれるヘッダー ファイルにカスタム マクロと定義を配置する
  • システムインクルードディレクトリまたはワークスペースで外部依存関係（ヘッダーファイル）が利用可能であることを確認する
  • ターゲット プラットフォームで抽出を実行します。 たとえば、Windows ランナーを選択してWindows プロジェクトを分析し、プラットフォーム固有のヘッダーとコンパイラにアクセスできるようにします。

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

サポートされているシステムの種類システム名
オペレーティング システムWindows、macOS、Linux
ビルドシステムWindows: MSbuild スクリプトと build スクリプト
Linux と macOS: Autoconf、Make、CMake、qmake、Meson、Waf、SCons、Linux Kbuild、ビルドスクリプト
          `autobuild` ステップの動作は、抽出を実行するオペレーティング システムによって異なります。

Windows自動検出

Windowsでは、autobuild ステップは、次の方法を使用して、C/C++ に適したビルド メソッドの自動検出を試みます。

  1. ルートに最も近いソリューション (MSBuild.exe) またはプロジェクト (.sln) ファイルで .vcxproj を呼び出します。

           `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 ランナーはpowershell.exeをPATHに置く必要があります。

C# のビルド

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

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

C# のビルドなし

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

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

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

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

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

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

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

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

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

C# の自動ビルドの概要

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

Windows自動検出

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

  1. ルートに最も近いソリューション (dotnet build) またはプロジェクト (.sln) ファイルで .csproj を呼び出します。

  2. ルートに最も近いソリューションまたはプロジェクトファイルで MSBuild.exe を呼び出します。

           `autobuild` が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクト ファイルを検出した場合、それらすべてのビルドが試みられます。

  3. ビルド スクリプトのように見えるスクリプト build.bat、build.cmd、build.exe を、この順番で呼び出します。

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

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

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

Windows ランナーはpowershell.exeをPATHに置く必要があります。

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

Linux と macOS の自動検出

  1. ルートに最も近いソリューション (dotnet build) またはプロジェクト (.sln) ファイルで .csproj を呼び出します。

  2. ルートに最も近いソリューションまたはプロジェクトファイルで MSbuild を呼び出します。

           `autobuild` が最上位ディレクトリから同じ (最短) 深度で複数のソリューションまたはプロジェクト ファイルを検出した場合、それらすべてのビルドが試みられます。

  3. ビルド スクリプトのように見えるスクリプト build、build.sh を、この順番で呼び出します。

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

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

.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、および Makefile や Ninja スクリプトを含むビルド スクリプト

Go の自動検出

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

1. make、ninja、./build、または ./build.sh を順番に呼び出し、これらのいずれかのコマンドが成功した場合は、続けて go list ./... を呼び出してください。その go list ./... も成功すれば、必要な依存関係がインストールされたことを意味します。

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

メモ

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

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

既定では、テスト コード (_test.go で終わるファイル内のコード) は分析されません。 これは、CodeQL CLI を使用する場合、または環境変数 --extractor-option extract_tests=true を CODEQL_EXTRACTOR_GO_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` に変更されます。 または、高度なセットアップに変更することもできます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/kotlin-detected-in-no-build)」をご覧ください。

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 バージョンをインストールし、PATH 変数に存在する必要があります (java と javac を見つけることができます)。

  • 複数のバージョンの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 ランナーはpowershell.exeをPATHに置く必要があります。

Rust の構築

CodeQL では、Rust コードのビルド モードの none がサポートされています。

Rust 用のビルドなし

CodeQL では、 rust-analyzer を使用してビルド スクリプト (build.rs ファイル) をコンパイルして実行し、マクロ コードをコンパイルしますが、完全なビルドは呼び出しません。 存在するすべての Rust ファイルからデータベースが作成されます。 Cargo.tomlまたはrust-project.json ファイルが存在する必要があります。

Rust のランナー要件

Rust 分析では、 rustup と cargo をインストールする必要があります。

Swift のビルド

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

Swift の自動ビルドの概要

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

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

Swift コードのコード スキャンでは、既定で macOS ランナーが使用されます。 GitHub がホストしている macOS ランナーは、Linux や Windows ランナーよりもコストが高いので、分析するコードのみをビルドするようにお勧めします。 GitHub ホスト ランナーの価格の詳細については、「GitHub Actions の課金」をご覧ください。

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

CodeQL 分析ワークフロー

での Swift コンパイルのカスタマイズ

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

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

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