Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となります: 2022-10-12. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください

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

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

Who can use this feature

People with write permissions to a repository can upload code scanning data generated outside GitHub.

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. 詳細については、「GitHub Advanced Security について」を参照してください。

注: この機能を使用するには、サイト管理者が your GitHub Enterprise Server instance の code scanning を有効にする必要があります。 詳しくは、「アプライアンスでの code scanning の構成」をご覧ください。

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 アップロードでは、アップロードごとに最大 5,000 件の結果がサポートされます。 この制限を超える結果はすべて無視されます。 ツールで生成される結果が多すぎる場合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。

  • SARIF アップロードでサポートされる gzip 圧縮の SARIF ファイルの最大サイズは、アップロードごとに 10 MB となります。 この制限を超えるアップロードはすべて拒否されます。 含まれる結果が多すぎるために SARIF ファイルが大きくなりすぎた場合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。

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

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

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

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

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

参考資料