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

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

この機能を使用できるユーザーについて

リポジトリの所有者、組織の所有者、セキュリティ マネージャー、および 管理者 ロールを持つユーザー

この記事の内容

Note

セキュリティ研究者の場合は、保守担当者に直接連絡して、自分が管理していないリポジトリで自分に代わってセキュリティ アドバイザリを作成または 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 レビュー済み" アドバイザリにこの情報が必要だからです。 バージョン情報はリポジトリ レベルのセキュリティ アドバイザリでは省略可能ですが、この情報を早期に含めると、セキュリティ アドバイザリを発行するときにレビュー プロセスが簡略化されます。

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

用語集

  • 脆弱なバージョン範囲 (VVR): 特定のソフトウェア バグに対して脆弱なバージョンの範囲。
  • 演算子: 脆弱なバージョン範囲の境界を示す記号。
  • オープンソース脆弱性形式 (OSV): GitHub Advisory Database データが互換性を持つよう努める形式。

バージョンの構文

  • 数値が小さいほど古いバージョンで、数値が大きいほど新しいバージョンです。 たとえば、1.0.0 は 2.0.0 よりも低いバージョンです
  • アルファベットの並び順が先の文字ほど古いバージョンで、後の文字ほど新しいバージョンです。 たとえば、2.0.0-a は 2.0.0-b よりも古いバージョンです。
  • 数字の後に文字が付くとプレリリースの一部と見なされるため、数字の後に文字が付いているバージョンは、数字だけで文字のないバージョン番号よりも古いバージョンです。 たとえば、2.0.0-alpha、2.0.0-beta、2.0.0-rc は 2.0.0 よりも古いバージョンです。
  • 最終版は、VVR の最大数より小さくすることはできません。 たとえば、脆弱なバージョンがリリースされ、保守担当者がダウングレードを推奨したとします。 保守管理者は、Fixed フィールドでその下位バージョンを固定バージョンまたはパッチ適用バージョンとしてラベル付けすることはできません。これは、その下位バージョンが脆弱なバージョンよりも小さいためです。

サポートされている演算子

  • "このバージョン以上" の場合、>=。

  • "このバージョンより大きい" 場合、>。

    Warning

    GitHub は > 演算子の使用をサポートしていますが、OSV 形式ではサポートされていないため、この演算子の使用はお勧めしません。

  • "このバージョンと等しい" 場合、=。

  • "このバージョン以下" の場合、<=。

  • "このバージョンより小さい" 場合、<。

GitHub で影響を受けるバージョンを指定する

アドバイザリでは、影響を受けるバージョンを明確に定義することが重要です。 GitHub では、[影響を受けるバージョン] フィールドに、脆弱なバージョン範囲を指定するためのいくつかのオプションが用意されています。

影響を受けるバージョンが一部の既存のアドバイザリでどのように定義されているかを示す例については、「例」を参照してください。

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

    • 下限演算子シーケンス。

    • 上限演算子シーケンス。

    • 上限と下限の両方の演算子シーケンス。 最初に下限を指定し、その後に 1 つのコンマと 1 つのスペースを続け、次に上限を指定する必要があります。

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

    • 各演算子シーケンスは、演算子、1 つのスペース、そしてバージョンとして指定する必要があります。 有効な演算子の詳細については、上記の「サポートされている演算子」を参照してください。

    • バージョンは数字で始める必要があり、その後に任意の数の数字、文字、ドット、ダッシュ、またはアンダースコア (スペースまたはコンマ以外のもの) を続けます。 バージョンの書式設定の詳細については、上記の「バージョンの構文」を参照してください。

    Note

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

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

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

  • スペースの適切な使用

    • 演算子とバージョン番号の間にスペースを使用します。

    • >= や <= の中にスペースを使用しないでください。

    • >= lower bound, <= upper bound では、数値とコンマの間にスペースを使用しないでください。

    • コンマと上限演算子の間にスペースを使用します。

    Note

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

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

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

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

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

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

VVR で上限のみを設定する

  • 上限のみを設定する場合は、<= または < を使用します。
  • GitHub Advisory Database は、PyPA データベースをデータ ソースの 1 つとして使用します。 ただし、GitHub は PyPA VVR 形式と正確には一致しません (PyPa セキュリティ アドバイザリでは、多くの場合、>= 0, <= n または >= 0, < n を使用して、上限のみを持つバージョン範囲を参照します)。
  • 上限のみを持つ範囲に >= 0 を含める必要はありません。

VVR で下限のみを設定する

  • アドバイザリ キュレーション チームは、マルウェア以外のアドバイザリに下限のみを設定することはお勧めしません。 これは、最終版がリリースされている場合、アドバイザリが手動で更新されるまで、最終版のユーザーは不要な Dependabot alerts を受け取り続けるためです。
  • すべてのバージョンで >= 0 を使用する
  • > 0 は一般に使用されません。

影響を受けるバージョンを 1 つだけ指定する

  • 影響を受ける 1 つのバージョンの場合、= n。
  • = には、指定されたバージョン_のみ_が含まれ、公開用またはプライベート プレビューは自動的には含まれないことに注意してください。

一般的なエラー

  • < n という脆弱なバージョン範囲を使用した後で、n+1 にパッチを適用するというのは避けてください。

    • < n は、n が脆弱でない場合にしか使用できません。
    • この場合、VVR の値を <= n または < n+1 にする必要があります。

  • 正式なバージョン番号に文字が含まれる最終版を記述する場合は、数字のみを使用しないでください。 ソフトウェアに linux と windows の 2 つのブランチがあるとします。 2.0.0-linux と 2.0.0-windows をリリースする際に、脆弱なバージョンとして < 2.0.0 を使用すると、バージョン ロジックによって -linux と -windows がプレリリースと解釈されるため、2.0.0-linux と 2.0.0-windows は脆弱とマークされます。 2.0.0-linux や 2.0.0-windows が脆弱であると見なされないように、最初のパッチ バージョンとして、アルファベット順で最も早いブランチである 2.0.0-linux をマークする必要があります。

例

複数の VVR と複数の演算子を使用したアドバイザリ

「Etcd Gateway TLS 認証は、DNS SRV レコードで検出されたエンドポイントにのみ適用されます (GHSA-wr2v-9rpq-c35q)」には、次の 2 つの脆弱なバージョン範囲があります。

  • < 3.3.23。下限がなく上限があり、< 演算子を使用します。
  • >= 3.4.0-rc.0, <= 3.4.9。上限と下限があり、>= 演算子と <= 演算子を使用します。

プレリリースと通常リリースの関係を示すアドバイザリ

「XWiki Platform では、文字列プロパティの XClass 名を使用して XSS を使用できます (GHSA-wcg9-pgqv-xm5v)」には、次の 4 つの脆弱なバージョン範囲があります。

  • >= 1.1.2, < 14.10.21
  • >= 15.0-rc-1, < 15.5.5
  • >= 15.6-rc-1, < 15.10.6
  • = 16.0.0-rc-1

これらの VVR のうち 3 つには、脆弱なバージョン範囲のプレリリースが含まれています。 最後の VVR (= 16.0.0-rc-1) では、16.0.0-rc-1 のみが脆弱であるのに対し、その後の通常のリリース (16.0.0) は脆弱ではないことを示しています。 このロジックでは、16.0.0-rc-1 と 16.0.0 は別のバージョンで、16.0.0-rc-1 は 16.0.0 よりも前のリリースと見なされます。

この脆弱性へのパッチは、バージョン 16.0.0 に対して 2024 年 1 月 24 日に公開されました。 詳細については、xwiki/xwiki-platform リポジトリの commit 27eca84 を参照してください。 MVN リポジトリ サイトの XWiki Platform Old Core ページには、修正プログラムが XWiki に追加される前の 2024 年 1 月 22 日に 16.0.0-rc-1 が公開され、修正プログラムがコミットされた後、16.0.0 が 2024 年 1 月 29 日に公開されたことが示されています。

バージョン番号にブランチ名を含むアドバイザリ

Google Guava のバージョン リリースには、android と jre の 2 つのブランチがあります。 「Guava は、一時ディレクトリのセキュリティで保護されていない使用に対して脆弱です (GHSA-7g45-4rm6-3mm3)」および「Guava の情報漏えい (GHSA-5mg8-w23w-74h3)」は、Guava に影響を与える脆弱性に関するアドバイザリです。 どちらのアドバイザリでもパッチ適用バージョンとして 32.0.0-android が設定されています。

  • バージョン範囲ロジックは 32.0.0 の後の文字をプレリリースとして解釈するため、パッチ適用バージョンを 32.0.0 に設定すると、32.0.0-android と 32.0.0-jre の両方が誤って脆弱とマークされます。
  • バージョン範囲ロジックはアルファベットの後の文字をアルファベットの前の文字よりも新しいバージョンとして解釈するため、パッチ適用バージョンを 32.0.0-jre に設定すると、32.0.0-android は誤って脆弱とマークされます。

32.0.0-android と 32.0.0-jre の両方にパッチが適用されていることを示す最善の方法は、パッチ適用バージョンとして 32.0.0-android を使用することです。そうすると、ロジックは、アルファベットの 32.0.0-android より後のものはすべてパッチ適用済みと解釈します。