CodeQL データベースの作成

CodeQL データベースの作成について

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

ソース ファイルの場所、コードをコンパイルする必要があるかどうか、複数の言語の 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

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 でビルド メソッドを使用できる必要があります。

ビルド システムの検出

CodeQL CLI には、C/C++、C#、Go、Java コードの自動ビルダーが含まれています。 CodeQL の自動ビルダーを使用すると、ビルド コマンドを指定せずにコンパイル型言語のプロジェクトをビルドできます。 自動ビルダーが呼び出されると、CodeQL はソースでビルド システムの証拠を調べ、データベースの抽出に必要な最適なコマンドのセットを実行しようとします。

--command オプションを含めない場合、コンパイル型の --language に対して codeql database create を実行すると、自動ビルダーが自動的に呼び出されます。 たとえば、Java コードベースの場合は、単に次のように実行します。

codeql database create --language=java <output-folder>/java-database

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

ビルド コマンドの指定

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

• 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 コマンドの他のオプションを通常どおり指定できます。

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 データベースを作成する方法を示しています。

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 を使用して分析を実行する前に、データベースを解凍する必要があります。

参考資料

• 「VS Code の CodeQL でのプロジェクトの分析」