innersource アドバイザリの管理

innersource アドバイザリがどのように機能し、誰が作成できるかの背景については、 AUTOTITLE を参照してください。

Prerequisites

Innersource アドバイザリは、アクティブな GitHub Code Security または GitHub Advanced Security ライセンスを持つ企業でのみ作成できます。

innersource アドバイザリの作成

InnerSource アドバイザリを作成するには:

enterprise_innersource_vulnerabilities権限を持つGitHub Appを作成してインストールします。
このアクセス許可に write アクセスできるアプリに関連付けられているトークンを生成します。
OSV 形式を使用して脆弱性の説明を作成し、REST API エンドポイントPOSTに/enterprises/{enterprise}/innersource-vulnerabilities/syncします。

これらの各手順について、以下で詳しく説明します。

手順 1: GitHub App を作成します

企業が所有するGitHub Appを登録し、enterprise_innersource_vulnerabilitiesアクセス権を持つread and writeアクセス許可を付与します。「GitHub アプリの登録」を参照してください。

アプリを登録したら、企業にインストールして、企業の代わりに動作できるようにします。

手順 2: アクセストークンを生成する

インストールアクセストークンを生成するために、 GitHub App インストールとして認証します。このトークンは、 enterprise_innersource_vulnerabilities アクセス許可を持ち、REST API に対する要求を認証するために使用されます。「GitHub アプリのインストールアクセストークンの生成」を参照してください。

OSV 形式を使用して脆弱性について説明し、インストールアクセストークンを使用して認証を行い、ペイロードをPOSTに/enterprises/{enterprise}/innersource-vulnerabilities/syncします。ペイロードは、影響を受けるパッケージと脆弱なバージョンの範囲を識別します。固定バージョンが使用可能な場合は、fixedがプル要求を開いて影響を受けるリポジトリを更新できるように、バージョン番号を含むDependabot フィールドを含めます。

アドバイザリスキーマの詳細については、セキュリティアドバイザリ用の REST API エンドポイントを参照してください。

innersource 勧告の利用

innersource アドバイザリを作成すると、影響を受けるコンポーネントを使用する企業内のリポジトリは、アラートと更新プログラムを受け取ります。

エンタープライズ内のリポジトリで Dependabot alerts と更新が有効になっていることを確認します。これは、セキュリティ構成を使用して大規模に適用できます。「カスタムセキュリティ構成を作成する」を参照してください。
依存リポジトリの Dependabot alerts ページで、影響を受けるコンポーネントに関する新しいアラートを確認します。アラートには個別の "Innersource" ラベルが付き、オープンソースアドバイザリアラートと区別されます。
アドバイザリペイロードに使用可能なパッケージと一致するバージョン番号を持つ fixed フィールドが含まれている場合、 Dependabot はパッケージマネージャーのマニフェストファイルを更新するプル要求も作成します。「Dependabot バージョンの更新の構成」を参照してください。

innersource アドバイザリの取り消し

影響を受けるコンポーネントの脆弱なバージョンが使用されていない場合、またはアドバイザリが置き換えられる場合は、そのコンポーネントを取り消すと役立ちます。

アドバイザリを取り消すには、作成手順と同じ REST API エンドポイントを使用しますが、ペイロードを調整して withdrawn キーを含めます。その値は、脆弱性がいつ引き出されたかを示す date-time フィールドです。

OSV 形式のサポートと制限事項

GitHub は、内部ソースの脆弱性同期 API を使用して、オープンソース脆弱性 (OSV) 形式の脆弱性を受け入れます。 GitHubは OSV 仕様との互換性を確保するために努力していますが、標準の OSV スキーマと、GitHubが必要とするものやサポートするものには違いがあります。

サポートされている OSV スキーマのバージョン

GitHub では、 ~> 1.0 と互換性のある OSV スキーマバージョン (つまり、 1.0.0 から 1.x.x) がサポートされます。推奨されるスキーマバージョンは 1.4.0。

影響を受けるエントリの書式設定

OSV 仕様では、1 つの affected エントリに、同じパッケージに対して複数の ranges と複数の versions を格納できます。 GitHub では、これらを個別のエントリに分割して内部的に正規化します。

| OSV 標準 | GitHub 動作 | |---|---| | 1 つの affected エントリに複数のエントリを含めることができます。 ranges | 承認された。各範囲は、個別の脆弱なバージョン範囲として処理されます。 | | 1 つの affected エントリに複数のエントリを含めることができます。 versions | 承認された。各バージョンは完全一致 (= x.y.z) として扱われ、個別の脆弱なバージョン範囲として処理されます。 | | 1 つの affected エントリには、ranges と versions を混在させることができます | 承認された。範囲とバージョンは、内部で個別のエントリに分割されます。 | | SEMVER範囲には、複数のintroduced/fixedペアを含めることができます | 承認された。 1 つの範囲内の複数の不整合な間隔 ( [1.0.0, 1.0.2) や [3.0.0, 3.2.5)など) がサポートされています。 |

サポートされている範囲の種類

範囲タイプ	Support
`ECOSYSTEM`
完全にサポートされています。
`introduced`、`fixed`、および`last_affected`イベントをサポートします。
`SEMVER`
完全にサポートされています。
`introduced`、`fixed`、および`last_affected`イベントをサポートします。
`last_affected` イベントは、`<=`上限比較子として解析されます。
`GIT`
サポートされていません。 Git コミットベースの範囲は処理されません。

メモ

ECOSYSTEM範囲では、範囲ごとに 1 つのintroducedと 1 つのfixed (またはlast_affected) イベントのみがサポートされます。同じパッケージに対して複数の不整合なバージョン範囲を表す必要がある場合は、個別の affected エントリまたは個別の範囲を使用します。

- SEMVER 範囲は、1 つの範囲内の複数の introduced/fixed ペア (たとえば、1 つのイベント配列の [1.0.0, 1.0.2) と [3.0.0, 3.2.5) ) をサポートします。

fixedとlast_affected同じ範囲に一緒に表示することはできません。 fixedを優先して、いずれか一方を使用します。

必須フィールド

OSV 仕様では、複数のフィールドは省略可能として扱いますが、 GitHub には必須です。これらのフィールドがない要求は、 422 エラーで拒否されます。

| フィールド | OSV 仕様 | GitHub 要件 | |---|---|---| | id | 必須 | 必須。脆弱性の外部識別子として使用されます。 | | severity 配列 | Optional | 必須。 空でないCVSS_V3文字列 (例: CVSS_V4) を持つ少なくとも 1 つのscoreまたはCVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:Hエントリを含む必要があります。有効な CVSS 項目のない要求は拒否されます。 | | affected[].package.ecosystem | 必須 | サポートされているエコシステムである必要があります | | affected[].ranges または affected[].versions | 少なくとも 1 つ必要 | アラートの照合には、少なくとも 1 つの範囲またはバージョンが存在する必要があります |

自動派生を含む省略可能なフィールド

フィールド	Behavior
`database_specific.severity`	指定されている場合は、定性的重要度ラベル (`critical`、 `high`、 `moderate`、または `low`) として使用されます。存在しない場合、重大度は CVSS ベクタースコアから自動的に派生します。
`summary`	存在しない場合は、 `id` フィールドにフォールバックします。
`details`	存在しない場合は、 `summary` または `id`にフォールバックします。

サポートされている重大度の種類

重大度の種類	Support
`CVSS_V3`
サポートされています。有効な CVSS 3.1 ベクター文字列である必要があります。
`CVSS_V4`
サポートされています。有効な CVSS 4.0 ベクター文字列である必要があります。
その他の型
サポートされていません。解析エラーが発生します。

サポートされている参照型

参照の種類	Support
`ADVISORY`	サポートされている
`WEB`	サポートされている
`FIX`	サポートされている
`ARTICLE`	サポートされている
`REPORT`	サポートされている
`PACKAGE`	対応済み (ソースコード内の位置に対応付けられています)
`EVIDENCE`	サポートされています (処理中は無視されます)
`DETECTION`
サポートされていません。処理中に削除されます。

エイリアスのサポート

エイリアスの形式	Support
`CVE-YYYY-NNNNN`
サポートされています。 CVE 識別子として抽出されます。最初の CVE エイリアスのみが使用されます。
その他の形式 (GHSA、PYSEC など)
サポートされていません。処理中に削除されます。

メモ

脆弱性 id フィールドが GHSA-で始まる場合は、GHSA 識別子として認識されます。ただし、 aliases 配列内の GHSA エントリは削除され、保持されません。

フィールドサイズの制約

OSV 仕様では、どのフィールドの最大文字列長も定義されません。すべての文字列は無制限です。ただし、 GitHub では、内部データベーススキーマに基づいてフィールドサイズの制限が適用されます。これらの制限は、独自の互換性のあるスキーマを維持する GitHub Enterprise Serverとの同期を解除しないと緩和できません。

これらの制限を超える送信は、制限を超えたフィールドと実際の長さ (例: affected[0].first_patched_version is 63 characters (max 50)) を示す説明的な 422 エラーで拒否されます。

| OSV フィールド | にマップされます | OSV 標準の制限 | GitHub 制限 | 単位 | |---|---|---|---|---| | summary | vulnerabilities.summary | 制限なし (推奨≤ 120 文字) | 1,024 | バイト | | id | vulnerabilities.external_id | 制限なし | 2,048 | 文字 | | aliases[] (CVE エントリ) | vulnerabilities.cve_id | 制限なし | 20 | 文字 | | severity[].score (CVSS v3) | vulnerabilities.cvss_v3 | 制限なし | 255 | バイト | | severity[].score (CVSS v4) | vulnerabilities.cvss_v4 | 制限なし | 255 | 文字 | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | 制限なし | 20 | 文字 | | affected[].package.name | vulnerable_version_ranges.affects | 制限なし | 255 | 文字 | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | 制限なし | 50 | 文字 | | 計算された脆弱なバージョン範囲 | vulnerable_version_ranges.requirements | 制限なし | 65,535 | バイト |

メモ

50 文字の fixed_in (最初の修正プログラムが適用されたバージョン) の制限は、最も一般的に見られる制約です。一部のエコシステムでは、この制限を超える長いプレリリースバージョン文字列 ( 1.0.0-alpha.gamma.delta.epsilon.zeta.eta.theta など) が使用されます。

varchar 列は文字数で検証されます。 varbinary 列と text 列はバイトサイズによって検証されます (マルチバイト UTF-8 文字に関連)。

これらの制限は、 GitHub Enterprise Server スキーマの互換性によって制約されます。 GHES の変更を一致させることなく GitHub の列を拡大すると、環境間でアドバイザリ同期エラーが発生します。

エコシステムマッピング

GitHub は、OSV エコシステム名を内部エコシステム識別子にマップします。次のエコシステムがサポートされています。

| OSV エコシステム | GitHub エコシステム | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Maven | | NuGet | NuGet | | Packagist | Composer | | Go | Go | | crates.io | Rust | | Hex | Erlang | | Pub | Pub | | SwiftURL | Swift | | GitHub Actions | GitHub Actions |

例: アラート生成のための最小 OSV ペイロード

GitHubがDependabotアラートを作成するために必要なすべてのフィールドを含む最小 OSV ペイロードを次に示します。

{
  "schema_version": "1.4.0",
  "id": "EXAMPLE-2024-001",
  "modified": "2024-01-15T10:00:00Z",
  "summary": "Example vulnerability in example-package",
  "details": "A detailed description of the vulnerability.",
  "aliases": ["CVE-2024-12345"],
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    }
  ],
  "affected": [
    {
      "package": {
        "ecosystem": "npm",
        "name": "example-package"
      },
      "ranges": [
        {
          "type": "ECOSYSTEM",
          "events": [
            { "introduced": "0" },
            { "fixed": "1.2.3" }
          ]
        }
      ]
    }
  ],
  "database_specific": {
    "severity": "Critical"
  },
  "references": [
    { "type": "ADVISORY", "url": "https://example.com/advisory" }
  ],
  "published": "2024-01-15T10:00:00Z"
}

既知の制限

要求あたり最大 100 個の脆弱性。 同期 API は、1 つの要求で最大 100 個の脆弱性を受け入れます。
GIT範囲の種類がありません。 Git コミットベースのバージョン範囲はサポートされていません。
ECOSYSTEM 範囲ごとに単一のイベントタイプ。 各 ECOSYSTEM 範囲では、1 つの introduced と 1 つの上限イベント (fixed または last_affected) がサポートされます。 1 つのintroduced範囲内の複数の/fixed``ECOSYSTEM ペアはサポートされていません。代わりに、個別の範囲または個別のaffectedエントリを使用してください。 (この制限は、複数のイベントペアをサポートする SEMVER 範囲には適用されません)。
fixed と last_affected は相互に排他的です。 1 つの範囲に fixed イベントと last_affected イベントの両方を含めることはできません。いずれかを使用します。
GHES sync の互換性。 フィールドサイズの制限 (50 文字で fixed_in など) は、スキーマの互換性要件 GitHub Enterprise Server 制約されます。

この記事で