编写代码库安全建议的最佳实践

当您创建或编辑安全建议时，如果您使用标准格式指定生态系统、包名和受影响版本，则您提供的信息将更易于其他用户理解。

本文内容

任何对公共代码库具有管理员权限的用户都可以创建和编辑安全建议。

注意

如果您是安全研究人员，您应该直接联系维护人员，要求他们代表您在您未管理的代码库中创建安全建议或发布 CVE。但是，如果为代码库启用了私有漏洞报告，则您可以私下报告漏洞。有关更多信息，请参阅“私下报告安全漏洞”。

关于代码库的安全建议

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

我们建议您在编写代码库安全建议或对全局安全建议做出社区贡献时，使用 GitHub 安全建议数据库中使用的语法，尤其是版本格式。

如果您遵循 GitHub 安全建议数据库的语法，尤其是在定义受影响版本时

  • 当您发布代码库安全建议时，我们可以将您的建议添加到 GitHub 安全建议数据库中作为“GitHub 审查”建议，而无需请求更多信息。
  • Dependabot 将拥有准确识别受影响代码库并向其发送 Dependabot 警报以通知它们的信息。
  • 社区成员不太可能建议编辑您的建议以修复缺失或不正确的信息。

您可以使用“草稿安全建议”表单添加或编辑代码库安全建议。有关更多信息，请参阅“创建代码库安全建议”。

您可以使用“改进安全建议”表单建议对现有全局建议进行改进。有关更多信息，请参阅“编辑 GitHub 安全建议数据库中的安全建议”。

生态系统

您需要使用“生态系统”字段将建议分配给我们支持的生态系统之一。有关我们支持的生态系统的更多信息，请参阅“浏览 GitHub 安全建议数据库中的安全建议”。

Screenshot of the "Affected products" area of the security advisory form. The "Ecosystem" field is highlighted with a dark orange outline.

包名

我们建议您使用“包名”字段指定哪些包受影响，因为 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。

  • 空格的正确使用

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

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

    • 不要在>= 下限, <= 上限中的数字和逗号之间使用空格。

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

    注意

    下限限制

    • 是由于与 OSV 架构不兼容造成的。
    • 仅在您对 GitHub 安全漏洞数据库中现有安全公告提出建议时适用。

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

    Screenshot of the "Affected products" area of the security advisory form. A link, labeled "Add another affected product", is highlighted with a dark orange outline.

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

    • 如果未明确指定下限，则隐式值为> 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 平台允许通过字符串属性中的 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之后的所有内容解释为已修补。