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

code scanning に対する SARIF ファイルのアップロードについて

GitHub は、静的分析結果交換形式 (SARIF) ファイルの情報を使用して、リポジトリに code scanning アラートを作成します。 SARIF ファイルは、API または GitHub Actions を使用してリポジトリにアップロードできます。 詳しくは、「既存の CI システムでコード スキャンを使用する」をご覧ください。

SARIF ファイルは、CodeQL を含む多くの静的解析セキュリティテストツールを使用して生成できます。 結果は SARIF バージョン 2.1.0 を使用する必要があります。 詳しくは、「Code scanningの SARIF サポート」をご覧ください。

結果は、GitHub Actions、code scanning API、または CodeQL CLI を使ってアップロードできます。 最適なアップロード方法は、SARIF ファイルの生成方法によって異なります。以下、例を示します。

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

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

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

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

• sarif-file は、アップロードする SARIF ファイルのファイルまたはディレクトリを構成します。 ディレクトリまたはファイルのパスは、リポジトリのルートからの相対パスです。
• category (省略可能) は、SARIF ファイルで結果のカテゴリを割り当てます。 これにより、複数の方法で同じコミットを分析し、GitHub の code scanning ビューを使用して結果を確認できます。 たとえば、複数のツールを使用して分析できます。mono リポジトリでは、変更されたファイルのサブセットに基づいてリポジトリのさまざまなスライスを分析できます。

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

upload-sarif アクションは、push および scheduled イベントが発生したときに実行されるように構成できます。 GitHub Actions イベントの詳細については、「ワークフローをトリガーするイベント」を参照してください。

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@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        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 ファイルを出力します。 その後、ワークフローにより、upload-sarif アクションが使用され results.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@v4
      - 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@v3
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

参考資料

• SARIF アップロードのトラブルシューティング
• GitHub Actions　のワークフロー構文
• ワークフロー実行の履歴を表示する
• 既存の CI システムでコード スキャンを使用する
• コード スキャン用の REST API エンドポイント