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 にアップロードする前に、まず security_events 書き込み権限を持つ personal access token を生成する必要があります。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。

コード スキャン アラートとして 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://github.example.com \
    

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