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

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

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

書き込み アクセスを持つユーザー 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` プロセスを使用するために追加のソフトウェアのインストールが必要になる場合があります。 さらに、リポジトリに特定のバージョンのビルドツールが必要な場合は、手動でインストールする必要があります。

メモ

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

C/C++ のビルド

          CodeQL は、C/C++ コード `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# のビルド

          CodeQL では、C# コードのビルド モード `none`、 `autobuild` 、または `manual` がサポートされています。

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

C# のビルドなし

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

依存関係は、複数のヒューリスティックと戦略を使用して復元されます。 情報の主なソースは、*.csproj、*.sln、nuget.config、packages.config、global.json、project.assets.json です。 プライベート 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 のビルド

          CodeQL は、Go コードのビルド モード `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 言語を自動的にインストールする go.mod ファイルが検索されます。

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

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

さらに、 vendor ディレクトリは既定で CodeQL Go 分析から除外されます。 これをオーバーライドするには、--extractor-option extract_vendor_dirs=trueを使用するときに CodeQL CLI オプションを渡すか、環境変数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のランナー要件](#runner-requirements-for-java)を参照してください。


          プライベート Maven レジストリが組織に対して定義されている場合は、これも使用されます。 [プライベート レジストリへの既定のセットアップ アクセスをスキャンするコード](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries) と、 [既定のセットアップをスキャンするコードがプライベート レジストリを使用したかどうかを確認](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries)する方法を参照してください。

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 のビルド

          CodeQL では、Swift コードのビルド モード `autobuild` または `manual` がサポートされています。

Swift の自動ビルドの概要

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

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

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

          GitHub ホスト型 macOS ランナーは、Linux および Windows ランナーよりもコストが高いので、分析するコードのみをビルドすることをお勧めします。 
          GitHubホストランナーの価格の詳細については、[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) を参照してください。

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

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

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

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

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