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

          CodeQLを使用してCodeQL CLI データベースを分析すると、結果を含む SARIF ファイルが作成されます。 その後、 CodeQL CLI を使用して結果を GitHubにアップロードできます。

          CodeQL CLI以外の方法を使用して結果を生成した場合は、他のアップロード方法を使用できます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)」をご覧ください。

で認証用のトークンを生成する GitHub

結果を GitHubにアップロードする前に、まず personal access tokenを生成する必要があります。「個人用アクセストークンを管理する」を参照してください。

        **
        Personal access token (classic)
        **が必要なリポジトリに対して"Code scanning アラート"の読み取りと書き込みアクセスを必要とします。

        **
        Fine-grained personal access token
        ** には、"repo" **security_events アクセスが** 必要です。

サードパーティの CI システムに CodeQL CLI をインストールしている場合は、 GitHub App を使用して結果を GitHubにアップロードすることもできます。「既存の CI システムでコードスキャンを使用する」を参照してください。

結果をGitHubにアップロード

SARIF プロパティにアップロード用のサポートされているサイズがあり、ファイルがコードスキャンと互換性があることを確認します。詳しくは、「Code scanningの SARIF サポート」をご覧ください。
前のセクションで作成した GitHub App または personal access token を CodeQL CLIに渡す最適な方法を決定します。シークレットストアの安全な使用に関する CI システムのガイダンスを確認することをお勧めします。 CodeQL CLIでは、次の機能がサポートされます。
- シークレットストアとインターフェイスに --github-auth-stdin オプションを使います (推奨)。
- 環境変数 GITHUB_TOKEN にシークレットを保存し、--github-auth-stdin オプションを含めずに CLI を実行する。
- テスト目的であれば、--github-auth-stdin コマンドラインオプションを渡し、標準入力経由で一時トークンを指定することができます。

構成の最も安全で信頼性の高い方法を決定した場合は、各 SARIF 結果ファイルで codeql github upload-results を実行し、トークンが環境変数 --github-auth-stdin で使用可能でない限り、GITHUB_TOKEN を含めます。

# 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> \

Option	必須	Usage
`--repository`		データのアップロード先となるリポジトリの OWNER/NAME を指定します。所有者は、エンタープライズ内の組織有効になっている必要がありますGitHub Code Security。ただし、リポジトリがパブリックである場合はこの限りではありません。詳しくは、「リポジトリのセキュリティと分析設定を管理する」をご覧ください。
`--ref`		チェックアウトして分析した `ref` の名前を指定して、結果を正しいコードと照合できるようにします。ブランチ使用の場合: `refs/heads/BRANCH-NAME`、プル要求のヘッドコミットの場合は `refs/pull/NUMBER/head`、またはプル要求の GitHub生成されたマージコミットの場合は、 `refs/pull/NUMBER/merge`を使用します。
`--commit`		分析したコミットの完全な SHA を指定します。
`--sarif`		読み込む SARIF ファイルを指定します。
`--github-url`

          お使いの GitHub Enterprise Server インスタンスの URL を指定します。 |

| | | --github-auth-stdin | | 標準入力を使用してシークレットストアから GitHub App の REST API を使用して認証用に作成されたpersonal access tokenまたはGitHubを CLI に渡します。このトークンを使用して設定された GITHUB_TOKEN 環境変数にコマンドがアクセスできる場合、これは必要ありません。 |

詳しくは、「GitHubで結果をアップロード (github upload-results)」をご覧ください。

メモ

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

基本的な結果アップロード方法の例 GitHub

次の例では、SARIF ファイル temp/example-repo-js.sarif からリポジトリ my-org/example-repo に結果をアップロードします。結果が code scanning ブランチのコミット deb275d2d5fe9a522a0b7bd8b6b6a1c939552718に対する結果であることをmain API に通知します。この例では、GitHub Appの REST API を使用して認証用に作成されたpersonal access tokenまたはGitHubが、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 \

アップロードが失敗しなければ、このコマンドからの出力はありません。コマンドプロンプトは、アップロードが完了してデータ処理が開始された時点で戻ってきます。小規模なコードベースでは、すぐにcode scanningでGitHubアラートを調べることができます。チェックアウトしたコードに応じて、プル要求またはブランチの [ Security ] タブにアラートを直接表示できます。

分析が失敗した場合に診断情報を GitHub にアップロードする

          CodeQL CLIデータベースの分析が正常に完了すると、ファイル カバレッジ、警告、エラーなどの診断情報が収集され、結果と共に SARIF ファイルに含まれます。 SARIF ファイルをアップロードして GitHub すると、リポジトリの code scanningツールの状態ページ に診断情報が表示され、 CodeQL がどの程度正常に動作しているかを簡単に確認し、問題をデバッグできます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page)」をご覧ください。

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

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

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

「データベースエクスポート診断」を使用して、失敗した分析用の 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 を使用して SARIF ファイルをにアップロードします。次に例を示します。

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 ファイルをアップロードするプロセスと同じです。

この機能を使用できるユーザーについて

この記事で