Table of Contents generated with DocToc

Fixing security issues

High-level overview of how the security team handles a vulnerability report from inbound email through published CVE. This page is project-agnostic; the concrete lists, repos, release trains, and tooling for the adopting project live in [<project-config>/project.md](/project.md) (adopters bootstrap from the projects/_template/ scaffold).

The end-to-end 16-step lifecycle is in README.md. This page is the two-minute summary.

Process

  1. Vulnerability identification. The adopting project’s community monitors the project’s <security-list> (declared in <project-config>/project.md → Mailing lists) for inbound reports. Reports from elsewhere (GHSA, HackerOne, the ASF security@apache.org relay) are forwarded onto that list so the security team has a single inbox.

  2. Triage. A rotating triager imports new reports into the private <tracker> repository (see the security-issue-import skill), classifies each candidate, and drafts a receipt-of-confirmation reply to the reporter. The team then discusses CVE-worthiness in the issue comments and — once the report is assessed valid — applies a project-specific scope label (see <project-config>/scope-labels.md).

    For the rarer case where a security-relevant fix lands as a public PR on <upstream> without ever hitting <security-list>, the triager uses security-issue-import-from-pr instead. The skill creates the tracker directly with a scope label and the Assessed board column — the deliberate import implies the validity assessment has already happened informally, so the CVE-worthiness discussion is skipped and the tracker is ready for CVE allocation immediately.

    When the team’s discussion lands a consensus-invalid decision, the triager applies that decision via the security-issue-invalidate skill: it adds the invalid label, posts a short closing comment, archives the project-board item, and — when the tracker has an inbound <security-list> thread — drafts a polite-but-firm reply to the reporter explaining the reasoning (mined verbatim from the tracker’s discussion and combined with a fitting canned response from [<project-config>/canned-responses.md](/canned-responses.md)). The draft is never sent — the triager reviews in Gmail before sending. The skill hard-stops if a CVE has already been allocated (a Vulnogram REJECT is required first) or if the advisory has shipped (closing as invalid then is a public retraction that needs explicit team escalation).

  3. CVE allocation. A PMC member of the adopting project allocates a CVE through the project’s CVE tool (declared in [<project-config>/project.md → CVE tooling](/project.md#cve-tooling)). The allocation is PMC-gated; non-PMC triagers use the security-cve-allocate skill to produce a relay message for a PMC member to click through.

  4. Remediation. A security-team member writes the fix in the public <upstream> repository (see the security-issue-fix skill, which can draft the PR automatically). The public PR is scrubbed of CVE references, tracker-repo references, and any “security fix” signal — per the confidentiality rules in AGENTS.md.

  5. Release + advisory. The release manager for the cut that carries the fix sends the public advisory to the project’s users + announce lists, captures the archive URL, and moves the CVE record to PUBLIC in the CVE tool.

  6. Continuous improvement. The security team encourages responsible vulnerability disclosure and continues to improve the project’s security posture, security features, and handling process. The adopting project’s security model — declared in [<project-config>/security-model.md](/security-model.md) — is the authoritative reference for what counts as a vulnerability.

Best practices

  • Avoid labelling low-severity fixes as “security fixes” in public commits. When we implement low-severity security fixes — sometimes ones that are not even worthy of a CVE — we avoid describing them as security features in public commit messages, newsfragments, and release notes. This prevents automated scrapers from raising reports about issues they were not originally aware of. Such tools may themselves violate our security practices.
  • Keep the reporter informed at every status transition — see the Keeping the reporter informed section of roles.md for the full list of transitions and the drafting rules.
  • Confidentiality first. Tracker URLs and #NNN identifiers are public-safe (they point at access-gated pages); tracker contents — comments, labels, rollup entries, body excerpts — must not appear on a public surface; and the security framing of a public PR (the words CVE-, “vulnerability”, “security fix”, “advisory”) stays embargoed until the advisory ships. See the Confidentiality of the tracker repository section of AGENTS.md for the three-layer rule and the sharing-with-non-team-recipients pattern. The threat model covers the adversaries (P1–P5) the rule defends against and the STRIDE rows for skill family D (public remediation).