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

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

GitHub は、静的分析結果交換形式 (SARIF) ファイルの情� �を使用して、リポジトリに code scanning アラートを作成します。 SARIF ファイルは、API または GitHub Actions を使用してリポジトリにアップロードできます。 詳細については、「リポジトリの code scanning アラートの管理」を参照してく� さい。

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

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

• GitHub Actions を使用して CodeQL アクションを実行している� �合、追� のアクションは不要です。 CodeQL アクションは、分析の完了時に SARIF ファイルを自動的にアップロードします。
• GitHub Actions を使用して SARIF 互換の分析ツールを実行します。ワークフローを更新して、結果をアップロードする最後の手� �を含めることができます (下記を参照)。
• CodeQL CLI は、CI システ� で code scanning を実行するために、CLI を使用して結果を GitHub にアップロードできます (詳細については、「CI システ� での CodeQL CLI のインストール」を参照してく� さい)。
• CodeQL runnerは、CI システ� で code scanning を実行するためのものであり、既定では、完了時に、このランナーによって結果が GitHub に自動的にアップロードされます。 自動アップロードをブロックする� �合、結果をアップロードする準備ができたら、upload コマンドを使うことができます (詳しくは、「CI システ� での CodeQL runnerの実行」を参照してく� さい)。
• リポジトリの外部で成果物として結果を生成するツールでは、code scanning API を使用してファイルをアップロードできます (詳細については、「SARIF データとして分析をアップロードする」を参照してく� さい)。

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

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

ワークフローでは、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 を作成できます。 重複するアラートの防止方法の詳細については、コード スキャンの SARIF サポートに関するセクションを参照してく� さい。

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

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

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

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

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

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@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
          # 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@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 のワークフロー構文
• "ワークフローの履歴を表示する"
• "CI システ� での CodeQL code scanning について"
• "分析を SARIF データとしてアップロードする"