编写仓库安全通报的最佳实践

关于仓库安全通告

仓库安全通告允许公共仓库的维护人员私下讨论和修复项目中的安全漏洞。在协作修复后，仓库维护人员可以发布安全通告，向项目社区公开披露安全漏洞。通过发布安全通告，仓库维护人员使其社区更容易更新包依赖项并研究安全漏洞的影响。有关更多信息，请参阅关于仓库安全通告。

我们建议您在编写仓库安全通告或向全球安全通告做出社区贡献时，使用 GitHub 咨询数据库中使用的语法，尤其是版本格式。

如果您遵循 GitHub 咨询数据库的语法，特别是在定义受影响的版本时

• 当您发布仓库通告时，我们可以将您的通告添加到 GitHub 咨询数据库中，作为“GitHub 审核”的通告，无需请求更多信息。
• Dependabot 将获得准确识别受影响仓库的信息，并向它们发送 Dependabot 警报进行通知。
• 社区成员建议修改您的通告以修复缺失或不正确信息的可能性会降低。

您可以使用草稿安全通告表单添加或编辑仓库通告。有关更多信息，请参阅创建仓库安全通告。

您可以使用改进安全通告表单对现有全球通告提出改进建议。有关更多信息，请参阅编辑 GitHub 咨询数据库中的安全通告。

生态系统

您需要使用生态系统字段将通告分配给我们支持的其中一个生态系统。有关我们支持的生态系统的更多信息，请参阅浏览 GitHub 咨询数据库中的安全通告。

包名称

我们建议您使用包名称字段指定受影响的包，因为 GitHub 咨询数据库中的“GitHub 审核”通告需要包信息。包信息对于仓库级别的安全通告是可选的，但尽早包含此信息可以简化您发布安全通告时的审核过程。

受影响的版本

我们建议您使用受影响的版本字段指定受影响的版本，因为 GitHub 咨询数据库中的“GitHub 审核”通告需要此信息。版本信息对于仓库级别的安全通告是可选的，但尽早包含此信息可以简化您发布安全通告时的审核过程。

有关 GitHub 咨询数据库的更多信息，请参阅https://github.com/github/advisory-database。

术语表

• 漏洞版本范围 (VVR)：容易受到特定软件缺陷影响的版本范围。
• 运算符：指示漏洞版本范围边界的任何符号。
• 开源漏洞格式 (OSV)：GitHub 咨询数据库数据力求兼容的格式。

版本语法

• 较小的数字是比较大的数字更早的版本。例如，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字段中将该较低版本标记为修复或已打补丁的版本，因为该版本小于漏洞版本。

支持的运算符

• >= 表示“大于或等于此版本”。

• > 表示“大于此版本”。

  警告

  尽管 GitHub 支持使用 > 运算符，但不建议使用此运算符，因为它不受 OSV 格式的支持。

• = 表示“等于此版本”。

• <= 表示“小于或等于此版本”。

• < 表示“小于此版本”。

在 GitHub 上指定受影响的版本

明确定义通告的受影响版本非常重要。GitHub 在受影响的版本字段中提供了几个选项，供您指定漏洞版本范围。

有关如何定义某些现有通告中受影响版本的示例，请参阅示例。

• 有效的受影响版本字符串由以下之一组成

  • 一个下限运算符序列。

  • 一个上限运算符序列。

  • 一个上限和下限运算符序列。下限必须在前，后跟逗号和单个空格，然后是上限。

  • 使用等号 (=) 运算符的特定版本序列。

  • 每个运算符序列必须指定为运算符、一个空格，然后是版本。有关有效运算符的更多信息，请参阅上面的支持的运算符。

  • 版本必须以数字开头，后跟任意数量的数字、字母、点、破折号或下划线（除了空格或逗号之外的任何字符）。有关版本格式的更多信息，请参阅上面的版本语法。

  注意

  受影响的版本字符串不能包含前导或尾随空格。

• 上限运算符可以是包含或不包含的，即分别为 <= 或 <。

• 下限运算符可以是包含或不包含的，即分别为 >= 或 >。但是，如果您发布仓库通告，并且我们将其升级为全球通告，则适用不同的规则：下限字符串只能是包含的，即 >=。排他的下限运算符 (>) 仅在版本为 0 时允许使用，例如 > 0。

• 正确使用空格

  • 在运算符和版本号之间使用空格。

  • 在 >= 或 <= 中不要使用空格。

  • 在 >= lower bound, <= upper bound 中的数字和逗号之间不要使用空格。

  • 在逗号和上限运算符之间使用空格。

  注意

  下限限制

  • 是由于与 OSV 架构不兼容。
  • 仅当您在 GitHub 咨询数据库中对现有通告提出建议时适用。

• 您不能在同一字段中指定多个受影响的版本范围，例如 > 2.0, < 2.3, > 3.0, < 3.2。要指定多个范围，您必须通过单击+ 添加另一个受影响的产品按钮，为每个范围创建一个新的受影响的产品部分。

  

• 如果受影响的版本范围仅包含单个上限或下限

  • 如果未明确指定下限，则隐式值始终为 > 0。
  • 如果未明确指定上限，则隐式值始终为无穷大。

仅对 VVR 设置上限

• 如果您只设置上限，请使用 <= 或 <。
• GitHub 咨询数据库使用 PyPA 数据库作为其数据源之一。但是，GitHub 不完全匹配 PyPA VVR 格式（PyPA 安全通告通常使用 >= 0, <= n 或 >= 0, < n 来指代仅具有上限的版本范围）。
• 在仅具有上限的范围中无需包含 >= 0。

仅对 VVR 设置下限

• 通告管理团队不建议仅对除恶意软件之外的任何通告设置下限。这是因为，如果发布了修复版本，修复版本的用户将继续收到不必要的 Dependabot 警报，直到通告手动更新。
• 对所有版本使用 >= 0
• > 0 通常不使用。

仅指定一个受影响的版本

• = n 用于单个受影响的版本
• 请记住，= 不会自动包含任何公共或私人预览版，仅包含指定的版本。

常见错误

• 避免使用 < n 漏洞版本范围，然后说 n+1 已打补丁。

  • < n 仅在 n 不存在漏洞时使用。
  • 在这种情况下，VVR 应该是 <= n 或 < n+1。

• 在描述带有字母的官方版本号的修复版本时，避免仅使用数字。假设您的软件有两个分支，linux 和 windows。当您发布 2.0.0-linux 和 2.0.0-windows 时，使用 < 2.0.0 作为漏洞版本会错误地将 2.0.0-linux 和 2.0.0-windows 标记为存在漏洞，因为版本逻辑将 -linux 和 -windows 解释为预发布版本。您需要将字母表中最早的分支 2.0.0-linux 标记为第一个打补丁的版本，以避免将 2.0.0-linux 和 2.0.0-windows 视为存在漏洞。

示例

包含多个 VVR 和多个运算符的通告

Etcd Gateway TLS 身份验证仅适用于在 DNS SRV 记录中检测到的端点 (GHSA-wr2v-9rpq-c35q) 具有两个漏洞版本范围

• < 3.3.23，它有一个没有下限的上限并使用 < 运算符。
• >= 3.4.0-rc.0, <= 3.4.9，它同时具有上限和下限，并使用 >= 和 <= 运算符。

显示预发布版本和常规版本之间关系的通告

XWiki Platform 允许通过字符串属性中的 XClass 名称进行 XSS (GHSA-wcg9-pgqv-xm5v) 具有四个漏洞版本范围

• >= 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 在漏洞版本范围内包含预发布版本。最后一个 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 更早的版本。

此漏洞的补丁于 2024 年 1 月 24 日发布，针对版本 16.0.0。有关更多信息，请参阅 xwiki/xwiki-platform 仓库中的提交 27eca84。MVN 仓库网站上的XWiki Platform Old Core页面显示，16.0.0-rc-1 于 2024 年 1 月 22 日发布，在修复添加到 XWiki 之前；16.0.0 于 2024 年 1 月 29 日发布，在修复提交之后。

版本号中包含分支名称的通告

Google Guava 在其版本发布中有两个分支，android 和 jre。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 之后的所有内容解释为已打补丁。