CIシステムでのCodeQL CLIの設定

CodeQL CLIでのCode scanningの結果の生成について

CIシステム内のサーバーでCodeQL CLIを利用できるようにして、確実にGitHubで認証できるようにしたなら、データを生成する準備ができています。

結果を生成してGitHubにアップロードするには、3つの異なるコマンドを使います。

1. database create では、リポジトリのサポートされている各プログラミング言語の階層構造を表すために CodeQL データベースを作成します。
2. database analyze では、クエリを実行して各 CodeQL データベースを分析し、結果を SARIF ファイルにまとめます。
3. github upload-results では、結果の SARIF ファイルを GitHub にアップロードします。そこで結果はブランチまたは pull request と照合され、code scanning アラートとして表示されます。

--help オプションを使用して、任意のコマンドのコマンドライン ヘルプを表示できます。

分析するCodeQLデータベースの作成

1. 分析するコードをチェックアウトします。

   • ブランチの場合は、分析するブランチのヘッドをチェックアウトします。
   • pull request の場合は、pull request のヘッド コミットをチェックアウトするか、GitHub で生成された pull request のマージ コミットをチェックアウトします。

2. コードベースの環境を設定し、依存関係が使用可能であることを確認します。 詳しくは、"CodeQL 分析のためのコードの準備" の「コンパイルされていない言語のデータベースの作成」と「コンパイル済み言語のデータベースの作成」をご覧ください。

3. コードベースのビルド コマンドを見つけます (ある場合)。 通常、これは CI システムの構成ファイルで使用できます。

4. リポジトリのチェックアウト ルートから codeql database create を実行し、コードベースをビルドします。

   # Single supported language - create one CodeQL database
   codeql database create <database> --command <build> \
         --language=<language-identifier>
   
   # Multiple supported languages - create one CodeQL database per language
   codeql database create <database> --command <build> \
         --db-cluster --language=<language-identifier>,<language-identifier>
   

   注: コンテナー化されたビルドを使用する場合は、ビルド タスクが行われるコンテナーで CodeQL CLI を実行する必要があります。

詳しくは、「CodeQL 分析のためのコードの準備」を参照してください。

単一言語の例

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

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --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.

複数言語の例

この例では、/checkouts/example-repo-multi でチェックアウトされたリポジトリの CodeQL データベースを 2 つ作成します。 イベント プロセッサで使用されるものは次のとおりです。

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

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

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,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] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

CodeQLデータベースの分析

1. CodeQLデータベースを作成してください（上記参照）。

2. データベースに対して codeql database analyze を実行し、使用するパックまたはクエリを指定します。

   codeql database analyze <database> --format=<format> \
       --output=<output>  --download <packs,queries>
   

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

詳しくは、「CodeQL クエリによるコード分析」を参照してください。

CodeQL データベースの分析の基本的な例

この例では、/codeql-dbs/example-repo で格納されている CodeQL データベースを分析し、結果を SARIF ファイル (/temp/example-repo-js.sarif) として保存します。 --sarif-category を使用して、結果を JavaScript として識別する追加の情報を SARIF ファイルに含めます。 これは、リポジトリ中の単一のコミットに対して分析するCodeQLデータベースが複数ある場合に不可欠です。

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

監視のために結果にファイル カバレッジ情報を追加する

必要に応じて、GitHub にファイル カバレッジ情報を送信して、code scanning のツールの状態ページに表示できます。 ファイル カバレッジ情報の詳細については、「コード スキャンのツール状態ページについて」を参照してください。

code scanning の結果にファイル カバレッジ情報を含めるには、CI システムの codeql database analyze の呼び出しに --sarif-add-baseline-file-info フラグを追加します。次に例を示します。

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

GitHubへの結果のアップロード

SARIF プロパティがアップロードでサポートされているサイズであり、ファイルがコード スキャンと互換性があることを確認できます。 詳しくは、「Code scanningの SARIF サポート」をご覧ください。

結果を GitHub にアップロードする前に、以前に作成した GitHub Appまたは personal access token を CodeQL CLI に渡す最善の方法を決める必要があります (「CI システムでの CodeQL CLI のインストール」を参照)。 シークレット ストアの安全な使用に関する CI システムのガイダンスを確認することをお勧めします。 CodeQL CLIは以下をサポートします。

• シークレット ストアとインターフェイスに --github-auth-stdin オプションを使います (推奨)。
• 環境変数 GITHUB_TOKEN にシークレットを保存し、--github-auth-stdin オプションを含めずに CLI を実行する。
• テスト目的であれば、--github-auth-stdin コマンドライン オプションを渡し、標準入力経由で一時トークンを指定することができます。

CI サーバーの最も安全で信頼性の高い方法を決定した場合は、各 SARIF 結果ファイルで codeql github upload-results を実行し、トークンが環境変数 GITHUB_TOKEN で使用可能でない限り、--github-auth-stdin を含めます。

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> 

詳しくは、「github upload-results」を参照してください。

GitHub への結果のアップロードの基本的な例

次の例では、SARIF ファイル temp/example-repo-js.sarif からリポジトリ my-org/example-repo に結果をアップロードします。 結果が main ブランチのコミット deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 に対するものであることを code scanning API に伝えます。 この例は、GitHub の REST API での認証用に作成された GitHub App または personal access token で GITHUB_TOKEN 環境変数を使っていることを前提としています。

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

アップロードが失敗しなければ、このコマンドからの出力はありません。 コマンドプロンプトは、アップロードが完了してデータ処理が開始された時点で戻ってきます。 小さなコードベースでは、すぐ後にGitHub中のcode scanningアラートを調べることができるでしょう。 チェックアウトしたコードに基づき、pull request 中で直接あるいはブランチの [セキュリティ] タブでアラートを見ることができます。詳細については「Pull RequestでCode scanningアラートをトリアージする」と「リポジトリのコード スキャンのアラートを管理する」を参照してください。

分析が失敗した場合の GitHub への診断情報のアップロード

CodeQL CLI でデータベースの分析が正常に完了すると、ファイル カバレッジ、警告、エラーなどの診断情報が収集され、それを結果とともに SARIF ファイルに含めます。 SARIF ファイルを GitHub にアップロードすると、そのリポジトリの code scanning ツールの状態ページに診断情報が表示され、CodeQL がどの程度正常に動作しているかを簡単に確認し、あらゆる問題をデバッグできます。 詳しくは、「コード スキャンのツール状態ページについて」を参照してください。

ただし、codeql database analyze が何らかの理由で失敗した場合は、GitHub にアップロードする SARIF ファイルがなく、そのリポジトリの code scanning ツールの状態ページに表示する診断情報がありません。 これにより、ユーザーが CI システム内のログ ファイルにアクセスできない限り、分析のトラブルシューティングが困難になります。

分析が失敗したときに、診断情報をエクスポートして GitHub にアップロードするように CI ワークフローを構成することをお勧めします。 これは、次の簡単なコマンドを使用して診断情報をエクスポートし、GitHub にアップロードすることで行うことができます。

分析が失敗した場合の診断情報のエクスポート

"database export-diagnostics" を使用して、失敗した分析用の SARIF ファイルを作成できます。次に例を示します。

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

この SARIF ファイルには、分析中に生成されたファイル カバレッジ情報、警告、エラーなど、失敗した分析の診断情報が含まれます。

分析が失敗した場合の診断情報のアップロード

"github upload-results" を使用して SARIF ファイルを GitHub にアップロードすることで、ツールの状態ページでこの診断情報を確認できます。次に例を示します。

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

これは、成功した分析から SARIF ファイルをアップロードするプロセスと同じです。

CodeQL クエリ パックのダウンロードと使用

CodeQL CLI バンドルには、GitHub の専門家、セキュリティ研究者、コミュニティの共同作成者によって管理されるクエリが含まれます。 他の Organization によって開発されたクエリを実行する場合、CodeQL クエリ パックを使用すると、クエリを効率的かつ信頼性の高い方法でダウンロードして実行できます。 詳しくは、「About code scanning with CodeQL」を参照してください。

CodeQL パックを使ってデータベースを分析する前に、GitHub Container registry から必要なパッケージをすべてダウンロードする必要があります。 これは、codeql database analyze コマンドの一部として --download フラグを使うことによって行うことができます。 パッケージが一般公開されていない場合は、認証に GitHub App または personal access token を使う必要があります。 詳細と例については、上記の「GitHub への結果のアップロード」を参照してください。

クエリ パックのダウンロードと使用の基本的な例

この例では、codeql database analyze コマンドに --download オプションを付けて実行しています。

1. 最新バージョンの octo-org/security-queries パックをダウンロードします。
2. バージョン 1.0.1 とocto-org/optional-security-queries互換性のある_バージョンの_パックをダウンロードします (この場合はバージョン 1.0.2 です)。 semver の互換性については、npm のセマンティック バージョンの範囲に関するドキュメントを参照してください。
3. octo-org/security-queries の既定のクエリをすべて実行します。
4. octo-org/optional-security-queries のクエリ queries/csrf.ql だけを実行します

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

CodeQL パックの直接ダウンロード

CodeQL パックをダウンロードしてすぐに実行しない場合、codeql pack download コマンドを使用できます。 これは、CodeQL クエリを実行するとき、インターネットへのアクセスをしないようにする場合、便利です。 CodeQL 分析を実行するとき、前の例と同じ方法でパック、バージョン、パスを指定できます。

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

複数の GitHub コンテナー レジストリから CodeQL パックをダウンロードする

CodeQL パックが複数のコンテナー レジストリに存在する場合は、各パックを検索する場所を CodeQL CLI に示す必要があります。 詳しくは、「をカスタマイズして、コード スキャンの詳細設定を行う」を参照してください。

CodeQL分析のためのCIの設定例

これは、2つのサポートされている言語を持つコードベースを分析し、結果をGitHubにアップロードするために使うことができる一連のコマンドの例です。

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

CIシステムでのCodeQL CLIのトラブルシューティング

ログと診断情報を見る

code scanningクエリスイートを使ってCodeQLデータベースを分析する際には、アラートに関する詳細情報を生成するのに加えて、CLIはデータベース生成ステップからの診断情報とサマリメトリクスを報告します。 アラートが少ないリポジトリでは、実際にコード中の問題が少ないのか、あるいはCodeQLデータベースの生成時にエラーがあったのかを判断するのにこの情報が役立つかもしれません。 codeql database analyze からさらに詳しい出力を得るには、--verbose オプションを使用します。

利用可能な診断情報の種類について詳しくは、「Code scanningログの表示」を参照してください。

Code scanning は、分析された言語の 1 つからの分析結果だけを表示します。

デフォルトでは、code scanningはリポジトリの分析ごとに1つのSARIF結果ファイルを期待します。 したがって、コミットから2つめのSARIF結果ファイルをアップロードすると、それはデータのオリジナルのセットの置き換えとして扱われます。

リポジトリ中の1つのコミットについての結果をcode scanning APIに複数アップロードしたい場合は、それぞれの結果をユニークなセットとして特定しなければなりません。 コミットごとに分析する CodeQL データセットを複数作成するリポジトリでは、--sarif-category オプションを使用して、そのリポジトリで生成するそれぞれの SARIF ファイルに言語または他の一意のカテゴリを指定します。

Python の抽出に関する問題

CodeQL CLI に対する Python 2 のサポートは非推奨になっています (具体的には、CodeQL データベース生成フェーズ (コード抽出))。

Python で記述されたコードで CodeQL CLI を使って CodeQL code scanning を実行する場合は、CI システムに Python 3 がインストールされていることを確認する必要があります。

参考資料

• 「CodeQL 分析のためのコードの準備」
• CodeQL クエリによるコード分析
• CodeQL パックを発行して使用する