有关内部资源公告的工作原理以及谁可以创建它们的背景信息，请参阅 Innersource advisories。
先决条件
内部资源公告只能在具有活动 GitHub Code Security 或 GitHub Advanced Security 许可证的企业中创建。
创建内部资源公告
若要创建内部资源公告，请执行以下操作：
- 使用GitHub App权限创建并安装
enterprise_innersource_vulnerabilities。 - 生成与可
write访问此权限的应用关联的令牌。 - 使用 OSV 格式创建漏洞的说明，并将其
POST添加到 REST API 终结点/enterprises/{enterprise}/innersource-vulnerabilities/sync。
下面更详细地介绍了上述每个步骤。
步骤 1：创建 GitHub App
注册企业拥有的帐户 GitHub App ，并向其 enterprise_innersource_vulnerabilities 授予访问权限 read and write 。 请参阅“注册GitHub应用”。
注册应用后，将其安装在企业上，以便它可以代表企业执行操作。
步骤 2：生成访问令牌
以 GitHub App 安装的身份进行身份验证，以生成安装访问令牌。 此令牌具有 enterprise_innersource_vulnerabilities 权限，用于对对 REST API 的请求进行身份验证。 请参阅“为 GitHub 应用生成安装访问令牌”。
步骤 3：上传公告说明
使用 OSV 格式描述该漏洞，然后使用安装访问令牌进行身份验证，将有效负载 POST 到 /enterprises/{enterprise}/innersource-vulnerabilities/sync。 该负载标明了受影响的软件包及存在漏洞的版本范围。 如果有可用的修复版本，请加入一个包含该版本号的 fixed 字段，以便 Dependabot 可以发起拉取请求来更新受影响的存储库。
有关咨询架构的详细信息，请参阅 适用于安全公告的 REST API 终结点。
使用内部开源建议
创建内部资源公告后，使用受影响组件的企业中的存储库将收到警报和更新。
- 确保企业中的存储库已启用 Dependabot alerts 和更新。 可以使用安全配置大规模强制实施此配置。 请参阅“删除自定义安全配置”。
- 查看从属存储库 Dependabot alerts 的页面，获取有关受影响组件的新警报。 该警报会带有明确的“Innersource”标签，以区别于开源咨询警报。
- 如果您的安全通告载荷中包含一个
fixed字段，且其中的版本号与某个可用软件包匹配，Dependabot 还会创建一个拉取请求，以更新包管理器的清单文件。 请参阅“配置 Dependabot 版本更新”。
撤回内部开源公告
如果受影响组件中存在漏洞的版本已不再使用，或者该公告已被新公告取代，那么撤回该公告会很有帮助。
若要撤回公告，请使用与创建步骤相同的 REST API 终结点，但请调整有效负载以包含 withdrawn 密钥，其值为指示 date-time 何时撤回漏洞的字段。
OSV 格式支持和限制
GitHub 通过内部开源漏洞同步 API 接收采用 Open Source Vulnerability（OSV）格式的漏洞信息。 虽然 GitHub 努力实现与 OSV 规范的兼容性，但标准 OSV 架构与需要或支持的内容 GitHub 之间存在差异。
支持的 OSV 架构版本
GitHub 支持与 ~> 1.0 （即 1.0.0 通过 1.x.x） 兼容的 OSV 架构版本。 建议的架构版本为 1.4.0.
受影响的条目格式
OSV 规范允许单个 affected 条目包含同一包的多个 ranges 和多个 versions。
GitHub 通过将它们拆分为单独的条目，在内部规范化这些项：
| OSV 标准 |
GitHub 行为 |
|---|---|
| 单个 affected 条目可以包含多个项 ranges | Accepted. 每个范围都作为单独的易受攻击的版本范围进行处理。 |
| 单个 affected 条目可以包含多个项 versions | Accepted. 每个版本被视为完全匹配（= x.y.z）并作为单独的易受攻击的版本范围进行处理。 |
| 单个 affected 条目可以混合 ranges 和 versions | Accepted. 范围和版本在内部拆分为单独的条目。 |
| 范围SEMVER可以包含多个introduced/fixed对 | Accepted. 支持在单个范围内包含多个不相交的区间（例如 [1.0.0, 1.0.2) 和 [3.0.0, 3.2.5)）。 |
支持的范围类型
| 范围类型 | 支持 |
|---|---|
ECOSYSTEM | |
完全支持。 支持introduced和fixed``last_affected事件。 | |
SEMVER | |
完全支持。 支持introduced和fixed``last_affected事件。 事件 last_affected 被分析为 <= 上限比较器。 | |
GIT | |
| 不支持。 不会处理基于 Git 提交的范围。 |
注意
- 对于
ECOSYSTEM范围，每个范围仅支持一个introduced事件和一个fixed（或last_affected）事件。 如果需要表示同一包的多个不同版本范围，请使用单独的affected条目或单独的范围。
SEMVER 范围支持在单个范围内包含多组 introduced/fixed 对（例如，[1.0.0, 1.0.2) 和 [3.0.0, 3.2.5) 位于同一个 events 数组中）。
-
fixed并且last_affected不能在同一范围内一起显示 。 使用一个或另一个，并优先使用fixed。
必填字段
OSV 规范将多个字段视为可选字段，但 GitHub 需要这些字段。 缺少这些字段的请求 被拒绝，出现 422 错误。
| 领域 | OSV 规范 |
GitHub 要求 |
|---|---|---|
| id | 必需 | 必填。 用作漏洞的外部标识符。 |
| severity 数组 | Optional |
必填。 必须至少包含一个 CVSS_V3 或 CVSS_V4 包含非空 score 字符串（例如， CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H） 的条目。 缺少有效 CVSS 条目的请求将被拒绝。 |
| affected[].package.ecosystem | 必需 | 必须是 受支持的生态系统 |
| affected[].ranges 或 affected[].versions | 至少需要一个 | 至少必须存在一个范围或版本才能进行警报匹配 |
支持自动推导的可选字段
| 领域 | Behavior |
|---|---|
database_specific.severity | 如果提供，则用作定性严重性标签（critical、high或moderate``low）。 如果未提供，严重程度将根据 CVSS 向量评分自动得出。 |
summary | 如果缺失，则回退到 id 字段。 |
details | 如果未提供，则回退到 summary 或 id。 |
支持的严重性类型
| 严重性类型 | 支持 |
|---|---|
CVSS_V3 | |
| 支持。 必须是有效的 CVSS 3.1 向量字符串。 | |
CVSS_V4 | |
| 支持。 必须是有效的 CVSS 4.0 向量字符串。 | |
| 其他类型 | |
| 不支持。 将导致分析错误。 |
支持的引用类型
| 引用类型 | 支持 |
|---|---|
ADVISORY | 支持 |
WEB | 支持 |
FIX | 支持 |
ARTICLE | 支持 |
REPORT | 支持 |
PACKAGE | 受支持（可映射到源代码位置） |
EVIDENCE | 受支持（处理时将被忽略） |
DETECTION | |
| 不支持。 在处理过程中被删除。 |
别名支持
| 别名格式 | 支持 |
|---|---|
CVE-YYYY-NNNNN | |
| 支持。 提取结果为 CVE 标识符。 仅使用第一个 CVE 别名。 | |
| 其他格式（GHSA、PYSEC 等） | |
| 不支持。 在处理过程中被移除。 |
注意
如果漏洞 id 字段以 GHSA-开头，则会将其识别为 GHSA 标识符。 但是，数组中的 aliases GHSA 条目被剥离，不会保留。
字段大小约束
OSV 规范不定义任何字段的最大字符串长度 - 所有字符串均未绑定。 但是， GitHub 基于其内部数据库架构强制实施字段大小限制。 在不破坏与 GitHub Enterprise Server 的同步的情况下，无法放宽这些限制，因为它自身维护着兼容的架构。
超过这些限制的提交将被拒绝，并显示描述性 422 错误，指示哪个字段超出了限制和提供的实际长度（例如， affected[0].first_patched_version is 63 characters (max 50)）。
| OSV 字段 | 映射到 | OSV 标准上限 |
GitHub 限制 | 单位 |
|---|---|---|---|---|
| summary | vulnerabilities.summary | 无限制（建议≤120 个字符） | 1,024**** | 字节 |
| id | vulnerabilities.external_id | 无限制 | 2,048**** | 字符 |
| aliases[] （CVE 条目） | vulnerabilities.cve_id | 无限制 |
20 | 字符 |
| severity[].score （CVSS v3） | vulnerabilities.cvss_v3 | 无限制 |
255 | 字节 |
| severity[].score （CVSS v4） | vulnerabilities.cvss_v4 | 无限制 |
255 | 字符 |
| affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | 无限制 |
20 | 字符 |
| affected[].package.name | vulnerable_version_ranges.affects | 无限制 |
255 | 字符 |
| affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | 无限制 |
50 | 字符 |
| 计算易受攻击的版本范围 | vulnerable_version_ranges.requirements | 无限制 |
65,535 | 字节 |
fixed_in （第一个修补版本）限制为 50 个字符是最常见的约束。 某些生态系统使用超出此限制的长预发行版本字符串（例如 1.0.0-alpha.gamma.delta.epsilon.zeta.eta.theta）。
-
varchar列按字符计数进行验证;varbinary和text列按字节大小进行验证（与多字节 UTF-8 字符相关）。
- 这些限制受 GitHub Enterprise Server 架构兼容性的约束。 在没有匹配 GHES 更改的情况下扩大列 GitHub 将导致环境之间的公告同步失败。
生态系统映射
GitHub 将 OSV 生态系统名称映射到其内部生态系统标识符。 支持以下生态系统：
| OSV 生态系统 |
GitHub 生态 |
|---|---|
| npm | npm |
| PyPI | pip |
| RubyGems | RubyGems |
| Maven | Maven |
| NuGet | NuGet |
| Packagist | Composer |
| Go | Go |
| crates.io | Rust |
| Hex | Erlang |
| Pub | Pub |
| SwiftURL | Swift |
| GitHub Actions | GitHub Actions |
示例：用于生成警报的最小 OSV 有效负载
以下是一个最小 OSV 负载，包含 GitHub 创建 Dependabot 警报所需的所有必需字段：
{
"schema_version": "1.4.0",
"id": "EXAMPLE-2024-001",
"modified": "2024-01-15T10:00:00Z",
"summary": "Example vulnerability in example-package",
"details": "A detailed description of the vulnerability.",
"aliases": ["CVE-2024-12345"],
"severity": [
{
"type": "CVSS_V3",
"score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
}
],
"affected": [
{
"package": {
"ecosystem": "npm",
"name": "example-package"
},
"ranges": [
{
"type": "ECOSYSTEM",
"events": [
{ "introduced": "0" },
{ "fixed": "1.2.3" }
]
}
]
}
],
"database_specific": {
"severity": "Critical"
},
"references": [
{ "type": "ADVISORY", "url": "https://example.com/advisory" }
],
"published": "2024-01-15T10:00:00Z"
}
已知的限制
- 每个请求最多 100 个漏洞。 同步 API 在单个请求中最多接受 100 个漏洞。
- 无
GIT范围类型。 不支持基于 Git 提交的版本范围。 - 每个生态系统范围的单个事件类型。 每个
ECOSYSTEM范围支持一个introduced和一个上限事件（fixed或last_affected）。 不支持在单个ECOSYSTEM范围中使用多个introduced/fixed对——请改用单独的范围或单独的affected条目。 （此限制不适用于SEMVER支持多个事件对的范围。 fixed和last_affected是互斥的。 单个范围不能同时包含fixed和last_affected事件。 使用一个或另一个。- GHES 同步兼容性。 字段大小限制（如
fixed_in50 个字符）受 GitHub Enterprise Server 架构兼容性要求的约束。