SARIF ファイルを GitHub にアップロードする

メモ

この機能を使用するには、サイト管理者が code scanning を有効にする必要があります。詳しくは、「アプライアンス用コードスキャンの構成」をご覧ください。

Enterprise の所有者が Enterprise レベルで GitHub Code Security ポリシーを設定している場合、code scanning を有効または無効にできない場合があります。詳しくは、「エンタープライズのコードセキュリティと分析のためのポリシーの適用」をご覧ください。

サードパーティの分析ツールまたは CI/CD システムを使用してコードの脆弱性をスキャンする場合は、SARIF ファイルを生成し、GitHub にアップロードできます。最適なアップロード方法は、SARIF ファイルの生成方法によって異なります。

たとえば、次のコマンドを使用します。

GitHub Actions を使用して CodeQL アクションを実行している場合、追加のアクションは不要です。 CodeQL アクションは、分析の完了時に SARIF ファイルを自動的にアップロードします。
GitHub Actions を使用して SARIF 互換の分析ツールを実行します。ワークフローを更新して、結果をアップロードする最後の手順を含めることができます。 GitHub Actions での code scanning 分析をアップロードする
CodeQL CLI を使用して CI システムで code scanning を実行し、CLI を使って結果を GitHub にアップロードできます。「既存の CI システムでコードスキャンを使用する」を参照してください。
リポジトリの外部で成果物として結果を生成するツールでは、code scanning API を使用してファイルをアップロードできます。「コードスキャン用の REST API エンドポイント」を参照してください。

デフォルトでは、code scanningはリポジトリの分析ごとに1つのSARIF結果ファイルを期待します。リポジトリ内のコミットに対して複数の結果セットをアップロードする場合は、各結果セットを一意のセットとして識別する必要があります。

GitHub Actions での code scanning 分析をアップロードする

GitHub Actions を使用してサードパーティの SARIF ファイルをリポジトリにアップロードするには、ワークフローが必要です。詳しくは、「ワークフローの書き込み」をご覧ください。

ワークフローでは、upload-sarif リポジトリの一部である github/codeql-action アクションを使用する必要があります。これには、アップロードの設定に使用できる入力パラメータがあります。使用する主な入力パラメーターは次のとおりです。

        `sarif_file` は、アップロードする SARIF ファイルのファイルまたはディレクトリを構成します。 ディレクトリまたはファイルのパスは、リポジトリのルートからの相対パスです。

        `category` (オプション) は、SARIF ファイルで結果のカテゴリを割り当てます。 これにより、複数の方法で同じコミットを分析し、GitHub の code scanning ビューを使用して結果を確認できます。 たとえば、複数のツールを使用して分析できます。mono リポジトリでは、変更されたファイルのサブセットに基づいてリポジトリのさまざまなスライスを分析できます。

詳細については、「upload-sarifアクション」を参照してください。

          `upload-sarif` アクションは、`push` および `scheduled` イベントが発生したときに実行されるように構成できます。 GitHub Actions イベントの詳細については、「[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows)」を参照してください。

SARIFファイルに partialFingerprints が含まれていない場合、upload-sarif アクションは partialFingerprints フィールドを自動的に計算して、重複するアラートが発生しないようにします。 GitHub では、リポジトリに SARIF ファイルと、スタティック分析で使用されるソースコードの両方が含まれている場合にのみ、partialFingerprints を作成できます。重複するアラートの防止の詳細については、「Code scanningの SARIF サポート」を参照してください。

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

リポジトリ外で生成された SARIF ファイルのワークフロー例

SARIF ファイルをリポジトリにコミットした後でアップロードする新しいワークフローを作成できます。これは、SARIF ファイルがご自分のリポジトリの外部の成果物として生成される場合に便利です。

この例のワークフローは、コミットがリポジトリにプッシュされるたびに実行されます。このアクションでは、partialFingerprints プロパティを使用して、変更が発生したかどうかを確認します。コミットがプッシュされたときの実行に加えて、ワークフローは週に 1 回実行されるようにスケジュールされています。詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

このワークフローは、リポジトリのルートにある results.sarif ファイルをアップロードします。ワークフローファイルの作成の詳細については、「ワークフローの書き込み」を参照してください。

または、このワークフローを変更して、SARIF ファイルのディレクトリをアップロードすることもできます。たとえば、すべての SARIF ファイルをリポジトリのルートにある sarif-output というディレクトリに配置し、アクションの入力パラメーター sarif_file を sarif-output に設定できます。ディレクトリをアップロードする場合、各 SARIF ファイルには、結果のカテゴリを定義するための一意の runAutomationDetails.id が含まれている必要があることにご注意ください。詳しくは、「Code scanningの SARIF サポート」をご覧ください。

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

ESLint 分析ツールを実行するワークフローの例

継続的インテグレーション (CI) ワークフローの一部としてサードパーティの SARIF ファイルを生成する場合は、CI テストを実行した後に upload-sarif アクションをステップとして追加できます。 CI ワークフローがない場合は、GitHub Actions テンプレートを使用して作成できます。詳しくは、「GitHub Actionsのクイックスタート」をご覧ください。

ワークフローでは、ESLint 静的分析ツールをワークフローのステップとして実行する例を示しています。 Run ESLint ステップは、ESLint ツールを実行し、results.sarif ファイルを出力します。その後、ワークフローにより、results.sarif アクションが使用され upload-sarif ファイルが GitHub にアップロードされます。ワークフローファイルの作成の詳細については、「GitHub Actionsについて」を参照してください。

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

コミット用に複数の SARIF ファイルをアップロードする

デフォルトでは、code scanningはリポジトリの分析ごとに1つのSARIF結果ファイルを期待します。したがって、コミットから2つめのSARIF結果ファイルをアップロードすると、それはデータのオリジナルのセットの置き換えとして扱われます。たとえば、分析ツールが分析する言語ごと、または使用するルールのセットごとに異なる SARIF ファイルを生成する場合、1 つの分析に対して 2 つの異なる SARIF ファイルをアップロードすることができます。リポジトリ内のコミットに対して複数の結果セットをアップロードする場合は、各結果セットを一意のセットとして識別する必要があります。

コミット用に複数の SARIF ファイルをアップロードする場合は、分析ごとに "カテゴリ" を指定する必要があります。カテゴリを指定する方法は、分析方法によって異なります。

CodeQL CLI を直接使用して、SARIF ファイルを生成するときに --sarif-category 引数を codeql database analyze コマンドに渡します。詳しくは、「CodeQL CLI について」をご覧ください。
GitHub Actions を codeql-action/analyze で使用すると、ワークフロー名とマトリックス変数 (通常は language) からカテゴリが自動的に設定されます。これをオーバーライドするには、アクションの category 入力を指定します。これは、単一のワークフローでモノリポジトリのさまざまなセクションを分析する場合に便利です。
GitHub Actions を使用して他の静的分析ツールから結果をアップロードする場合、1 つのワークフローで同じツールに対して複数の結果ファイルをアップロードするには、category 入力を指定する必要があります。詳しくは、「SARIF ファイルを GitHub にアップロードする」をご覧ください。
これらの方法のいずれかを使用していない場合は、アップロードする SARIF ファイルごとに一意の runAutomationDetails.id を指定する必要があります。このプロパティの詳細については、runAutomationDetailsオブジェクトを参照してください。

同じカテゴリと同じツールからコミット用の 2 つ目の SARIF ファイルをアップロードすると、以前の結果が上書きされます。ただし、1 つの GitHub Actions ワークフロー実行で同じツールとカテゴリに対して複数の SARIF ファイルをアップロードしようとすると、設定ミスが検出され、実行は失敗します。

詳細については、次を参照してください。

        [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)

        [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)

        [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)

        [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

        [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)