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 データベースの作成」および「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 CLI でのデータベースの分析」を参照してください。

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への結果のアップロード

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

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

• --github-auth-stdin オプションを使用し、標準入力を介して CLI にトークンを渡す (推奨)。
• 環境変数 GITHUB_TOKEN にシークレットを保存し、--github-auth-stdin オプションを含めずに CLI を実行する。

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

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin

詳細については、CodeQL CLI のドキュメントの「github upload-results」を参照してください。

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

この例では、SARIF ファイル temp/example-repo-js.sarif からリポジトリ my-org/example-repo に結果をアップロードします。 結果が main ブランチのコミット deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 に対するものであることを code scanning API に伝えます。

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

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

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

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

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'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

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

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

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

ログと診断情報を見る

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

利用可能な診断情報の種類について詳しくは、「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 CLI でのデータベースの分析
• CodeQL パックを発行して使用する