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

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

Code scanning is available for organization-owned repositories where GitHub Advanced Security is enabled. 詳しい情報については、「GitHub Advanced Security について」を参照してください。

ノート: この機能を使用するには、サイト管理者がyour GitHub Enterprise Server instanceのcode scanningを有効にする必要があります。 詳しい情報については「アプライアンスのためのcode scanningの設定」を参照してください。

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

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

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

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

以下のオプションを使って、どのコマンドでもコマンドラインヘルプを表示できます。 --help

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

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

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

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

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

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

    codeql database create <database> --command<build> --language=<language-identifier>

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

Option 必須 使い方
<database> CodeQLデータベースを作成するディレクトリの名前と場所を指定します。 既存のディレクトリを上書きしようとすると、コマンドは失敗します。 --db-clusterも指定した場合、これは親ディレクトリになり、分析する言語ごとにサブディレクトリが作られます。
`--language` データベースを作成する言語の識別子を指定します。`cpp`, `csharp`, `go`, `java`, `javascript`, and `python`のいずれかです(TypeScriptのコードを分析するときはjavascriptを使ってください)。
`--command` 推奨されます。 コードベースのビルドプロセスを呼び出すビルドコマンドもしくはスクリプトを指定するために使います。 コマンドは現在のフォルダ、もしくは定義されている場合は `--source-root`. 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.

CodeQLデータベースの分析

  1. Create a CodeQL database (see above).
  2. Run codeql database analyze on the database and specify which queries to use.
    codeql database analyze <database> --format=<format> \
        --output=<output>   <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へアップロードする場合、これはsarifv2.1.0とすべきです。 詳しい情報については「code scanningの SARIF サポート」を参照してください。
`--output` SARIF結果ファイルを保存する場所を指定します。
`--threads` オプション。 クエリを実行するのに複数のスレッドを使いたいときに使用します。 デフォルト値は1です。 クエリの実行を高速化するためにより多くのスレッドを指定できます。 スレッド数を論理プロセッサ数に設定するには0を指定してください。
`--verbose` オプション。 分析のプロセスに関する詳細な情報を得るために使用します。

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

基本的な例

この例は/codeql-dbs/example-repoに保存されたCodeQLデータベースを分析し、結果を/temp/example-repo-js.sarifというSARIFファイルに保存します。

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls 
    --format=sarifv2.1.0 --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 Enterprise Serverへの結果のアップロード

ノート:

  • 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 Enterprise Serverにアップロードする前に、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-url=<URL> --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-url` GitHub Enterprise ServerのURLを指定してください。
`--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-url=https://github.example.com \
    --github-auth-stdin

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

参考リンク

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

プライバシーポリシー

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

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

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

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

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