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

継続的インテグレーションシステムをCodeQL CLIを実行するように設定し、CodeQL分析を行い、code scanningアラートとして表示させるために結果をGitHubにアップロードできます。

Code scanningは、Organizationが所有するGitHub Advanced Securityが有効化されたすべてのパブリック及びプライベートリポジトリで利用できます。 詳しい情報については、「GitHub Advanced Security について」を参照してください。

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

ノート: GitHubでcode scanningの結果として表示するためにSARIFデータをアップロードすることは、GitHub Advanced Securityが有効化されたOrganizationが所有するリポジトリとGitHub.com上のパブリックリポジトリでサポートされています。 詳しい情報については「リポジトリのセキュリティ及び分析の設定の管理」を参照してください。

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

  1. 分析したいコードをチェックアウトしてください:

    • ブランチの場合は、分析したいブランチのheadをチェックアウトしてください。
    • Pull Requestの場合は、Pull Requestのheadコミットをチェックアウトするか、GitHubが生成したPull Requestのマージコミットをチェックアウトしてください。
  2. コードベースの環境をセットアップし、すべての依存関係が利用できるようにしてください。 詳しい情報については、CodeQL CLIのドキュメンテーション中の非コンパイル言語のデータベースの作成及びコンパイル言語のデータベースの作成を参照してください。

  3. コードベースのビルドコマンドがあれば、それを見つけてください。 通常これはCIシステムの設定ファイルにあります。

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

    # 単一のサポートされている言語 - 1つのCodeQLデータベースを作成
    codeql database create <database> --command<build> --language=<language-identifier> 
    
    # 複数のサポートされている言語 - 言語ごとにCodeQLデータベースを作成
    codeql database create <database> --command<build> \
          --db-cluster --language=<language-identifier>,<language-identifier> 

    ノート: コンテナ化されたビルドを使っているなら、ビルドのタスクが行われるコンテナ中でCodeQL CLIを実行しなければなりません。

Option 必須 使い方
<database> CodeQLデータベースを作成するディレクトリの名前と場所を指定します。 既存のディレクトリを上書きしようとすると、コマンドは失敗します。 --db-clusterも指定した場合、これは親ディレクトリになり、分析する言語ごとにサブディレクトリが作られます。
`--language` データベースを作成する言語の識別子を指定します。`cpp`、`csharp`、`go`、`java`、`javascript`、`python`のいずれかです(TypeScriptのコードを分析するときはjavascriptを使ってください)。
`--db-cluster`とともに使われると、このオプションはカンマ区切りのリストを取るか、複数回指定できます。
`--command` 推奨されます。 コードベースのビルドプロセスを呼び出すビルドコマンドもしくはスクリプトを指定するために使います。 コマンドは現在のフォルダ、もしくは定義されている場合は `--source-root`. Python及びJavaScript/TypeScriptの分析では不要です。
`--db-cluster`とともに使われると、 オプション。 複数言語のコードベースを使って、 `--language`.
`--no-run-unnecessary-builds` 推奨されます。 CodeQL CLIがビルドをモニターする必要がない場合に、言語のビルドコマンドを抑制するために使います(たとえばPythonやJavaScript/TypeScript)。
`--source-root` オプション。 CLIをリポジトリのチェックアウトルート外で実行する場合に使います。 デフォルトでは、database createコマンドは現在のディレクトリがソースファイルのルートディレクトリであると推定します。別の場所を指定する場合はこのオプションを使ってください。

詳しい情報についてはCodeQL CLIのドキュメンテーション中のCodeQLデータベースの作成を参照してください。

単一言語の例

この例は、/checkouts/example-repoにチェックアウトされたリポジトリのCodeQLデータベースを作成します。 これはJavaScript extractorを使い、リポジトリ中の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にチェックアウトされたリポジトリの2つのCodeQLデータベースを作成します。 これは以下を使用します。

  • --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. Create a CodeQL database (see above).
  2. Optional, run codeql pack download to download any CodeQL packs (beta) that you want to run during analysis. For more information, see "Downloading and using CodeQL query packs" below.
    codeql pack download <packs> 
  3. Run codeql database analyze on the database and specify which packs and/or queries to use.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <packs,queries> 

ノート: 1つのコミットに対して複数のCodeQLデータベースを分析する場合、このコマンドが生成するそれぞれの結果セットに対してSARIFカテゴリを指定しなければなりません。 結果をGitHubにアップロードする際には、code scanningはこのカテゴリを使ってそれぞれの言語に対する結果を別々に保存します。 これを忘れると、それぞれのアップロードが以前の結果を上書きしてしまいます。

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>
Option 必須 使い方
<database> 分析するCodeQLデータベースを含むディレクトリのパスを指定します。
<packs,queries> Specify CodeQL packs or queries to run. To run the standard queries used for code scanning, omit this parameter. CodeQL CLIバンドル内に含まれている他のクエリスイートを見るには、/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suitesを見てください。 独自のクエリスイートの作成に関する情報については、CodeQL CLIのドキュメンテーション中のCodeQLクエリスイートの作成を参照してください。
`--format` コマンドが生成する結果ファイルのフォーマットを指定します。 GitHubへアップロードする場合、これはsarif-latestとすべきです。 詳しい情報については「code scanningの SARIF サポート」を参照してください。
`--output` SARIF結果ファイルを保存する場所を指定します。
--sarif-category 単一データベース分析のオプション。 リポジトリ中の単一のコミットに対する複数のデータベースを分析する際に、言語を定義するために必要。 この分析でSARIF結果ファイルに含めるカテゴリを指定してください。 A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|
<packs> オプション。 Use if you have downloaded CodeQL query packs and want to run the default queries or query suites specified in the packs. For more information, see "Downloading and using CodeQL packs."
`--threads` オプション。 クエリを実行するのに複数のスレッドを使いたいときに使用します。 デフォルト値は1です。 クエリの実行を高速化するためにより多くのスレッドを指定できます。 スレッド数を論理プロセッサ数に設定するには0を指定してください。
`--verbose` オプション。 分析のプロセスとデータベース作成プロセスからの診断データに関する詳細な情報を得るために使用します。

詳しい情報については、CodeQL CLIのドキュメンテーション中のCodeQL CLIでのデータベースの分析を参照してください。

基本的な例

この例は/codeql-dbs/example-repoに保存されたCodeQLデータベースを分析し、結果を/temp/example-repo-js.sarifという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 upload supports a maximum of 5000 results per upload. この制限を超えた結果は無視されます。 ツールがあまりに多くの結果を生成する場合、最も重要なルールやクエリに対する結果に焦点を当てるよう、設定を更新すべきです。

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

結果をGitHubにアップロードする前に、GitHub Appもしくは以前に作成した個人アクセストークンを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
Option 必須 使い方
`--repository` データをアップロードするリポジトリのOWNER/NAMEを指定します。 リポジトリがパブリックでなければ、オーナーはGitHub Advanced Securityのライセンスを持つEnterprise内のOrganizationでなければならず、GitHub Advanced Securityはリポジトリで有効化されていなければなりません。 詳しい情報については「リポジトリのセキュリティ及び分析の設定の管理」を参照してください。
`--ref` チェックアウトして分析したrefの名前を指定して、結果が正しいコードとマッチできるようにします。 ブランチではrefs/heads/BRANCH-NAMEを、Pull Requestのheadコミットではrefs/pulls/NUMBER/headを、Pull Requestに対してGitHubが生成したマージコミットではrefs/pulls/NUMBER/mergeを使ってください。
`--commit` 分析したコミットの完全なSHAを指定してください。
`--sarif` ロードするSARIFファイルを指定してください。
`--github-auth-stdin` オプション。 GitHub AppもしくはGitHubのREST APIの認証のために作成された個人アクセストークンを標準入力経由でCLIに渡すために使います。 このトークンが設定された環境変数GITHUB_TOKENにコマンドがアクセスできる場合、これは必要ありません。

詳しい情報については、CodeQL CLIのドキュメンテーション中のgithub upload-resultsを参照してください。

基本的な例

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

$ 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中で直接、あるいはブランチのSecurity(セキュリティ)タブ上でアラートを見ることができます。 詳しい応報については「Pull Requestのcode scanningアラートのトリアージ」及び「リポジトリのcode scanningアラートの管理」を参照してください。

Downloading and using CodeQL query packs

Note: The CodeQL package management functionality, including CodeQL packs, is currently in beta and subject to change.

The CodeQL CLI bundle includes queries that are maintained by GitHub experts, security researchers, and community contributors. If you want to run queries developed by other organizations, CodeQL query packs provide an efficient and reliable way to download and run queries. For more information, see "About code scanning with CodeQL."

Before you can use a CodeQL pack to analyze a database, you must download any packages you require from the GitHub コンテナレジストリ by running codeql pack download and specifying the packages you want to download. If a package is not publicly available, you will need to use a GitHub App or personal access token to authenticate. For more information and an example, see "Uploading results to GitHub" above.

codeql pack download <scope/name@version>,... 
Option 必須 使い方
`` Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded.
`--github-auth-stdin` オプション。 Pass the GitHub App or personal access token created for authentication with GitHub's REST API to the CLI via standard input. このトークンが設定された環境変数GITHUB_TOKENにコマンドがアクセスできる場合、これは必要ありません。

基本的な例

This example runs two commands to download the latest version of the octo-org/security-queries pack and then analyze the database /codeql-dbs/example-repo.

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download octo-org/security-queries

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0

$ codeql database analyze /codeql-dbs/example-repo  octo-org/security-queries \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/1] 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.
> [1/1 eval 394ms] Evaluation done; writing results to docto-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

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

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

# 'codeql-dbs'ディレクトリ中のJava及びPythonのためのCodeQLデータベースを急く性
# コードベースのための通常のビルドスクリプトの 'myBuildScript'を呼ぶ

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

# JavaのためのCodeQLデータベース'codeql-dbs/java'を分析
# データに'java'の結果としてタグ付けし、'java-results.sarif'に保存

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

# PythonのためのCodeQLデータベース'codeql-dbs/python'を分析
# データに'python'の結果としてタグ付けし、'python-results.sarif'に保存

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

# Javaの結果付きのSARIF ファイル'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

# Pythonの結果付きのSARIFファイル'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ログを見る」を参照してください。

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

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

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

CIシステムがCodeQL CLIをトリガーできない場合の代替方法

If your CI system cannot trigger the CodeQL CLI autobuild and you cannot specify a command line for the build, you can use indirect build tracing to create CodeQL databases for compiled languages. For more information, see Using indirect build tracing in the documentation for the CodeQL CLI.

参考リンク

このドキュメントは役立ちましたか?

プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?