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

サードパーティの静的解析ツールからGitHubにSARIFファイルをアップロードし、リポジトリ内でそれらのツールからのcode scanningアラートを見ることができます。

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

書き込み アクセスを持つユーザー

Code scanning は、次のリポジトリの種類で使用できます。

  • GitHub.com 上のパブリックリポジトリ
  • GitHub Team、GitHub Enterprise Cloud、または GitHub Enterprise Server 上の組織所有リポジトリ。 GitHub Code Security が 有効になっています。

この記事で

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

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

  •         GitHub Actions
        CodeQLアクションを実行する場合、それ以上のアクションは必要ありません。 
        CodeQLアクションでは、分析が完了すると、SARIF ファイルが自動的にアップロードされます。

  •         GitHub Actions SARIF 互換分析ツールを実行するには、結果をアップロードする最後の手順を含むようにワークフローを更新できます。 
        code scanning
        [を使用したGitHub Actions分析のアップロードを](#uploading-a-code-scanning-analysis-with-github-actions)参照してください。
  • CI システムでCodeQL CLIを実行するcode scanningは、CLI を使用して結果をGitHubにアップロードできます。 「既存の CI システムでコード スキャンを使用する」を参照してください。
  • リポジトリの外部で成果物として結果を生成するツールでは、 code scanning API を使用してファイルをアップロードできます。 「コード スキャン用の REST API エンドポイント」を参照してください。

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

メモ

プライベート リポジトリと内部リポジトリの場合、code scanning機能がリポジトリに対して有効になっている場合、GitHub Code Securityを使用できます。 エラー GitHub Code Security or GitHub Advanced Security must be enabled for this repository to use code scanningが表示された場合は、 GitHub Code Security が有効になっていることを確認します。 詳細については、「リポジトリのセキュリティと分析設定を管理する」を参照してください。

          code scanningを使用した分析のアップロードGitHub Actions

          GitHub Actionsを使用してサードパーティの SARIF ファイルをリポジトリにアップロードするには、ワークフローが必要です。 詳細については、「[AUTOTITLE](/actions/learn-github-actions)」を参照してください。

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

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

  •         `category` (オプション) は、SARIF ファイルで結果のカテゴリを割り当てます。 これにより、同じコミットを複数の方法で分析し、code scanningのGitHub ビューを使用して結果を確認できます。 たとえば、複数のツールを使用して分析できます。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のクイック スタート」を参照してください。

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

ワークフローでは、ESLint 静的分析ツールをワークフローのステップとして実行する例を示しています。 Run ESLint ステップは、ESLint ツールを実行し、results.sarif ファイルを出力します。 その後、ワークフローは、results.sarif アクションを使用してGitHubにupload-sarif ファイルをアップロードします。 ワークフロー ファイルの作成の詳細については、「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)