SARIF 出力について
GitHub で Static Analysis Results Interchange Format (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 に渡す最適な方法を見極める必要があります。 シークレット ストアの安全な使用に関する 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 ファイルをアップロードするプロセスと同じです。