Back to Details

draft-security-advisory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Security Advisory Writer

GitHub Security Advisory 撰写指南

Turn the vulnerability report the user provides into a publication-ready GitHub Security Advisory (GHSA): a terse two-section body, with the precision carried by GitHub's structured form fields.
将用户提供的漏洞报告转换为可发布的GitHub Security Advisory（GHSA）：内容简洁，分为两个部分，同时契合GitHub结构化表单字段的严谨要求。

Class, not instance

聚焦类别，而非实例

The advisory speaks at the level of the vulnerability class: the flaw class (SQL injection, SSTI, missing authorization), the broken or missing control, the feature area, the risk category. Everything at the level of the instance — function names, file paths, field names, endpoints, configuration keys, code snippets, payloads — stays out, so a reader can never work backwards from the advisory to the patched code path. A published advisory locates a flaw no more precisely than "certain endpoints", "a configuration field", "a certain page", "names of a few records" — match that register.
公告需聚焦漏洞类别层面：即缺陷类型（如SQL注入、SSTI、权限缺失）、失效或缺失的控制措施、功能领域、风险类别。所有实例层面的信息——函数名、文件路径、字段名、端点、配置键、代码片段、攻击载荷——均需排除在外，确保读者无法通过公告反向推导出已修复的代码路径。已发布的公告对漏洞的定位精度不应超过“部分端点”“某个配置字段”“某页面”“少量记录名称”，需严格遵循此标准。

Title

标题

Pick the established pattern that fits; when an earlier advisory for the same project covered the same class, reuse its title verbatim — repeated titles are house style, not a defect:
  • Injection flaws: 
    Possibility of {class} due to missing validation
  • Authorization flaws: 
    Unauthorised {action} due to missing validation
    (British spelling)
  • Outcome-led: 
    {Outcome} via {class}
    — e.g. 
    Account takeover via Reflected XSS
  • Feature-scoped: 
    {Class} in {feature area}
    — a last resort, only when none of the patterns above fit; never to make a title unique, since identical titles across advisories are fine. Generalize the feature area so the exact feature stays unrevealed: name an umbrella surface one level broader than where the flaw sits (e.g. "portal pages", not the specific portal), never a module, screen, or record type.
选择符合既定格式的标题；若同一项目此前针对同类漏洞发布过公告，需直接复用其标题——重复标题是规范风格，而非缺陷：
  • 注入类缺陷：
    Possibility of {class} due to missing validation
  • 权限类缺陷：
    Unauthorised {action} due to missing validation
    （英式拼写）
  • 结果导向型：
    {Outcome} via {class}
    — 示例：
    Account takeover via Reflected XSS
  • 功能范围型：
    {Class} in {feature area}
    — 仅当上述模板均不适用时作为最后选择；切勿为了让标题唯一而使用此模板，因为公告间标题重复是允许的。需对功能领域进行泛化处理，避免暴露具体功能：选择漏洞所在层级更宽泛的 umbrella surface（如“门户页面”，而非具体某一门户），绝不提及模块、页面或记录类型。

Advisory body

公告正文

Exactly two sections:
markdown
undefined
正文需严格分为两个部分：
markdown
undefined

Impact

Impact

{One or two sentences: where the flaw sits, at class level; what control was missing; what the attacker gains and the minimum privilege needed.}
{One or two sentences: where the flaw sits, at class level; what control was missing; what the attacker gains and the minimum privilege needed.}

Workarounds

Workarounds

No workaround available; upgrading is required.

Reuse the stock Impact sentence when the class has one:

- SQL injection: "Some endpoints were vulnerable to SQL injection through specially crafted requests, which would allow a malicious actor to extract sensitive information."
- Missing authorization: "Certain endpoints failed to enforce proper authorization checks, allowing users to modify data beyond their permitted role."

For other classes, write the sentence in the same register: "{Class} through {vague vector} allows {an authenticated user / a malicious user} to {capability}." Amend the Workarounds line only when a real workaround exists.
No workaround available; upgrading is required.

若对应缺陷类别有标准影响描述语句，需直接复用：

- SQL注入：`Some endpoints were vulnerable to SQL injection through specially crafted requests, which would allow a malicious actor to extract sensitive information.`
- 权限缺失：`Certain endpoints failed to enforce proper authorization checks, allowing users to modify data beyond their permitted role.`

对于其他缺陷类别，需遵循相同风格撰写语句：`{Class} through {vague vector} allows {an authenticated user / a malicious user} to {capability}.`（将占位符替换为对应内容）。仅当存在切实可行的临时解决方案时，才修改Workarounds部分的内容。

Form fields

表单字段

After the body, list the values for GitHub's advisory form:
  • Ecosystem / package: the project's ecosystem and package name
  • Affected / patched versions: one row per currently supported release stream — ask the user which streams are supported if not stated in the report; affected 
    < {first fixed release}
    , patched 
    {first fixed release}
  • CVSS: v3.1 vector and score, derived from the rules below, with a one-sentence rationale for each non-obvious metric choice (PR, S, C, I)
  • Severity: the band the score falls in
  • CWE: the most specific id available
  • Credits: reporter(s) from the report as reporter; whoever authored the fix as remediation developer
That is the whole advisory: the body carries no summary, no root-cause walkthrough, and no proof of concept, and the CVE field stays empty — GitHub assigns one after publication. The report's PoC informs the CVSS metrics only.
正文之后，列出GitHub公告表单的各项值：
  • 生态系统/包： 项目所属的生态系统及包名
  • 受影响/已修复版本： 每个当前支持的发布流对应一行；若报告中未说明支持的发布流，需向用户确认；受影响版本格式为
    < {首个修复版本}
    , 已修复版本为
    {首个修复版本}
  • CVSS： v3.1向量及评分，根据下方规则推导得出；对于非显而易见的指标选择（PR、S、C、I），需用一句话说明理由
  • 严重程度： 评分所属的等级区间
  • CWE： 最具体的对应ID
  • 致谢： 报告中的提交者标注为reporter；修复代码的作者标注为remediation developer
以上即为完整的公告内容：正文无需包含摘要、根本原因分析或概念验证（PoC），CVE字段留空——GitHub会在发布后自动分配CVE编号。报告中的PoC仅用于辅助推导CVSS指标。

Derivation rules

推导规则

CVSS metrics, from the report:
  • AV — Network if reachable via web UI; Local if shell access is required.
  • AC — Low, unless the report describes a race condition, non-default setup, or hard-to-meet precondition.
  • PR — None if unauthenticated; Low for any authenticated user or common operational role; High for admin/superuser only.
  • UI — None, unless a victim must take an action.
  • S — Changed when the exploit reaches resources outside the attacker's own authorization scope (cross-tenant data, document types the role cannot normally access).
  • C — High if arbitrary sensitive records are readable; Medium if limited; None otherwise.
  • I — High for arbitrary writes or deletes; Low for constrained or incidental writes; None if read-only.
  • A — High if service disruption is possible; None otherwise.
CWE — the most specific available:
  • Template injection → CWE-1336
  • SQL injection → CWE-89
  • Missing authorization → CWE-862
  • Improper input validation → CWE-20
  • Code injection (generic) → CWE-94
  • Path traversal → CWE-22
  • XSS → CWE-79
  • SSRF → CWE-918
  • XXE → CWE-611
Severity bands from the CVSS base score: 9.0–10.0 Critical · 7.0–8.9 High · 4.0–6.9 Medium · 0.1–3.9 Low.
If the report supplies its own CVSS or CWE, validate it; where your analysis disagrees, use your analysis and note the discrepancy in one sentence.
CVSS指标，基于报告内容推导：
  • AV（攻击向量）：若可通过Web UI访问则为Network；若需Shell访问则为Local
  • AC（攻击复杂度）：默认Low，除非报告中描述了竞争条件、非默认配置或难以满足的前置条件
  • PR（所需权限）：未认证用户可利用则为None；任何已认证用户或普通操作角色可利用则为Low；仅管理员/超级用户可利用则为High
  • UI（用户交互）：默认None，除非受害者需执行特定操作
  • S（范围）：若攻击可触及攻击者自身权限范围外的资源（如跨租户数据、角色通常无法访问的文档类型）则为Changed
  • C（保密性影响）：可读取任意敏感记录则为High；仅能读取有限敏感记录则为Medium；否则为None
  • I（完整性影响）：可任意写入或删除则为High；仅能进行受限或偶然写入则为Low；若仅为只读则为None
  • A（可用性影响）：可能导致服务中断则为High；否则为None
CWE — 选择最具体的对应ID：
  • 模板注入 → CWE-1336
  • SQL注入 → CWE-89
  • 权限缺失 → CWE-862
  • 输入验证不当 → CWE-20
  • 代码注入（通用） → CWE-94
  • 路径遍历 → CWE-22
  • XSS → CWE-79
  • SSRF → CWE-918
  • XXE → CWE-611
严重程度区间基于CVSS基础评分：9.0–10.0 严重（Critical）· 7.0–8.9 高（High）· 4.0–6.9 中（Medium）· 0.1–3.9 低（Low）
若报告中已提供CVSS或CWE信息，需进行验证；若你的分析结果与报告不符，以你的分析为准，并使用一句话说明差异。

Final check

最终检查

Re-read the title and the Impact section. They must hold zero instance-level identifiers.
重新阅读标题和影响部分，确保其中不包含任何实例层面的标识符。