リポジトリ セキュリティ アドバイザリを作成するためのベスト プラクティス

この記事の内容

セキュリティ アドバイザリを作成または編集すると、標準形式を使用してエコシステム、パッケージ名、影響を受けるバージョンを指定する際に、あなたが提供する情報を他のユーザーが容易に理解できるようにすることができます。

廃止に関する注意: GitHub は、GitHub Advanced Security (GHAS) が有効になっていないプライベート リポジトリ のリポジトリ セキュリティ アドバイザリが廃止されます。 2024 年 2 月 15 日の時点で、GHAS が有効になっていないプライベート リポジトリにセキュリティ アドバイザリを作成できなくなります。

この廃止は、パブリック リポジトリの公開されたセキュリティ アドバイザリには影響しません。 また、GHAS が有効になっているプライベート リポジトリのセキュリティ アドバイザリにも影響しません。

GHAS が有効になっていないプライベート リポジトリに以前公開されていたアドバイザリは消去されます。 以前に公開されたアドバイザリを保存する必要がある場合は、GitHub REST API を使用してダウンロードできます。 詳しくは、REST API ドキュメントの「リポジトリ セキュリティ アドバイザリ」をご覧ください。

リポジトリに対する管理者権限があるユーザーなら誰でも、セキュリティアドバイザリを作成して編集することができます。

注: セキュリティ研究者の場合は、保守担当者に直接連絡して、自分が管理していないリポジトリで自分に代わってセキュリティ アドバイザリを作成または CVE を発行するように依頼する必要があります。 しかし、リポジトリに対してプライベート脆弱性レポートが有効になっている場合は、脆弱性を自分で "プライベートで" 報告できます。__ 詳しくは、「セキュリティの脆弱性を非公開で報告する」を参照してください。

リポジトリのセキュリティ アドバイザリについて

リポジトリ セキュリティ アドバイザリを使うと、リポジトリ保守管理者は、プロジェクト内でプライベートにセキュリティの脆弱性を検討して修正することができます。 共同で修正を行った後、リポジトリ保守担当者はセキュリティ アドバイザリを公開して、セキュリティの脆弱性をプロジェクトのコミュニティに開示することができます。 セキュリティ アドバイザリを公開することにより、リポジトリ保守担当者は、コミュニティがいっそう簡単にパッケージの依存関係を更新したり、セキュリティの脆弱性の影響を調べたりできるようにします。詳しくは、「リポジトリ セキュリティ アドバイザリについて」をご覧ください。

ベスト プラクティス

リポジトリ セキュリティ アドバイザリを作成するとき、またはグローバル セキュリティ アドバイザリに対するコミュニティへの貢献を行うときは、GitHub Advisory Databaseで使用されている構文 (特にバージョン形式) を使用することをお勧めします。

GitHub Advisory Database の構文に従う場合 (特に、影響を受けるバージョンを定義する場合) は次のようになります。

  • リポジトリ アドバイザリを発行すると、詳しい情報を要求しなくても、アドバイザリを GitHub Advisory Database に "GitHub-reviewed" アドバイザリとして追加できます。
  • Dependabot では、影響を受けるリポジトリを正確に識別し、それらに Dependabot alerts を送信して通知するための情報を取得します。
  • コミュニティ メンバーは、不足している情報や不正確な情報を修正するためのアドバイザリに対する編集を提案することが少なくなる可能性があります。

[下書きセキュリティ アドバイザリ] フォームを使用して、リポジトリ アドバイザリを追加または編集します。 詳しくは、「リポジトリ セキュリティ アドバイザリの作成」を参照してください。

[セキュリティ アドバイザリの改善] フォームを使用して、既存のグローバル アドバイザリの改善を提案します。 詳しくは、「GitHub Advisory Database でのセキュリティ アドバイザリの編集」を参照してください。

エコシステム

[エコシステム] フィールドを使用して、サポートされているエコシステムのいずれかにアドバイザリを割り当てる必要があります。 サポートされているエコシステムについて詳しくは、「GitHub Advisory Database でのセキュリティ アドバイザリの参照」をご覧ください。

セキュリティ アドバイザリ フォームの [影響を受ける製品] 領域のスクリーンショット。 [エコシステム] フィールドが、濃いオレンジ色の枠線で強調されています。

パッケージ名

[パッケージ名] フィールドを使用して、影響を受けるパッケージを指定することをお勧めします。これは、GitHub Advisory Database 内の "GitHub レビュー済み" アドバイザリにパッケージ情報が必要であるためです。 パッケージ情報はリポジトリ レベルのセキュリティ アドバイザリでは省略可能ですが、この情報を早期に含めると、セキュリティ アドバイザリを発行するときにレビュー プロセスが簡略化されます。

影響を受けるバージョン

[影響を受けるバージョン] フィールドを使用して、影響を受けるバージョンを指定することをお勧めします。GitHub Advisory Database 内の "GitHub レビュー済み" アドバイザリにこの情報が必要だからです。 バージョン情報はリポジトリ レベルのセキュリティ アドバイザリでは省略可能ですが、この情報を早期に含めると、セキュリティ アドバイザリを発行するときにレビュー プロセスが簡略化されます。

  • 影響を受ける有効なバージョン文字列は、次のいずれかで構成されます。

    • 下限演算子シーケンス。
    • 上限演算子シーケンス。
    • 上限と下限の両方の演算子シーケンス。
    • 等値 (=) 演算子を使用した特定のバージョン シーケンス。

  • 各演算子シーケンスは、演算子、1 つのスペース、そしてバージョンとして指定する必要があります。

    • 有効な演算子は =、<、<=、>、または >= です。
    • バージョンは数字で始めて、その後に任意の数の数字、文字、ドット、ダッシュ、またはアンダースコア (スペースまたはコンマ以外のもの) を続ける必要があります
    • 上限と下限の両方のシーケンスを指定する場合は、最初に下限を指定し、その後に 1 つのコンマと 1 つのスペースを続け、次に上限を指定する必要があります。

    注: 影響を受けるバージョン文字列には、先頭または末尾にスペースを含めることはできません。

  • 上限演算子は、包括的とすることも排他的とすることもできます (つまり、<= または <)。

  • 下限演算子は、包括的とすることも排他的とすることもできます (つまり、>= または >)。 ただし、リポジトリ アドバイザリを公開し、リポジトリ アドバイザリをグローバル アドバイザリに格上げする場合は、別のルールが適用されます。下限文字列は、包括的 (つまり、>=) とすることしかできません。排他的な下限演算子 (>) は、バージョンが 0 の場合にのみ許可されます (たとえば、> 0)。

    注: 下限の制限は、次のとおりです。

    • OSV (オープン ソースの脆弱性) スキーマとの互換性がないために発生します。
    • GitHub Advisory Database 内の既存のアドバイザリに対して提案を行う場合にのみ適用されます。

  • > 2.0, < 2.3, > 3.0, < 3.2 など、同じフィールドに、複数の影響を受けるバージョン範囲を指定することはできません。複数の範囲を指定するには、 [+ 影響を受ける製品を追加] ボタンをクリックして、各範囲に新しい [影響を受ける製品] セクションを作成する必要があります。

    セキュリティ アドバイザリ フォームの [影響を受ける製品] 領域のスクリーンショット。 [影響を受ける製品を追加] というラベルの付いたリンクが、濃いオレンジ色の枠線で強調されています。

  • 影響を受けるバージョン範囲に 1 つの上限または下限のみが含まれる場合:

    • 下限が明示的に指定されていない場合、暗黙的な値は常に > 0 です。
    • 上限が明示的に指定されていない場合、暗黙的な値は常に無限大になります。

GitHub Advisory Database の詳細については、「https://github.com/github/advisory-database」を参照してください。