注: この記事は、2023 年 1 月に CodeQL ドキュメント Web サイトから移行されました。
CodeQL データベースの作成について
注: この記事では、GitHub Enterprise Server 3.5 の初期リリースに含まれている CodeQL CLI 2.8.5 バンドルで使用できる機能について説明します。
サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。
CodeQL を使用してコードを分析する前に、コードに対してクエリを実行するために必要なすべてのデータが含まれた CodeQL データベースを作成する必要があります。 CodeQL データベースは、CodeQL CLI を使用して自分で作成することも、GitHub.com からダウンロードすることもできます。
CodeQL の分析は、コードからリレーショナル データを抽出し、それを使用して CodeQL データベースを構築することに依存しています。 CodeQL データベースには、コードベースに関するすべての重要な情報が含まれており、CodeQL クエリを実行することでそれを分析できます。 GitHub では、多数のオープンソース プロジェクトの CodeQL データベースを作成し、保存しています。 詳しくは、「GitHub.com から CodeQL データベースをダウンロードする」を参照してください。
CodeQL CLI を使用して、CodeQL データベースを自分で作成することもできます。 CodeQL データベースを生成する前に、次のことを行う必要があります。
- CodeQL CLI をインストールして設定する。 詳しくは、「CodeQL CLI の使用を開始する」を参照してください。
- 分析するコードベースのバージョンをチェックアウトする。 ディレクトリは、すべての依存関係が既にインストールされ、ビルドする準備ができている必要があります。
GitHub にコード スキャン アラートとして表示する結果を作成するためにサードパーティの CI システムで CodeQL CLI を使用する方法については、「CI システムでの CodeQL CLI の構成」を参照してください。 GitHub Actions を使用して CodeQL コード スキャンを有効にする方法については、「リポジトリのコード スキャンの設定」を参照してください。
実行中 codeql database create
プロジェクトのチェックアウト ルートから次のコマンドを実行すると、CodeQL データベースが作成されます。
codeql database create <database> --language=<language-identifier>
ユーザーは次のものを指定する必要があります。
<database>
: 作成する新しいデータベースへのパス。 このコマンドを実行すると、このディレクトリが作成されます。既存のディレクトリを指定することはできません。--language
: どの言語のデータベースを作成するかを表す識別子。--db-cluster
と一緒に使用する場合は、オプションでコンマ区切りリストが受け入れられるか、複数指定できます。 CodeQL では、次の言語のデータベースの作成がサポートされています。
言語 | 識別子 |
---|---|
C/C++ | cpp |
C# | csharp |
Go | go |
Java | java |
JavaScript/TypeScript | javascript |
Python | python |
Ruby | ruby |
注: Ruby の CodeQL 分析は、現在ベータ版です。 ベータ版の間、Ruby の分析は他の言語の CodeQL 分析ほど包括的ではありません。
ソース ファイルの場所、コードをコンパイルする必要があるかどうか、複数の言語の CodeQL データベースを作成するかどうかに応じて、追加のオプションを指定できます。
--source-root
: データベースの作成で使用されるプライマリ ソース ファイルのルート フォルダー。 既定では、コマンドで現在のディレクトリがソースのルートであると見なされます。別の場所を指定するには、このオプションを使用します。--db-cluster
: 複数の言語のデータベースを作成する場合に、複数言語のコードベースに対して使用します。--command
: 1 つ以上のコンパイル型言語のデータベースを作成するときに使用します。要求する言語が Python と JavaScript のみである場合は省略します。 これにより、コンパイラを呼び出すために必要なビルド コマンドを指定します。 コマンドは、現在のフォルダーまたは--source-root
(指定されている場合) から実行されます。--command
を含めない場合、CodeQL で組み込みの自動ビルダーを使用した、ビルド システムの自動検出が試みられます。--no-run-unnecessary-builds
:--db-cluster
と一緒に使用して、CodeQL CLI でビルドを監視する必要がない言語 (たとえば Python や JavaScript、TypeScript) のビルド コマンドを抑制します。
エクストラクターのオプションを指定して、CodeQL データベースを作成するエクストラクターの動作をカスタマイズできます。 詳しくは、「エクストラクターのオプション」を参照してください。
データベースを作成するときに使うことができるすべてのオプションについて詳しくは、「database create」をご覧ください。
進行状況と結果
指定したオプションに問題がある場合は、エラーが報告されます。 インタープリター型言語の場合、抽出の進行状況がコンソールに表示されます。ソース ファイルごとに、抽出が成功したか失敗したかが報告されます。 コンパイル型言語の場合、コンソールにはビルド システムの出力が表示されます。
データベースが正常に作成されると、コマンドで指定したパスに新しいディレクトリが見つかります。 --db-cluster
オプションを使用して複数のデータベースを作成した場合は、言語ごとにサブディレクトリが作成されます。 各 CodeQL データベース ディレクトリには、リレーショナル データ (分析に必要) やソース アーカイブ (データベースの作成時に作られたソース ファイルのコピー) などの複数のサブディレクトリが含まれており、分析結果の表示に使用されます。
非コンパイル型言語のデータベースの作成
CodeQL CLI には、非コンパイル型言語 (具体的には JavaScript (および TypeScript)、Python、Ruby) のデータベースを作成するためのエクストラクターが含まれています。 こうしたエクストラクターは、database create
を実行するときに --language
オプションとして JavaScript、Python、または Ruby を指定すると、自動的に呼び出されます。 これらの言語のデータベースを作成するときは、追加の依存関係がすべて使用可能であることを確認する必要があります。
注: JavaScript、TypeScript、Python、Ruby 用に database create
を実行する場合は、--command
オプションを指定しないでください。 そうでないと、通常のエクストラクター呼び出しがオーバーライドされ、空のデータベースが作成されます。 複数の言語のデータベースを作成し、そのうちの 1 つがコンパイル型言語である場合は、--no-run-unnecessary-builds
オプションを使用して、コンパイルする必要のない言語のコマンドをスキップします。
JavaScript および TypeScript
JavaScript のデータベースを作成するために追加の依存関係は必要ありませんが、プロジェクトに TypeScript ファイルが含まれている場合は、Node.js 6.x 以降をインストールする必要があります。 コマンド ラインで --language=javascript
を指定して、JavaScript と TypeScript の両方のファイルを抽出できます。
codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database
ここでは、--source-root
パスを指定しています。これはデータベースの作成が実行される場所ですが、必ずしもコードベースのチェックアウト ルートではありません。
既定では、node_modules
および bower_components
ディレクトリ内のファイルは抽出されません。
Python
Python のデータベースを作成する場合は、次のことを確認する必要があります。
- Python 3 がインストールされていて、CodeQL エクストラクターで使用できること。
- コードで使用している Python のバージョンがインストールされていること。
- pip パッケージ管理システムにアクセスでき、コードベースが依存するすべてのパッケージをインストールできること。
- pip モジュール virtualenv をインストール済みであること。
コマンド ラインで --language=python
を指定する必要があります。 次に例を示します。
codeql database create --language=python <output-folder>/python-database
これにより、コードのチェックアウト ルートから database create
サブコマンドが実行され、<output-folder>/python-database
に新しい Python データベースが生成されます。
Ruby
Ruby のデータベースを作成するには、追加の依存関係は必要ありません。 コマンド ラインで --language=ruby
を指定する必要があります。 次に例を示します。
codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database
ここでは、--source-root
パスを指定しています。これはデータベースの作成が実行される場所ですが、必ずしもコードベースのチェックアウト ルートではありません。
コンパイル型言語のデータベースの作成
コンパイル型言語の場合、CodeQL からデータベースを生成するために必要なビルド システムを呼び出す必要があるため、CLI でビルド メソッドを使用できる必要があります。
ビルド システムの検出
注: 現在、Kotlin の CodeQL 分析はベータ版です。 ベータ版では、Kotlin コードと、付随するドキュメントの分析は、他の言語の場合ほど包括的なものではありません。
CodeQL CLI には、C/C++、C#、Go、Java コードの自動ビルダーが含まれています。 CodeQL の自動ビルダーを使用すると、ビルド コマンドを指定せずにコンパイル型言語のプロジェクトをビルドできます。 自動ビルダーが呼び出されると、CodeQL はソースでビルド システムの証拠を調べ、データベースの抽出に必要な最適なコマンドのセットを実行しようとします。
--command
オプションを含めない場合、コンパイル型の --language
に対して codeql database create
を実行すると、自動ビルダーが自動的に呼び出されます。 たとえば、Java コードベースの場合は、単に次のように実行します。
codeql database create --language=java <output-folder>/java-database
コードベースで標準のビルド システムを使用するのであれば、多くの場合、自動ビルダーを利用することがデータベースを作成する最も簡単な方法です。 標準以外のビルド ステップを必要とするソースについては、コマンド ラインで各ステップを明示的に定義することが必要な場合があります。
注:
-
Go データベースを構築する場合は、Go ツールチェーン (バージョン 1.11 以降) をインストールし、依存関係がある場合は、適切な依存関係マネージャー (dep など) をインストールします。
-
Go の自動ビルダーはリポジトリ内で、Go で記述されたコードの自動検出を試み、依存関係のフェッチを試みる際にのみビルド スクリプトを実行します。 CodeQL で強制的に、抽出をビルド スクリプトによってコンパイルされたファイルに制限するには、環境変数
CODEQL_EXTRACTOR_GO_BUILD_TRACING=on
を設定するか、--command
オプションを使用してビルド コマンドを指定します。
ビルド コマンドの指定
次の例は、コンパイル型言語について指定できるビルド コマンドの一部を示すために設計されています。
注: --command
オプションで受け入れられる引数は 1 つです。複数のコマンドを使用する必要がある場合は、--command
を複数回指定します。 サブコマンドとオプションを渡す必要がある場合は、正しく解釈されるように引数全体を引用符で囲む必要があります。
-
make
を使用してビルドされた C/C++ プロジェクト:codeql database create cpp-database --language=cpp --command=make
-
dotnet build
を使用してビルドされた C# プロジェクト:すべてのコードが確実にビルドされるように
/t:rebuild
を追加するか、事前にdotnet clean
を実行することをお勧めします (ビルドされていないコードは CodeQL データベースに含まれません)。codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
-
CODEQL_EXTRACTOR_GO_BUILD_TRACING=on
環境変数を使用してビルドされた Go プロジェクト:CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go
-
カスタム ビルド スクリプトを使用してビルドされた Go プロジェクト:
codeql database create go-database --language=go --command='./scripts/build.sh'
-
Gradle を使用してビルドされた Java プロジェクト:
# Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL: codeql database create java-database --language=java --command='gradle --no-daemon clean test'
-
Maven を使用してビルドされた Java プロジェクト:
codeql database create java-database --language=java --command='mvn clean install'
-
Ant を使用してビルドされた Java プロジェクト:
codeql database create java-database --language=java --command='ant -f build.xml'
-
Bazel を使用してビルドされたプロジェクト:
# Navigate to the Bazel workspace. # Before building, remove cached objects # and stop all running Bazel server processes. bazel clean --expunge # Build using the following Bazel flags, to help CodeQL detect the build: # `--spawn_strategy=local`: build locally, instead of using a distributed build # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache codeql database create new-database --language=<language> \ --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results //path/to/package:target' # After building, stop all running Bazel server processes. # This ensures future build commands start in a clean Bazel server process # without CodeQL attached. bazel shutdown
-
カスタム ビルド スクリプトを使用してビルドされたプロジェクト:
codeql database create new-database --language=<language> --command='./scripts/build.sh'
このコマンドにより、プロジェクトのビルドに必要なすべてのコマンドを含むカスタム スクリプトを実行します。
間接ビルド トレースの使用
コンパイル型言語の CodeQL CLI 自動ビルダーが CI ワークフローで動作せず、codeql database trace-command
でビルド コマンドの呼び出しをラップできない場合は、間接ビルド トレースを使用して CodeQL データベースを作成できます。 間接ビルド トレースを使用するには、CI システムで各ビルド アクションのカスタム環境変数を設定できる必要があります。
間接ビルド トレースを使用して CodeQL データベースを作成するには、プロジェクトのチェックアウト ルートから次のコマンドを実行します。
codeql database init ... --begin-tracing <database>
ユーザーは次のものを指定する必要があります。
<database>
: 作成する新しいデータベースへのパス。 このコマンドを実行すると、このディレクトリが作成されます。既存のディレクトリを指定することはできません。--begin-tracing
: ビルド コマンドがトレースされる環境を設定するために使用できるスクリプトを作成します。
codeql database init
コマンドの他のオプションを通常どおり指定できます。
注: Windows でビルドを実行する場合は、--trace-process-level <number>
または --trace-process-name <parent process name>
を設定して、分析対象コードのすべてのビルド ステップを監視する親 CI プロセスをオプションで参照する必要があります。
codeql database init
コマンドによりメッセージが出力されます。
Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.
Based on your operating system, we recommend you run: ...
codeql database init
コマンドを使用すると、CodeQL で一連のビルド ステップをトレースできるようにするための環境変数と値が含まれたファイルと共に、<database>/temp/tracingEnvironment
が作成されます。 これらのファイルには start-tracing.{json,sh,bat,ps1}
のように名前が付けられます。 これらのファイルの 1 つを CI システムのメカニズムと共に使用して、今後の手順のための環境変数を設定します。 次のようにすることができます。
- JSON ファイルを読み取り、処理し、CI システムによって想定されている形式で環境変数を出力します。 たとえば、Azure DevOps では
echo "##vso[task.setvariable variable=NAME]VALUE"
が想定されています。 - または、CI システムで環境を永続化する場合は、適切な
start-tracing
スクリプトをソースとして、CI システムのシェル環境に CodeQL 変数を設定します。
コードをビルドします。必要に応じて、start-tracing
スクリプトが保存されているディレクトリにある end-tracing.{json,sh,bat,ps1}
スクリプトを使用して環境変数の設定を解除してから、codeql database finalize <database>
コマンドを実行します。
間接ビルド トレースを使用して CodeQL データベースを作成したら、それを他の CodeQL データベースと同様に操作できます。 たとえば、データベースを分析し、コード スキャンを使用する場合は GitHub に結果をアップロードします。
間接ビルド トレースを使用して CodeQL データベースを作成する例
注: Azure DevOps パイプラインを使用する場合、CodeQL データベースを作成する最も簡単な方法は、GitHub Advanced Security for Azure DevOps を使用することです。 ドキュメントについては、Microsoft Learn で「GitHub Advanced Security for Azure DevOps を構成する」を参照してください。
次の例は、Azure DevOps パイプラインでの間接ビルド トレースを使用して CodeQL データベースを作成する方法を示しています。
steps:
# Download the CodeQL CLI and query packs...
# Check out the repository ...
# Run any pre-build tasks, for example, restore NuGet dependencies...
# Initialize the CodeQL database.
# In this example, the CodeQL CLI has been downloaded and placed on the PATH.
- task: CmdLine@1
displayName: Initialize CodeQL database
inputs:
# Assumes the source code is checked out to the current working directory.
# Creates a database at `<current working directory>/db`.
# Running on Windows, so specifies a trace process level.
script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"
# Read the generated environment variables and values,
# and set them so they are available for subsequent commands
# in the build pipeline. This is done in PowerShell in this example.
- task: PowerShell@1
displayName: Set CodeQL environment variables
inputs:
targetType: inline
script: >
$json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
$json.PSObject.Properties | ForEach-Object {
$template = "##vso[task.setvariable variable="
$template += $_.Name
$template += "]"
$template += $_.Value
echo "$template"
}
# Execute the pre-defined build step. Note the `msbuildArgs` variable.
- task: VSBuild@1
inputs:
solution: '**/*.sln'
msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
platform: Any CPU
configuration: Release
# Execute a clean build, in order to remove any existing build artifacts prior to the build.
clean: True
displayName: Visual Studio Build
# Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
- task: PowerShell@1
displayName: Clear CodeQL environment variables
inputs:
targetType: inline
script: >
$json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
$json.PSObject.Properties | ForEach-Object {
$template = "##vso[task.setvariable variable="
$template += $_.Name
$template += "]"
$template += $_.Value
echo "$template"
}
- task: CmdLine@2
displayName: Finalize CodeQL database
inputs:
script: 'codeql database finalize db'
# Other tasks go here, for example:
# `codeql database analyze`
# then `codeql github upload-results` ...
GitHub.comからのデータベースのダウンロード
GitHub では、REST API を使用してダウンロードできる 200,000 を超えるリポジトリの CodeQL データベースを GitHub.com に保存しています。 リポジトリの一覧は、セキュリティ調査のための最も興味深いコードベースが確実に含まれるように、絶えず増加し、進化しています。
/repos/<owner>/<repo>/code-scanning/codeql/databases
エンドポイントを使用して、リポジトリにダウンロード可能な CodeQL データベースがあるかどうかを確認できます。 たとえば、GitHub CLI を使用して CodeQL データベースの有無を確認するには、次のように実行します。
gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/
このコマンドからは、リポジトリで使用できる CodeQL データベースに関する情報が返されます。データベースが表す言語や、データベースが最後に更新された日時などです。 使用できる CodeQL データベースがない場合、応答は空です。
目的の言語の CodeQL データベースが存在することを確認したら、次のコマンドを使用してダウンロードできます。
gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip
詳しくは、「CodeQL データベース エンドポイントの取得」のドキュメントを参照してください。
CodeQL CLI を使用して分析を実行する前に、データベースを解凍する必要があります。