disclose

name	disclose
description	Draft the disclosure content for a finding in GitHub Security Advisory shape. Produces a title, markdown description, affected package block, CVSS vector, CWE list, and references, then writes them back to the finding so the analyst can paste them into the GHSA form (or POST to GitHub's repository-advisories REST endpoint) rather than composing from scratch.
license	MIT
compatibility	Needs network access to the scrutineer API (http://host:port/api). Finding-scoped; runs on one finding at a time.
metadata	{"scrutineer.version":1,"scrutineer.output_file":"report.json","scrutineer.output_kind":"freeform"}

disclose

Draft disclosure content for an existing finding in a shape that maps one-to-one to GitHub's repository security advisory (GHSA) form. You are not deciding whether the bug is real — the triage and verify skills did that. Your job is to turn a confirmed finding into text a maintainer can paste into https://github.com/{org}/{repo}/security/advisories/new, or that a caller can POST to POST /repos/{owner}/{repo}/security-advisories.

Workspace

• ./src — the repository at its current HEAD, so you can link to file:line and read tag history
• ./context.json — has scrutineer.api_base, scrutineer.token, scrutineer.repository_id, and scrutineer.finding_id (required; this skill only makes sense finding-scoped)
• ./report.json — write a GHSA-shaped record of what you drafted
• ./schema.json — shape of report.json

What to do

1. Read ./context.json. If scrutineer.finding_id is missing, write {"error": "no finding_id in context.json; disclose is finding-scoped"} to report.json and exit 0.

2. Fetch the finding: GET {api_base}/findings/{finding_id} with Authorization: Bearer {token}. You get title, severity, cwe (comma-joined), location, affected, cvss_vector, cve_id, fix_version, fix_commit, and the six-step prose (trace, boundary, validation, prior_art, reach, rating). Also fetch:

   • GET {api_base}/repositories/{repository_id} for the upstream URL and default branch
   • GET {api_base}/repositories/{repository_id}/packages for the list of published packages; you need this to fill GHSA's affected-package block

3. Compose the GHSA fields below. Every field names the GHSA REST key (summary, description, vulnerabilities, etc.) so the mapping is explicit. Keep each one factual and derived from the finding — do not invent details the audit did not establish.

   summary (title). A single sentence, under 80 characters. Start with the impact verb ("Arbitrary file write in …", "Prototype pollution in …"), not the package name. Reuse the finding's title if it already fits that shape.

   description (markdown body). This is the main document a maintainer reads. Structure as below. Each section is required unless marked optional.

   ## Summary
   
   Two or three sentences describing the vulnerability in the maintainer's own domain terms. Repeat the one-line summary then expand.
   
   ## Impact
   
   What an attacker can do. Stay tight — reuse the Rating prose if it already covers this. Name the attacker model (unauthenticated remote, local, authenticated user) in the first sentence.
   
   ## Affected versions
   
   A line per affected range, matching the `vulnerabilities[].vulnerable_version_range` values. Example:
   - `>= 1.0, < 2.3.1` (all pre-2.3.1 releases)
   
   ## Patched versions
   
   If a fix has shipped, list the first patched version. Otherwise write "Not yet patched" and state whether the `fix_commit` on the finding is on the default branch.
   
   ## Proof of concept
   
   Reuse the Validation prose, formatted as a short runnable recipe. Include the minimum needed to trigger the bug. A fenced code block when a script exists.
   
   ## Fix suggestion
   
   One or two sentences on where the guard belongs (sanitise here, validate there, remove the sink). Do not claim a specific patch unless the Trace identifies the exact line.
   
   ## References
   
   - `{repo.html_url}/blob/{default_branch}/{location}` — the vulnerable code
   - `https://cwe.mitre.org/data/definitions/{n}.html` — one line per CWE
   - any URL that appeared verbatim in the prior_art field of the finding
   

Constraints

• Do not mark the finding as ready — lifecycle transitions belong to the analyst. Your output is input for their review, not a replacement for it.
• Do not post communications. POST /findings/{id}/communications records maintainer contact, which this skill has not made.
• Do not fabricate a CVE ID, a CWE, a credit, or a vulnerable function name. Every value in the ghsa block must be derivable from the finding, the repo, or the packages list.
• Do not emit severity and cvss_vector_string together — GHSA rejects the pair. Prefer the CVSS vector; use severity only when you cannot derive a vector.
• If the finding prose is too thin to draft from (empty Trace, empty Validation), write {"error": "finding {id} has insufficient prose to draft disclosure"} to report.json and exit 0. Do not PATCH anything.