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

在创建或编辑安全公告时，使用标准格式指定生态系统、包名称和受影响的版本后，更易于其他用户理解你提供的信息。

> \[!NOTE]
> 如果你是安全研究人员，应直接联系维护人员，要求他们创建安全通告，或在你不管理的存储库中代表你发布 CVE。 但如果为存储库启用了私人漏洞报告，则可以自行“私下”\_\_ 报告漏洞。 有关详细信息，请参阅“[私下报告安全漏洞](/zh/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)”。

## 有关存储库的安全公告

使用存储库安全公告，公共存储库的维护人员可私下讨论和修复项目中的安全漏洞。 协作得到修补程序后，存储库维护人员可发布安全通知，向项目社区公开安全漏洞。 通过发布安全通知，存储库维护人员可使其社区更轻松地更新包依赖项并对安全漏洞的影响进行调查。 了解更多信息，请参阅 [存储库安全公告](/zh/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories)。

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

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

* 发布存储库公告时，可以将公告添加到 GitHub Advisory Database 作为“GitHub-已审核”公告，而无需请求更多信息。
* Dependabot 将提供信息来准确识别受影响的存储库，并向其发送 Dependabot alerts 以通知它们。
* 社区成员不太可能建议通过编辑公告来修复缺失或不正确的信息。

使用“草稿安全公告”表单添加或编辑存储库公告。 有关详细信息，请参阅“[创建存储库安全公告](/zh/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory)”。

您可以使用“改进安全公告”表单提出对现有全球公告的改进建议。 有关详细信息，请参阅“[在 GitHub Advisory Database 中编辑安全公告](/zh/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database)”。

## 生态系统

需要使用“生态系统”字段将公告分配给受支持的生态系统之一。 有关我们所支持的生态系统的详细信息，请参阅 [在 GitHub Advisory Database 中浏览安全公告](/zh/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database#github-reviewed-advisories)。

![安全公告表单的“受影响产品”区域的屏幕截图。 “生态系统”字段以深橙色边框突出显示。](/assets/images/help/security/security-advisory-ecosystem.png)

## 包名称

我们建议使用“**包名称**”字段来指定受影响的软件包，因为该信息是 GitHub 中“GitHub Advisory Database-已审核”公告所必需的。 包信息对于存储库级安全公告是可选的，但在发布安全公告时尽早包含此信息可简化审核过程。

## 受影响版本

我们建议使用“**受影响版本**”字段来指定受影响的版本，因为该信息是 GitHub 中“GitHub Advisory Database-已审核”公告所必需的。 版本信息对于存储库级安全公告是可选的，但在发布安全公告时尽早包含此信息可简化审核过程。

有关 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 在“受影响的版本\*\*\*\*”字段中提供了多个选项，方便你指定易受攻击的版本范围。

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

* 有效的受影响的版本字符串包含以下内容之一：
  * 下限运算符序列。

  * 上限运算符序列。

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

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

  * 每个运算符序列都必须指定为运算符、单个空格，以及版本。 有关有效运算符的详细信息，请参阅上文[支持的运算符](#supported-operators)。

  * 版本必须以数字开头，其后为任意数量的数字、字母、点、短破折号或下划线字符（空格或逗号以外的任何内容）。 有关版本格式的详细信息，请参阅上文的[版本语法](#version-syntax)。
  > \[!NOTE]
  > 受影响的版本字符串不能包含前导空格或尾随空格。

* 上限运算符可以是包含或不包含，即分别是`<=`或`<`。

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

* 正确使用空格
  * 在运算符与版本号之间使用空格。

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

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

  * 在逗号和上限运算符之间使用空格。
  > \[!NOTE]
  > 下限限制：
  >
  > * 是因为与 OSV 架构不兼容。
  > * 仅在对 GitHub Advisory Database 中的现有公告提出建议时才适用。

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

  ![安全公告表单的“受影响产品”区域的屏幕截图。 “添加另一个受影响的产品”链接以深橙色边框显示。](/assets/images/help/security/security-advisory-add-another-affected-product.png)

* 如果受影响的版本范围仅包含单个上限或下限：
  * 如果未显式指定下限，那么隐式值始终为 `> 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` 被视为易受攻击。

### 例子

#### 具有多个 VVR 和多个运算符的公告

[Etcd Gateway TLS 身份验证仅适用于在 DNS SRV 记录中检测到的终结点（GHSA-wr2v-9rpq-c35q）](https://github.com/advisories/GHSA-wr2v-9rpq-c35q)，其具有两个易受攻击的版本范围：

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

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

[XWiki 平台允许通过字符串属性中的 XClass 名称进行 XSS (GHSA-wcg9-pgqv-xm5v) ](https://github.com/advisories/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。 有关更多信息，请参阅 [](https://github.com/xwiki/xwiki-platform/commit/27eca8423fc1ad177518077a733076821268509c) 存储库中的`xwiki/xwiki-platform `。 MVN 存储库站点中的 [XWiki 平台旧核心](https://mvnrepository.com/artifact/org.xwiki.platform/xwiki-platform-oldcore)页面显示，`16.0.0-rc-1` 于 2024 年 1 月 22 日发布，即在向 XWiki 添加修补程序之前，而 `16.0.0` 于 2024 年 1 月 29 日发布，即在提交修补程序之后。

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

[Google Guava](https://mvnrepository.com/artifact/com.google.guava/guava) 在其版本发布中有两个分支，即 `android` 和 `jre`。
[Guava 存在临时目录不安全使用漏洞 (GHSA-7g45-4rm6-3mm3)](https://github.com/advisories/GHSA-7g45-4rm6-3mm3) 以及 [Guava 中的信息泄漏 (GHSA-5mg8-w23w-74h3)](https://github.com/advisories/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` 之后的所有内容解释为已修补。