依存関係送信 API について
REST API を使って、プロジェクトの依存関係を送信できます。 これにより、ソフトウェアのコンパイル時やビルド時に解決されるものなどの依存関係を GitHub の依存関係グラフ機能に追加し、プロジェクトのすべての依存関係をより完全に把握できます。
依存関係グラフには、リポジトリ内のマニフェストまたはロック ファイル (JavaScript プロジェクトの package-lock.json
ファイルなど) から識別された依存関係に加えて、この API を使って送信したすべての依存関係が表示されます。 依存関係グラフの表示の詳細については、「リポジトリの依存関係を調べる」を参照してください。
送信された依存関係は、既知の脆弱性に対する Dependabot alerts と Dependabot security updates を受け取ります。 GitHub Advisory Database のサポートされているエコシステムのいずれかからの依存関係に対する Dependabot alerts のみを受け取ります。 サポートされているこれらのエコシステムについて詳しくは、「GitHub Advisory Database について」をご覧ください。 依存関係送信 API を介して送信された推移的な依存関係の場合、更新プログラムが利用可能な場合は、Dependabot が自動的に pull request を開き、親依存関係を更新します。
送信された依存関係は依存関係レビューに表示されますが、組織の依存関係の分析情報には_表示されません_。
注: 依存関係レビュー API と 依存関係送信 API は連携して動作します。 これは、依存関係レビュー API には、依存関係送信 API を介して送信された依存関係が含まれます。
依存関係は、スナップショットの形式で 依存関係送信 API に送信されます。 スナップショットは、コミット SHA や他のメタデータに関連付けられている依存関係のセットであり、コミットのリポジトリの現在の状態を反映しています。 スナップショットは、ビルド時に検出された依存関係から、またはソフトウェア部品表 (SBOM) から生成できます。 これらのユース ケースのいずれかをサポートする GitHub Actions があります。 依存関係送信 API の詳細については、「依存関係送信用の REST API エンドポイント」を参照してください。
ビルド時に依存関係を送信する
GitHub Actions ワークフローで 依存関係送信 API を使って、プロジェクトのビルド時にプロジェクトの依存関係を送信できます。
事前に作成されたアクションを使用する
依存関係送信 API を使う最も簡単な方法は、依存関係のリストを収集して必要なスナップショット形式に変換したものを API に送信するアクションを事前に作成し、それをリポジトリに追加することです。 さまざまなエコシステムについてこれらの手順を行うアクションを GitHub Marketplace で利用できます。 これらのアクションの一部は、サード パーティによって提供されます。 現在使用可能なアクションへのリンクを次の表に示します。
エコシステム | アクション | GitHub によってメンテナンスされます |
---|---|---|
Go | Go の依存関係送信 | |
Gradle | Gradle の依存関係送信 | |
Maven | Maven 依存関係ツリーの依存関係送信 | |
製粉 | Mill の依存関係送信 | |
Scala | Sbt の依存関係送信 | |
NuGet とその他 | コンポーネント検出の依存関係の送信アクション |
注: コンポーネント検出依存関係の送信アクションの場合、サポートされているその他のエコシステムには、Vcpkg、Conan、Conda、Crates、NuGet などがあります。
たとえば、次の Go 依存関係送信ワークフローは、Go ビルド ターゲット (main
関数を含む Go ファイル) の依存関係を計算し、そのリストを 依存関係送信 API に送信します。
name: Go Dependency Submission
on:
push:
branches:
- main
# The API requires write permission on the repository to submit dependencies
permissions:
contents: write
# Environment variables to configure Go and Go modules. Customize as necessary
env:
GOPROXY: '' # A Go Proxy server to be used
GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
jobs:
go-action-detection:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: ">=1.18.0"
- name: Run snapshot action
uses: actions/go-dependency-submission@v1
with:
# Required: Define the repo path to the go.mod file used by the
# build target
go-mod-path: go-example/go.mod
#
# Optional. Define the repo path of a build target,
# a file with a `main()` function.
# If undefined, this action will collect all dependencies
# used by all build targets for the module. This may
# include Go dependencies used by tests and tooling.
go-build-target: go-example/cmd/octocat.go
独自のアクションを作成する
代わりに、ビルド時にプロジェクトの依存関係を送信する独自のアクションを記述することもできます。 次のようなワークフローにする必要があります。
- プロジェクトの依存関係のリストを生成します。
- 依存関係のリストを、依存関係送信 API で受け入れられるスナップショット形式に変換します。 形式について詳しくは、「依存関係送信用の REST API エンドポイント」の "リポジトリ スナップショットの作成" API エンドポイントの本文パラメーターをご覧ください。
- 適切な形式にした依存関係のリストを 依存関係送信 API に送信します。
GitHub Enterprise Server の Dependency Submission Toolkit は、依存関係送信 API に依存関係を送信するための独自の GitHub アクションを構築するのに役立つ TypeScript ライブラリです。 アクションの記述について詳しくは、「自動化の共有」をご覧ください。
ソフトウェア部品表 (SBOM) を生成して送信する
SBOM は、プロジェクトの依存関係と関連情報 (バージョンやパッケージ識別子など) の、機械で読み取り可能な正式なインベントリです。 SBOM は、次の方法でサプライ チェーンのリスクを軽減するのに役立ちます。
- リポジトリで使用される依存関係に関する透明性を提供する
- プロセスの早い段階で脆弱性を特定できるようにする
- コードベースに存在する可能性があるライセンス コンプライアンス、セキュリティ、または品質の issue に関する分析情報を提供する
- さまざまなデータ保護基準をより適切に遵守できるようにする
ソフトウェア部品表 (SBOM) を生成する
SBOM を生成する場合、次を使用できます。
- GitHub UI。 依存関係グラフの情報を使ってリポジトリの SBOM をエクスポートする方法について詳しくは、「リポジトリのソフトウェア部品表のエクスポート」をご覧ください。
- REST API は、 詳しくは、「ソフトウェア部品表 (SBOM) 用の REST API エンドポイント」を参照してください。
- GitHub Actions。 次のアクションでは、リポジトリの SBOM が生成され、ワークフロー成果物としてアタッチされます。これをダウンロードして他のアプリケーションで使用できます。 ワークフロー成果物のダウンロードについて詳しくは、「ワークフローの成果物をダウンロードする」をご覧ください。
アクション | 詳細 | GitHub によってメンテナンスされます |
---|---|---|
SBOM-generator-action | 依存関係グラフの情報を使って SPDX SBOM を生成します | |
Anchore SBOM アクション | Syft を使って、サポートされているエコシステムで SPDX 2.2 互換の SBOM を作成します | |
Microsoft による sbom-tool | 依存関係をスキャンし、SPDX 互換の SBOM を作成します |
ソフトウェア部品表 (SBOM) を 依存関係送信 API に送信する
既知の脆弱性を持つ依存関係の Dependabot alerts を受信するには、SBOM を 依存関係送信 API にアップロードして送信します。 SBOM を 依存関係送信 API に送信するには、次の表のいずれかのアクションを使用します。
Tip
SPDX 依存関係送信アクションとアンカー SBOM アクションは、SBOM の生成と、その 依存関係送信 API への送信の両方に使用できます。
アクション | 詳細 | GitHub によってメンテナンスされます |
---|---|---|
SPDX 依存関係送信アクション | Microsoft の SBOM ツールを使って、サポートされているエコシステムで SPDX 2.2 互換の SBOM を作成します | |
Anchore SBOM アクション | Syft を使って、サポートされているエコシステムで SPDX 2.2 互換の SBOM を作成します | |
SBOM 依存関係送信アクション | 依存関係送信 API に CycloneDX SBOM をアップロードします |
たとえば、次の SPDX 依存関係送信アクション ワークフローは、リポジトリの依存関係を計算し、SPDX 2.2 形式でエクスポート可能な SBOM を生成して、依存関係送信 API に送信します。
name: SBOM upload
on:
workflow_dispatch:
push:
branches: ["main"]
jobs:
SBOM-upload:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: write
steps:
- uses: actions/checkout@v4
- name: Generate SBOM
# generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
run: |
curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x $RUNNER_TEMP/sbom-tool
$RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
- uses: actions/upload-artifact@v3
with:
name: sbom
path: _manifest/spdx_2.2
- name: SBOM upload
uses: advanced-security/spdx-dependency-submission-action@5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e
with:
filePath: "_manifest/spdx_2.2/"