CodeQL 分析結果を GitHub にアップロードする

SARIF 出力について

GitHub は、静的分析結果交換形式 (SARIF) ファイルの情報を使用して、リポジトリに code scanning アラートを作成します。 SARIF は、さまざまな静的分析ツールの出力を表すように設計されており、SARIF 仕様には、"省略可能" と見なされる多くの機能があります。結果は SARIF バージョン 2.1.0 を使用する必要があります。詳しくは、「Code scanningの SARIF サポート」をご覧ください。

CodeQL CLI を使って CodeQL データベースを分析した後、結果が含まれる SARIF ファイルが作成されます。詳しくは、「CodeQL クエリによるコード分析」をご覧ください。その後、CodeQL CLI を使って GitHub に結果をアップグレードできます。

CodeQL CLI 以外の方法を使った場合、他のアップロード方法を使えます。詳しくは、「SARIF ファイルを GitHub にアップロードする」をご覧ください。

Note

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

GitHubでの認証のためのトークンの生成

結果を GitHub にアップロードする前に、まず personal access token を生成する必要があります。

Personal access token (classic) には、必要なリポジトリに対する "Code scanning アラート" の読み書きアクセス権が必要です。
Fine-grained personal access token には、"repo" の security_events に対するアクセス権が必要です。

詳しくは、「個人用アクセストークンを管理する」をご覧ください。

コードスキャンアラートとして GitHub に表示する結果を作成するため、サードパーティの CI システムに CodeQL CLI をインストールしてある場合は、GitHub App または personal access token を使って、結果を GitHub にアップロードできます。詳しくは、「既存の CI システムでコードスキャンを使用する」をご覧ください。

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

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

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

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

構成の最も安全で信頼性の高い方法を決定した場合は、各 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>

オプション	必須	使用法
`--repository`		データのアップロード先となるリポジトリの OWNER/NAME を指定します。リポジトリがパブリックでなければ、オーナーは GitHub Advanced Security のライセンスを持つエンタープライズ内の組織でなければならず、GitHub Advanced Security はリポジトリで有効化されていなければなりません。詳しくは、「リポジトリのセキュリティと分析設定を管理する」をご覧ください。
`--ref`		チェックアウトして分析した `ref` の名前を指定して、結果を正しいコードと照合できるようにします。ブランチで `refs/heads/BRANCH-NAME` を使用するか、pull request のヘッドコミットで `refs/pull/NUMBER/head` を使用するか、pull request の GitHub で生成されたマージコミットで `refs/pull/NUMBER/merge` を使用します。
`--commit`		分析したコミットの完全な SHA を指定します。
`--sarif`		読み込む SARIF ファイルを指定します。
`--github-auth-stdin`		GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレットストアから CLI に渡します。このトークンを使用して設定された `GITHUB_TOKEN` 環境変数にコマンドがアクセスできる場合、これは必要ありません。

詳しくは、「github upload-results」をご覧ください。

Note

1 つのコミットに対して複数の CodeQL データベースを分析する場合、このコマンドで生成された結果セットごとに SARIF カテゴリを指定する必要があります。結果をGitHubにアップロードする際には、code scanningはこのカテゴリを使ってそれぞれの言語に対する結果を別々に保存します。この操作を忘れた場合は、各アップロードで前の結果が上書きされます。詳しくは、「CodeQL クエリによるコード分析」をご覧ください。

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 中で直接、あるいはブランチの [Security] タブ上でアラートを確認できます。詳細については、「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-typescript --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 ファイルをアップロードするプロセスと同じです。