CodeQL 分析用コードを準備する

分析用コードの準備について

CodeQLを使用してコードを分析する前に、コードに対してクエリを実行するために必要なすべてのデータを含むCodeQL データベースを作成する必要があります。 CodeQLを使用して、CodeQL CLIデータベースを自分で作成できます。

CodeQL 分析は、コードからリレーショナルデータを抽出し、それを使用して CodeQL データベースを構築することに依存します。 CodeQL データベースには、コードベースに関するすべての重要な情報が含まれています。コードベースに対して CodeQL クエリを実行することで分析できます。

CodeQL データベースを生成する前に、次の作業を行う必要があります。

CodeQL CLIをインストールして設定します。詳細については、「CodeQL CLI を設定する」を参照してください。
分析するコードをチェックアウトします。
- ブランチの場合は、分析するブランチのヘッドをチェックアウトします。
- プルリクエストの場合は、プルリクエストのヘッドコミット、または GitHub によって生成されたプルリクエストのマージコミットをチェックアウトします。
コードベースの環境を設定し、依存関係が使用可能であることを確認します。
コンパイル型言語で最適な結果を得るには、コードベースのビ–ルドコマンドを見つけます (存在する場合)。通常、これは CI システムの構成ファイルで使用できます。

コードベースの準備ができたら、codeql database create を実行してデータベースを作成できます。詳細については、「非コンパイル型言語のデータベースを作成する」および「コンパイル型言語のデータベースを作成する」を参照してください。

Language	識別子	オプションの代替識別子 (存在する場合)
C/C++	`c-cpp`
`c` または `cpp`
C#	`csharp`
GitHub Actions ワークフロー	`actions`
Go	`go`
Java/Kotlin	`java-kotlin`
`java` または `kotlin`
JavaScript/TypeScript	`javascript-typescript`
`javascript` または `typescript`
Python	`python`
Ruby	`ruby`
Rust	`rust`
Swift	`swift`

代替識別子の 1 つを指定した場合、これは標準の言語識別子の使用と同じです。たとえば、javascript の代わりに javascript-typescript を指定した場合、TypeScript コードの分析は除外されません。代わりに、--codescanning-config CLI オプションを使って、paths-ignore 構成キーで除外対象のファイルを指定する構成ファイルを読み込むことができます。「コードスキャンのワークフロー構成オプション」を参照してください。

または、それをサポートする言語の場合は、スキャン対象のファイルのみをビルドするカスタムビルドコマンドを使います。「コンパイル型言語のデータベースの作成」を参照してください。

コードベースにビルドプロセスを呼び出すビルドコマンドまたはスクリプトがある場合は、次のように指定することをお勧めします。

   codeql database create  --command  \
         --language=

データベースを作成するためのオプション

ソースファイルの場所、コードをコンパイルする必要がある場合、および複数の言語用に CodeQL データベースを作成する場合に応じて、追加のオプションを指定できます。

Option	Required	使用方法

CodeQL データベース用に作成するディレクトリの名前と場所を指定します。既存のディレクトリを上書きしようとすると、コマンドは失敗します。また `--db-cluster` を指定した場合は、これが親ディレクトリであり、分析される言語ごとにサブディレクトリが作成されます。
`--language`		データベースを作成する言語の識別子 ( `c-cpp`、 `csharp`、 `go`、 `java-kotlin`、 `javascript-typescript`、 `python`、 `ruby`、 `rust` および `swift`のいずれか) を指定します。



--db-cluster

と一緒に使用する場合は、このオプションは、カンマ区切りのリストを許可するか、複数回指定できます。 | | --command | | **推奨。** コードベースのビルドプロセスを呼び出すビルドコマンドまたはスクリプトを指定するために使用します。コマンドは、現在のフォルダーまたは、定義されている場合は、--source-root で実行できます。 Pythonおよび JavaScript/TypeScript の分析には必要ありません。 | | --build-mode | | **推奨。** C/C++、C#, Java および Rust を指定しない場合は、`--command` を使用して、ビルドなしで CodeQL データベースを作成する (`none`) か、ビルドコマンドの自動検出を試みる (`autobuild`) かを指定します。既定では、自動ビルド検出が使用されます。ビルドモードの比較については、[「CodeQL ビルドモード」](/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-for-compiled-languages#compare-build-modes)を参照してください。 | | --db-cluster | |



--language

によって指定された言語ごとに 1 つのデータベースを生成するには、複数言語コードベースを使用します。 | | --no-run-unnecessary-builds | | **推奨。** CodeQL CLIがビルドを監視する必要がない言語 (Pythonや JavaScript/TypeScript など) のビルドコマンドを抑制するために使用します。 | | --source-root | | リポジトリのチェックアウトルートの外部で CLI を実行する場合に使用します。既定では、`database create` コマンドで現在のディレクトリがソースファイルのルートディレクトリであると見なされます。別の場所を指定するためにこのオプションを使用します。 | | --codescanning-config | | Advanced. CodeQL データベースの作成方法と、後の手順で実行するクエリを指定する構成ファイルがある場合に使用します。詳細については、「[AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files)」および「[AUTOTITLE](/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-create#--codescanning-configfile)」を参照してください。 |

抽出オプションを指定して、 CodeQL データベースを作成するエクストラクターの動作をカスタマイズできます。詳細については、「エクストラクターのオプション」を参照してください。

データベースの作成時に使用できるすべてのオプションの詳細については、「AUTOTITLE」を参照してください。

単一言語の例

この例では、CodeQLでチェックアウトされたリポジトリ用の単一の/checkouts/example-repo データベースを作成します。 JavaScript 抽出機能を使用して、リポジトリに JavaScript および TypeScript コードの階層表現を作成します。結果のデータベースは /codeql-dbs/example-repo に格納されます。

$ codeql database create /codeql-dbs/example-repo --language=javascript-typescript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

複数言語の例

この例では、CodeQLでチェックアウトされたリポジトリ用の 2 つの/checkouts/example-repo-multi データベースを作成します。以下を使用します。

--db-cluster: 複数の言語の分析を要求します。
--language: データベースを作成する言語を指定します。
--command: コードベースのビルドコマンド (ここでは make) をツールに伝えます。
--no-run-unnecessary-buildsは、必要のない言語 (Python など) のビルドコマンドをスキップするようにツールに指示します。

結果のデータベースは、python の cpp および /codeql-dbs/example-repo-multi サブディレクトリに格納されます。

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,c-cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] 
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

進行状況と結果

指定したオプションに問題がある場合は、エラーが報告されます。解釈された言語の場合、および--build-mode noneにC/C++、C#, Java および Rustを指定すると、抽出の進行状況がコンソールに表示されます。ソースファイルごとに、抽出の成功または失敗がコンソールに表示されます。コンパイル型言語がビルドされると、コンソールには、ビルドシステムの出力が表示されます。

データベースが正常に作成されると、コマンドで指定したパスに新しいディレクトリが見つかります。 --db-cluster オプションを使用して複数のデータベースを作成した場合は、言語ごとにサブディレクトリが作成されます。各 CodeQL データベースディレクトリには、リレーショナルデータ (分析に必要) やソースアーカイブ (データベースの作成時に作成されたソースファイルのコピー) など、多数のサブディレクトリが含まれています。これは、分析結果の表示に使用されます。

非コンパイル型言語のデータベースの作成

CodeQL CLIには、コンパイルされていない言語 (具体的には JavaScript (および TypeScript)、Python、Ruby) 用のデータベースを作成するエクストラクターが含まれています。これらのエクストラクターは、javaScript、Python、または Ruby を --language オプションとして指定すると、database create の実行時に自動的に呼び出されます。これらの言語のデータベースを作成するときは、追加の依存関係がすべて使用可能であることを確認する必要があります。

メモ

JavaScript、TypeScript、Python、Ruby database create を実行する場合は、--command オプションを指定しないでください。そうでないと、通常のエクストラクター呼び出しがオーバーライドされ、空のデータベースが作成されます。複数の言語のデータベースを作成し、そのうちの 1 つがコンパイル型言語である場合は、--no-run-unnecessary-builds オプションを使用して、コンパイルする必要のない言語のコマンドをスキップします。

JavaScript と TypeScript

JavaScript のデータベースを作成するために、追加の依存関係は必要ありませんが、プロジェクトに TypeScript ファイルが含まれている場合は、Node.js 14 以降をインストールして、PATH としての node で使用できるようにする必要があります。コマンドラインで --language=javascript-typescript を指定して、JavaScript と TypeScript の両方のファイルを抽出できます。

codeql database create --language=javascript-typescript --source-root  /javascript-database

ここでは、--source-root パスを指定しています。これはデータベースの作成が実行される場所ですが、必ずしもコードベースのチェックアウトルートではありません。

既定では、node_modules および bower_components ディレクトリ内のファイルは抽出されません。

Python

Python用のデータベースを作成するときは、次のことを確認する必要があります。

Python 3 がインストールされており、CodeQL エクストラクターで使用できます。
コードによって使用されるPythonのバージョンがインストールされている。

コマンドラインで --language=python を指定する必要があります。例えば次が挙げられます。

codeql database create --language=python /python-database

これにより、コードのチェックアウトルートから database create サブコマンドが実行され、/python-database に新しいPython データベースが生成されます。

Ruby

Ruby のデータベースを作成するには、追加の依存関係は必要ありません。コマンドラインで --language=ruby を指定する必要があります。例えば次が挙げられます。

codeql database create --language=ruby --source-root  /ruby-database

コンパイル型言語のデータベースの作成

ほとんどのコンパイル済み言語では、 CodeQL 必要なビルドシステムを呼び出してデータベースを生成する必要があるため、CLI でビルドメソッドを使用できる必要があります。この方法では、生成されたコードを含むデータベースが作成されます。 CodeQL には、コードベースを構築するための 2 つのメソッドがあります。

さらに、 C/C++、C#, Java および Rustでは、コードをビルドせずにデータベースを生成するオプションがあります。これは、多数のリポジトリに対して code scanning を有効にする場合に特に便利です。詳細については、「CodeQL ビルドモード」を参照してください。

ビルドシステムを自動検出する

CodeQL CLIには、C/C++、C#、Go、Java、Kotlin、Swift コード用のオートビルダーが含まれています。 CodeQL autobuilder を使用すると、ビルドコマンドを指定せずにコンパイル済み言語のプロジェクトをビルドできます。自動ビルダーが呼び出されると、 CodeQL はソースでビルドシステムの証拠を調べ、データベースの抽出に必要な最適なコマンドセットの実行を試みます。詳細については、「コンパイル済み言語の CodeQL コードスキャン」を参照してください。

自動ビルダーは、codeql database create オプションを含めず --command を設定しない場合に、コンパイル型言語に対して --build-mode none を実行した際に、自動で呼び出されます。たとえば、Swift コードベースの場合は、単に次のように実行します。

codeql database create --language=swift /swift-database

コードベースで標準のビルドシステムを使用するのであれば、多くの場合、自動ビルダーを利用することがデータベースを作成する最も簡単な方法です。標準以外のビルドステップを必要とするソースについては、コマンドラインで各ステップを明示的に定義することが必要な場合があります。

メモ

Go データベースを構築する場合は、Go ツールチェーン (バージョン 1.11 以降) をインストールし、依存関係がある場合は、適切な依存関係マネージャー (dep など) をインストールします。
Go の自動ビルダーはリポジトリ内で、Go で記述されたコードの自動検出を試み、依存関係のフェッチを試みる際にのみビルドスクリプトを実行します。 CodeQLで、ビルドスクリプトによってコンパイルされたファイルへの抽出を制限するには、環境変数をCODEQL_EXTRACTOR_GO_BUILD_TRACING=on設定するか、--command オプションを使用してビルドコマンドを指定します。

ビルドコマンドの指定

次の例は、コンパイル型言語について指定できるビルドコマンドの一部を示すために設計されています。

メモ

--command オプションで受け入れられる引数は 1 つです。複数のコマンドを使用する必要がある場合は、--command を複数回指定します。サブコマンドとオプションを渡す必要がある場合は、正しく解釈されるように引数全体を引用符で囲む必要があります。

make を使用してビルドされた C/C++ プロジェクト:

# Disable parallel execution via `-j1` or other techniques: https://www.gnu.org/software/make/manual/make.html#Parallel-Execution
codeql database create cpp-database --language=c-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.
# To ensure isolated builds without caching, add `--no-build-cache` on persistent machines.
codeql database create java-database --language=java-kotlin --command='gradle --no-daemon clean test'

Maven を使用してビルドされたプロジェクトJava:

codeql database create java-database --language=java-kotlin --command='mvn clean install'

Ant を使用してビルドされたプロジェクトJava:

codeql database create java-database --language=java-kotlin --command='ant -f build.xml'

Cargo を使用して構築された Rust プロジェクト:
```
codeql database create rust-database --language=rust
```
Xcode プロジェクトまたはワークスペースからビルドされた Swift プロジェクト。既定では、最大の Swift ターゲットがビルドされます。

プロジェクトがクリーン状態であり、使用できるビルドアーティファクトがないことを確認することをお勧めします。
```
xcodebuild clean -all
codeql database create -l swift swift-database
```
swift build を使用してビルドされた Swift プロジェクト:
```
codeql database create -l swift -c "swift build" swift-database
```

xcodebuild を使用してビルドされた Swift プロジェクト:

# Build using the following xcodebuild flags:
# `CODE_SIGNING_REQUIRED=NO` and `CODE_SIGNING_ALLOWED=NO`: turn off code signing, which may fail with CodeQL
# `COMPILATION_CACHE_ENABLE_CACHING=NO` and `SWIFT_ENABLE_COMPILE_CACHE=NO`: turn off build caching, which may skip compilation steps
# `SWIFT_USE_INTEGRATED_DRIVER=NO`: turn off the Swift integrated driver, which is incompatible with CodeQL
codeql database create -l swift \
-c "xcodebuild build -target your-target
  CODE_SIGNING_REQUIRED=NO
  CODE_SIGNING_ALLOWED=NO
  COMPILATION_CACHE_ENABLE_CACHING=NO
  SWIFT_ENABLE_COMPILE_CACHE=NO
  SWIFT_USE_INTEGRATED_DRIVER=NO" \
swift-database

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

カスタムビルドスクリプトを使用してビルドされた Swift プロジェクト:
```
codeql database create -l swift -c "./scripts/build.sh" swift-database
```

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
# `--disk_cache=`: avoid using a disk cache. Note that a disk cache is no longer considered a remote cache as of Bazel 6.
codeql database create new-database --language= \
--command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results --disk_cache= //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

メモ

Go 用の Bazel ビルドは現在サポートされていません。

カスタムビルドスクリプトを使用してビルドされたプロジェクト:
```
codeql database create new-database --language= --command='./scripts/build.sh'
```

このコマンドにより、プロジェクトのビルドに必要なすべてのコマンドを含むカスタムスクリプトを実行します。

間接ビルドトレースの使用

コンパイル済み言語の CodeQL CLI オートビルダーが CI ワークフローで動作せず、ビルドコマンドの呼び出しを codeql database trace-commandでラップできない場合は、間接ビルドトレースを使用して CodeQL データベースを作成できます。間接ビルドトレースを使用するには、CI システムで各ビルドアクションのカスタム環境変数を設定できる必要があります。

間接ビルドトレースを使用して CodeQL データベースを作成するには、プロジェクトのチェックアウトルートから次のコマンドを実行します。

codeql database init ... --begin-tracing

ユーザーは次のものを指定する必要があります。

: 作成する新しいデータベースへのパス。このコマンドを実行すると、このディレクトリが作成されます。既存のディレクトリを指定することはできません。
--begin-tracing: ビルドコマンドがトレースされる環境を設定するために使用できるスクリプトを作成します。

codeql database init コマンドの他のオプションを通常どおり指定できます。

メモ

ビルドがWindowsで実行される場合は、--trace-process-level または --trace-process-name を設定して、分析対象のコードのすべてのビルドステップを監視する親 CI プロセスを指定する必要があります。

codeql database init コマンドによりメッセージが出力されます。

Created skeleton . 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 /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 コマンドは、環境変数と値を含むファイルを含む/temp/tracingEnvironmentを作成し、CodeQLが一連のビルドステップをトレースできるようにします。これらのファイルには start-tracing.{json,sh,bat,ps1} のように名前が付けられます。これらのファイルの 1 つを CI システムのメカニズムと共に使用して、今後の手順のための環境変数を設定します。次のようにすることができます。

JSON ファイルを読み取り、処理し、CI システムによって想定されている形式で環境変数を出力します。たとえば、Azure DevOpsは echo "##vso[task.setvariable variable=NAME]VALUE" を想定しています。
または、CI システムが環境を永続化する場合は、適切な start-tracing スクリプトをソースにして、CI システムのシェル環境で CodeQL 変数を設定します。

コードをビルドします。必要に応じて、end-tracing.{json,sh,bat,ps1} スクリプトが保存されているディレクトリにある start-tracing スクリプトを使用して環境変数の設定を解除してから、codeql database finalize コマンドを実行します。

間接ビルドトレースを使用して CodeQL データベースを作成したら、他の CodeQL データベースと同様に操作できます。たとえば、データベースを分析し、コードスキャンを使用する場合は結果を GitHub にアップロードします。

間接ビルドトレースを使用して CodeQL データベースを作成する例

メモ

Azure DevOpsパイプラインを使用する場合、CodeQL データベースを作成する最も簡単な方法は、GitHub Advanced Security for Azure DevOps を使用することです。ドキュメントについては、Microsoft Learn の Configure 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 `/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` ...

次のステップ

CodeQL CLIを使用してコードから作成したデータベースを分析する方法については、CodeQL クエリによるコード分析を参照してください。

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

この記事で