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 にアップロードする」を参照してください。

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

結果を GitHub Enterprise Server にアップロードする前に、まず 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 Enterprise Server にアップロードできます。 詳しくは、「既存の CI システムでコード スキャンを使用する」を参照してください。

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

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

結果を GitHub Enterprise Server にアップロードする前に、以前に作成した 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-url=<URL> \
    --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-url=<URL> \
    

オプション	必須	使用法
--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-url		GitHub Enterprise ServerのURLを指定してください。
--github-auth-stdin		GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレット ストアから CLI に渡します。 このトークンを使用して設定された GITHUB_TOKEN 環境変数にコマンドがアクセスできる場合、これは必要ありません。

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

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

次の例では、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-url=https://HOSTNAME \
    

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

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

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

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

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

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

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

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

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

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

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

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

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