编写存储库安全公告的最佳做法

对公共存储库有管理员权限的任何人都可以创建和编辑安全公告。

有关存储库的安全公告

使用存储库安全公告，公共存储库的维护人员可私下讨论和修复项目中的安全漏洞。 协作得到修补程序后，存储库维护人员可发布安全通知，向项目社区公开安全漏洞。 通过发布安全通知，存储库维护人员可使其社区更轻松地更新包依赖项并对安全漏洞的影响进行调查。 有关详细信息，请参阅 关于存储库安全公告。

编写存储库安全公告或为全局安全公告做出社区贡献时，建议采用 GitHub Advisory Database 中使用的语法，尤其是版本格式设置。

如果按照 GitHub Advisory Database 的语法，尤其是对受影响的版本进行定义时：

• 发布存储库公告时，可以将公告添加到 GitHub Advisory Database 作为“GitHub-已审核”公告，而无需请求更多信息。
• 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)：易受特定软件 bug 攻击的版本范围。
• 运算符：表示易受攻击版本范围的边界的任何符号。
• 开放源代码漏洞格式 (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 在“受影响的版本****”字段中提供了多个选项，方便你指定易受攻击的版本范围。

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

• 有效的受影响的版本字符串包含以下内容之一：

  • 下限运算符序列。

  • 上限运算符序列。

  • 上限运算符序列和下限运算符序列。 下限必须先出现，其后加上逗号和一个空格，然后是上限。

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

  • 每个运算符序列都必须指定为运算符、单个空格，以及版本。 有关有效运算符的详细信息，请参阅上文支持的运算符。

  • 版本必须以数字开头，其后为任意数量的数字、字母、点、短破折号或下划线字符（空格或逗号以外的任何内容）。 有关版本格式的详细信息，请参阅上文的版本语法。

  Note

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

• 上限运算符可以是非独占运算符或独占运算符，即分别是 <= 或 <。

• 下限运算符可以是非独占运算符或独占运算符，即分别是 >= 或 >。 但是，如果你发布存储库公告，而我们将你的存储库公告升级为全局公告后，则会应用不同的规则：下限运算符只能是非独占的，即 >=。仅当版本为 0 时才能是独占下限运算符 (>)，如 > 0。

• 正确使用空格

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

  • 请勿在 >= 或 <= 中使用空格。

  • 在 >= lower bound, <= upper bound 中，请勿在数字和逗号之间使用空格。

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

  Note

  下限限制：

  • 是因为与 OSV 架构不兼容。
  • 仅在对 GitHub Advisory Database 中的现有公告提出建议时才适用。

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

  

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

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

仅在 VVR 上设置上限

• 如果仅设置上限，请使用 <= 或 <。
• GitHub Advisory Database 会使用 PyPA 数据库作为数据源之一。 但是，GitHub 与 PyPA VVR 格式不完全匹配（PyPa 安全公告经常使用 >= 0, <= n 或 >= 0, < n 来指代只有上限的版本范围）。
• 只有上限的范围无需包含 >= 0。

仅在 VVR 上设置下限

• 咨询策展团队不建议仅在恶意软件以外的任何咨询设置下限。 这是因为，如果已发布修正版本，则修正版本的用户将继续接收不必要的 Dependabot alerts，直到手动更新公告。
• 针对所有版本，都使用 >= 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 被视为易受攻击。

示例

为多个 VR 和多个运算符提供咨询

Etcd 网关 TLS 身份验证仅适用于 DNS SRV 记录中检测到的终结点 (GHSA-wr2v-9rpq-c35q)，具有两个易受攻击的版本范围：

• < 3.3.23，有上限而无下限，并使用 < 运算符。
• >= 3.4.0-rc.0, <= 3.4.9，有上限而无下限，并使用 >= 和 <= 运算符。

显示预发行版和常规版本之间关系的公告

XWiki 平台允许通过字符串属性中 XClass 名称 (GHSA-wcg9-pgqv-xm5v) 的 XSS 具有四个易受攻击的版本范围：

• >= 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 平台旧核心页面显示，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 之后的所有内容解释为已修补。