Draft Security Advisory (draft-security-advisory)

Turn a vulnerability report into a ready-to-review GitHub security advisory draft for nrwl/nx. This skill drafts; it NEVER publishes. The final review and the publish step are always performed by a human.

Save the finished draft to tmp/security-advisories/<slug>/advisory.md (gitignored), where <slug> is a short kebab-case name for the vulnerability (e.g. graph-server-cors).

Inputs

The argument is the vulnerability report: a file path, pasted text, or a pointer (e.g. a GitHub private vulnerability report / GHSA draft ID, fetchable via gh api /repos/nrwl/nx/security-advisories/<GHSA-ID>). If no report is provided, ask for one — do not invent a vulnerability.

Process

Work through these phases in order. Do not skip the investigation phases — the advisory must be grounded in the actual code, not just the reporter's claims.

Phase 1 — Understand the report

• Read the full report. Identify: the claimed flaw, the attack scenario, the entry point (which package / command / server), and any proof of concept.
• Restate the vulnerability in one sentence before proceeding. If the report is ambiguous or you cannot confirm the flaw exists in the code, stop and report that instead of drafting.

Phase 2 — Confirm scope in the code

• Locate the vulnerable code in this repo. Read enough surrounding code to understand the real trust boundary: what is attacker-controlled, what checks exist, and what the worst-case outcome is.
• Determine what is and is not exposed. Which configurations, commands, or product surfaces trigger the vulnerable path? Which ones use a different code path and are unaffected? This is a per-report judgment based on the code you just read — verify each claim of "not affected" by finding the diverging code path, and say so in the draft with a > [!IMPORTANT] callout.
• Distinguish "practical impact in realistic usage" from "theoretical worst case" — the Summary states the practical impact; the Details section may note the escalation path.

Phase 3 — Establish version ranges

• Find the commit/PR that introduced the flaw: git log -S '<code fragment>' or git log --follow on the file, then gh pr list --search <sha> to map the commit to a PR.
• Map the introducing commit to the first released version: git tag --contains <sha> | sort -V | head.
• Find the fix PR(s) and the first patched version(s) on every affected release line (including backports). Verify with npm view <pkg> versions --json that the patched versions are actually published.
• List every affected npm package separately with its own vulnerable range and patched versions. If a package is deprecated rather than patched, its remediation is migration guidance, not an upgrade.

Phase 4 — Score severity

• Propose a CVSS vector and score (v3.1 or v4.0 — match whichever the fix team is using; include the full vector string). Justify each metric choice in one line each in your working notes; the advisory itself gets the score, the vector, and a one-sentence statement of exploitation preconditions.
• Identify the applicable CWE ID(s).

Phase 5 — Write the draft

Write tmp/security-advisories/<slug>/advisory.md with two parts:

1. The advisory body (markdown, layout below) — this is what gets pasted into the GHSA "Description" field.
2. A metadata section at the end for the GHSA form fields: summary/title (≤ 100 chars), severity, CVSS vector, CWE IDs, and a per-package table of ecosystem | package | vulnerable version range | patched versions.

Then print the draft location and a short recap (severity, affected packages, patched versions) so the reviewer can sanity-check at a glance.

Advisory body layout

Follow the structure of previously published nrwl/nx advisories (e.g. GHSA-vp3h-ghgh-jr7g, GHSA-g2r8-wvmj-jf5w). Sections, in order:

## Summary

One short paragraph: what the flaw is, who is exposed, and the practical
impact. If the realistic impact differs from the theoretical worst case,
state the realistic one here.

## Severity

**<High/Medium/...>** — CVSS vX.Y **<score>** (`<full vector string>`)

One or two sentences on exploitation preconditions (what an attacker needs,
what the victim must be doing).

- **CWE-NNN**: <name>

## Affected & Patched Versions

Per-package version ranges and patched versions. State which version
introduced the flaw. Call out release lines that are NOT patched and where
those users should go.

> [!IMPORTANT]
> Use callouts like this to scope the blast radius when the investigation
> shows that common configurations or related surfaces are unaffected —
> name them explicitly and say why they are unaffected.

## Remediation

Exact upgrade targets ("Upgrade to `X.Y.Z` or later"). Note when the fix is a
drop-in vs. requires configuration changes. For deprecated packages, link the
migration guidance instead of a patched version.

## Details

Technical walkthrough: the vulnerable code (short, real snippets from the
repo), why it is exploitable, and what the fix changes. Be precise about what
is attacker-controlled and what is not — if part of the attack requires
capabilities that already imply code execution, say so.

## References

- Fix: <PR link(s)>
- Introduced: <PR link(s) that introduced the vulnerable code>
- Any related advisories, CVEs, or docs

## Credits

- **<Name>** (<affiliation or GitHub handle>) — Reporter

Hard rules

• Never publish, create, or update an advisory on GitHub. Output is the local draft file only. If the reviewer wants to create the GHSA draft via gh api, they run that themselves after review.
• Never include unpublished vulnerability details in anything that leaves the draft directory (commits, PRs, issues, comments).
• Every factual claim in the draft (ranges, introducing PR, patched versions, "not affected" statements) must be verified during Phases 2–3, not copied from the report.
• Credit the reporter by the name/handle they used in the report.