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

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

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

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

You can upload the results using GitHub Actions, the code scanning API, the CodeQL CLI, or the CodeQLランナー. 最適なアップロード方法は、SARIF ファイルの生成方法によって異なります。以下、例を示します。

• GitHub Actions を使用して CodeQL アクションを実行している場合、追加のアクションは不要です。 SARIF ファイルは、ファイルのアップロードに使用したものと同じ GitHub Actions ワークフローで実行する SARIF 互換の分析ツールから生成できます。
• "ワークフロー実行の管理"
• The CodeQL CLI to run code scanning in your CI system, you can use the CLI to upload results to GitHub (for more information, see "Running CodeQL CLI in your CI system").
• GitHub は、リポジトリにアップロードされた SARIF ファイルからの code scanning アラートを表示します。 If you block the automatic upload, when you are ready to upload results you can use the upload command (for more information, see "Running CodeQLランナー in your CI system").
• 結果をリポジトリ外に成果物として生成するツールの場合、code scanning API を使用してファイルをアップロードできます (詳しい情報については、「解析を SARIF データとしてアップロードする」を参照)。

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

サードパーティの SARIF ファイルを GitHub にアップロードするには、GitHub Actions ワークフローが必要です。 詳しい情報については、「GitHub Actions を学ぶ」を参照してください。

ワークフローは、upload-sarif アクションを使用する必要があります。 これには、アップロードの設定に使用できる入力パラメータがあります。 使用する主な入力パラメータは、アップロードする SARIF ファイルのファイルまたはディレクトリを設定する sarif-file です。 ディレクトリまたはファイルのパスは、リポジトリのルートからの相対パスです。 詳しい情報については、「upload-sarif アクション」を参照してください。

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

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

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

SARIF ファイルをリポジトリにコミットした後でアップロードする新しいワークフローを作成できます。 これは、SARIF ファイルがリポジトリ外のアーティファクトとして生成される場合に役立ちます。

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

このワークフローは、リポジトリのルートにある results.sarif ファイルをアップロードします。 ワークフローファイルの作成に関する詳しい情報については、「GitHub Actions を学ぶ」を参照してください。

または、このワークフローを変更して、SARIF ファイルのディレクトリをアップロードすることもできます。 たとえば、すべての SARIF ファイルをリポジトリのルートにある sarif-output というディレクトリに配置し、アクションの入力パラメータ sarif_file を sarif-output に設定できます。

name: "Upload SARIF"

# コードがリポジトリにプッシュされるたびに、スケジュールに従ってワークフローを実行します。
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v2
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v1
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

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"

# コードがリポジトリにプッシュされるたびに、スケジュールに従ってワークフローを実行します。
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - 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@v1
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

参考リンク

• GitHub Actionsのワークフロー構文
• "Viewing your workflow history"
• "About CodeQL code scanning in your CI system"
• 「解析を SARIF データとしてアップロードする」