version: "1.0.2" name: vulnerability-writeup description: Turn vulnerability notes, disclosure reports, PoCs, source code, or Codex Security findings into self-contained, sceptically validated, natural-sounding vulnerability reports. Use for one vulnerability or a disclosure campaign; a Codex Security scan is optional.

Vulnerability Writeup

Before choosing paths or saving retained output, read ../../references/artifact-storage.md and follow its storage policy.

Purpose

Produce a disclosure report that another security researcher can understand, check and, where safely possible, reproduce. Treat the original finding as a hypothesis, not a conclusion. Establish the assessed software version, attacker position, reachable entry point, expected security behaviour, actual failure and narrowest demonstrated impact before deciding how strongly the report can speak. Pin the exact underlying source privately so the report remains accurate without burdening the reader with unnecessary commit hashes.

The result is still a finished, distributable vulnerability report, not an interactive review. Bring the scepticism, evidence discipline and approachable researcher-to-researcher voice of a good conversational review into the report itself.

Accept supplied notes, disclosure documents, existing reports, PoCs, source trees and scanner findings as first-class inputs. Do not require a scan ID, finding bundle, manifest, coverage receipt or other Codex Security scan artefact.

Non-negotiable rules

• Give each distinct vulnerability its own report directory and exactly one drafting sub-agent. The main agent owns inventory, deduplication, source checks and final acceptance.
• During Codex Security final reporting, the scan request authorises those one-finding drafting sub-agents. Do not request separate delegation approval.
• When the exact vulnerable source revision is available, inspect it. Resolve the complete commit internally when possible and note dirty, shallow, missing, patched or mismatched source. For a reproduced vendor or distribution package, verify every reader-facing excerpt and line citation against that exact patched source; use upstream source separately for history unless it is also the code that ran. Follow relevant dependency code in causal order and identify its exact tested version. Use git show REV:PATH for a non-checked-out revision rather than treating the current worktree as that revision. In the report, identify the software by its verified public release whenever one exists.
• If the exact source or revision is unavailable, stop and request it. Produce a report-only assessment only when the user explicitly accepts that limitation, and make every source-dependent conclusion visibly conditional.
• When source and release history are available, trace the vulnerable code back to the change that introduced it and determine which released versions actually contain the vulnerable behaviour. Inspect the relevant tags, release branches, fixes and backports; never turn an unverified commit range into an affected-version claim.
• Never invent a source excerpt, line number, revision, affected version, first affected release, fixed release, advisory, CVE, CVSS vector, deployment prevalence, exploit route, execution result or observation.
• Distinguish source evidence, inspected-but-unexecuted PoCs, actual runtime observations, supplied report claims, inference and unknowns. Do not promote an inspected PoC into a reproduced vulnerability.
• Do not use "witness" as shorthand for supporting evidence. Name the actual source excerpt, test input, HTTP request and response, execution trace, proof-of-concept run, observed output or counterexample, and explain exactly what it demonstrates. Preserve an actual source identifier containing that word only when necessary, and immediately explain its concrete meaning.
• Test only within the user's explicit authorisation. Use disposable local targets for crashing, destructive or privilege-escalating PoCs. Never contact or test a public, external or production target without target-specific permission.
• Do not manufacture PoC commands, logs, screenshots or sample output. Include observed output only when it was actually produced or when a supplied, identifiable trace was inspected. Label a prediction as expected output and explain that it was not observed.
• Write in the language and locale the user requests; when they do not specify one, use their normal default. Be warm, direct and exact; guide substantive reasoning with a natural we, and use I only for work actually performed. Describe what the software should do, what it actually does and why that matters in plain language.
• Give people clear, conventional names when they help explain the finding: Alice is the legitimate account or resource owner, Bob is another legitimate user or intended recipient, Mallory is the active attacker, and Eve is a passive observer. Use matching example usernames such as alice, bob, mallory and eve consistently in prose, commands and PoCs.
• Make every delivered report and PoC portable and self-contained. Use repository-relative source paths, report-relative commands and verified software versions. Never include an author-machine-specific absolute path in report prose, excerpts, citations, links, PoC code, build files, command examples or captured output; retain a verified absolute target-system path when it is necessary to describe or reproduce the vulnerability.

Actors, language and release references

Introduce only the people the particular finding needs and keep their roles consistent. For example: Alice owns the document; Mallory signs in as mallory and retrieves it by changing the document ID. Add Bob when the behaviour involves another legitimate user or intended recipient, and Eve only when passive interception is actually relevant. Preserve important real system roles, privileges and account types; do not pretend that a generic example user has permissions the actual product does not grant.

Explain the problem in terms of what should happen and what happens instead. Prefer Only Alice should be able to read her document, but the download handler checks that Mallory is signed in without checking who owns the document over abstract, theory-heavy security language. Define genuinely necessary technical terms once and use them only when they clarify the real mechanism.

Replace opaque evidence labels with the actual thing observed. For example, write the request showing Mallory received Alice's document, the input that triggers the out-of-bounds read, the recorded order of the two requests, the failing regression test, or the source lines showing that the ownership check is missing. Choose the phrase that matches the real evidence; do not substitute an equally vague generic label.

Use public release numbers as the primary reader-facing source references. Give the assessed release, the first verified affected release and the fixed release when established. Cite source using a repository-relative path and function; do not repeat a commit hash for every excerpt. Include a short commit reference only when the introducing change, fixing change, unversioned build or conflicting release history is itself important to the explanation.

Trace affected release history

Before drafting, inspect the history of the actual vulnerable code rather than assuming the current version has always behaved this way.

1. Identify the exact lines, check, state change or permission decision that makes the reported attack possible.
2. Trace that behaviour through file history, renames and blame to identify the change that introduced it.
3. Inspect release tags and maintained branches to find the earliest released version that actually contains the vulnerable behaviour.
4. Inspect the fixing change and each relevant release branch to determine the first fixed version and any backported fixes.
5. Confirm representative affected and fixed release snapshots directly. A tag containing an introducing commit is not proof that the released code remained vulnerable after subsequent fixes or backports.
6. State separately what is confirmed, what is the earliest version inspected and what cannot be determined from the available history. If tags, older history or release mappings are missing, say so rather than claiming a definitive first affected version.

Do not stop at a shallow checkout when complete history, release archives or authoritative mirrors can be obtained safely within scope. Use checksum manifests or equivalent publisher evidence to establish archive provenance where appropriate. Inspect enough actual release snapshots to support the stated family or branch coverage, then name the intermediate patch releases or current branch tips that were not individually checked.

Use Git history and full commit identities as research evidence, not as repeated report prose. When supported, explain the result as a release history: The vulnerable ownership check was introduced in 2.3.0, is present in 2.3.0–2.5.1, and is corrected in 2.5.2. Explain what the introducing change was trying to do and why the earlier release did not have the problem when that history clarifies the root cause. Do not present that example as a finding or reuse its version numbers without checking the real project.

Evidence-first intake

Before drafting, inventory:

• the raw finding, report, disclosure notes and claimed trigger;
• the exact source root, assessed release and privately pinned commit or tag, or the source limitation the user explicitly accepted for a report-only assessment;
• the introducing change, earliest verified affected release, affected release branches, fixing change and verified fixed or backported releases;
• the affected paths, functions, configuration and build options;
• Alice, Bob, Mallory or Eve as appropriate, together with each person's actual account, required credentials, privileges and controlled input;
• the affected owner, intended recipient, security boundary and downstream consumer;
• the claimed impact and the narrower primitive actually supported;
• any PoC, logs, negative control, regression test and available fix;
• what was read, built, executed, observed, merely supplied or not available;
• the testing authorisation and any disposable test environment.

Write down the minimal reported trigger as a hypothesis before tracing it. Keep the actual attacker-controlled input, intermediate state and claimed sink aligned throughout the investigation. Do not quietly replace the claimed exploit with an easier earlier event, another request, a different object, a patched revision or a test-fixture-only behaviour.

Before drafting, reduce the finding to one concrete attack sentence: who Mallory is, which legitimate credential or input she controls, what she does, which separate policy or owner should stop her and which real sink she reaches. State the important non-claims alongside it, such as Mallory reuses her own session; she does not steal Alice's session or break TLS. Record the complete tested topology and prerequisites near this sentence, separating defaults from operator configuration and leaving deployment prevalence unknown unless measured.

Challenge the claim before making it sound convincing:

• Is the required configuration default, optional, unusual or unknown? Documentation and shipped examples establish existence, not prevalence.
• Does the attacker already need the access or privilege that the report claims to obtain?
• Does the exact source preserve the reported object ownership, callback order, lock, lifetime, bounds, validation order and final sink?
• Can cancellation, generation checks, error handling, cleanup, permissions or another guard prevent the path?
• Does a controlled test change only timing or visibility, or can it create the outcome itself?
• What negative control or concrete observation would distinguish the claimed vulnerability from a benign explanation?
• Does the evidence establish reachability, a bad state, a real boundary crossing or only a stronger impact that remains possible?

If the source contradicts the finding, stop presenting it as a vulnerability. Explain the contradiction and the remaining evidence rather than generating a persuasive disclosure for a false positive.

Campaign workflow

1. Create the user-requested report directory, or use reports/. Inventory and deduplicate findings by root cause and source path rather than title.
2. Read references/report-format.md completely. Require each drafting sub-agent to read it before writing.
3. When the vulnerable source is available, pin and inspect it. Independently check the decisive entry point, security check, state change, sink and available fix. Trace the introducing change and inspect affected and fixed release tags only when the relevant history is available; otherwise record that limitation without blocking a source-backed report. When the user explicitly accepted a report-only assessment, record the unavailable source and require every source-dependent conclusion to remain conditional.
4. Record the one-sentence attack and non-claims, available verified release history or explicit release-history limitations, named actors, complete tested topology, defaults versus configured prerequisites, meaningful positive and negative controls, exact validation basis and testing boundary before assigning the finding.
5. During Codex Security final reporting, write each detailed report to findings/<slug>/<slug>.md, using the identical lowercase slug for its directory and filename, and record that exact safe relative path as writeup.reportPath. Outside Codex Security final reporting, preserve the user-requested report directory and filename; use a descriptive <slug>.md only when no filename was requested. Create a sibling poc/ directory only when real PoC artefacts exist or can safely be developed.
6. Launch exactly one sub-agent for each distinct vulnerability. Provide only that vulnerability's raw material, available pinned source or explicitly accepted report-only limitation, PoC artefacts, output directory, exact report path, report-format reference and authorisation boundary.
7. Independently read the returned report against the raw artefacts and any available pinned source and release history. Check each important claim, excerpt, transition, affected-version statement, impact, fix and reported observation; keep source-dependent conclusions conditional when source inspection was unavailable and the user accepted a report-only assessment.
8. Reject a draft that smooths over missing evidence, invents a run, inflates impact, guesses affected versions, leaks an author-machine-specific absolute path, calls an unexplained piece of evidence a "witness", overloads the prose with hashes or jargon, mistakes configuration existence for prevalence, or uses named actors or first-person language as decoration.
9. If the draft needs substantive repair, launch a fresh sub-agent for that same finding with the original artefacts and specific review failures. Do not cover an evidentiary failure with cosmetic edits.
10. Make only small final corrections after acceptance, and validate the completed report and real PoC artefacts before delivery.

If delegation is unavailable, report that constraint instead of silently drafting a production-scan finding in the main agent. If a worker stalls, give one explicit finish instruction, retry once with a tighter single-finding assignment, and report the remaining blocker if the retry also fails.

Single-finding drafting prompt

Use this shape and supply the actual evidence:

Write one self-contained vulnerability disclosure report for <slug>.
 
You own exactly one finding. Read references/report-format.md completely before drafting.
 
Inputs:
- Raw finding and rough report: <paths>
- Source root and privately pinned vulnerable revision: <path and revision; never put the author-machine path in the report; or unavailable, with the user's explicit acceptance of a report-only assessment>
- Assessed release and verified affected versions: <release, first affected version, branches and gaps>
- Introducing and fixing changes: <verified history, release tags and backports>
- Relevant source paths, functions and claimed trigger: <details>
- Existing PoC, logs and negative controls: <paths or none>
- Fix or advisory, if directly available: <revision and paths or unknown>
- Attacker prerequisites and configuration: <known facts and unknowns>
- Named actors and usernames: <Alice/alice, Bob/bob, Mallory/mallory or Eve/eve as appropriate>
- Testing authorisation and disposable lab: <boundary>
- Report and PoC output directory: <directory>
- Exact report output path: <user-requested report path; during Codex Security final reporting use <scan_dir>/findings/<slug>/<slug>.md>
 
Treat the supplied finding as a hypothesis. Inspect the exact source revision yourself when available. If the user explicitly accepted a report-only assessment without source, identify that limitation, keep every source-dependent conclusion visibly conditional and never invent an excerpt or line citation. Otherwise, trace the actual attacker-controlled entry point, the reported state change, existing checks and the real sink. Reopen any source excerpt that ends before the decisive line. Do not substitute a different event, object, revision or test harness for the claimed trigger.
 
Open with the actual attack in ordinary language and say what it is not. Name Mallory's legitimate starting credential or input, the separate service, owner or policy she crosses, and the concrete protected sink she reaches. Put the complete tested prerequisites near the beginning and distinguish defaults from configured features without guessing prevalence.
 
When source and release history are available, trace when the vulnerable behaviour first appeared and inspect the relevant released versions, fixing change and backports. If the supplied checkout is shallow, obtain complete history or exact release archives when safely available rather than treating the gap as the answer. Write the report in terms of verified software versions; include a commit hash only when that specific change is important or a release number is unavailable. Clearly separate the earliest verified vulnerable version from an unproven first affected release, and identify unsampled patch releases or branch tips; state unavailable release evidence as a limitation in an explicitly accepted report-only assessment.
 
Before stating impact, challenge deployment assumptions, attacker privileges, cancellation, locks, cleanup, ordering, negative controls and alternative explanations. Say exactly which claims are established, which remain plausible and which the source contradicts. Correct the original notes when necessary. If the vulnerability does not hold, report the contradiction; do not manufacture a disclosure.
 
Use the user's requested language and locale, or their normal default when unstated, with a calm researcher-to-researcher voice. Use Alice for the legitimate owner, Bob for another legitimate user or intended recipient, Mallory for the active attacker and Eve for a passive observer, only when those roles fit. Carry the matching usernames through requests, shell commands, PoCs and output. Follow one cross-component causal story: first establish that the ordinary security policy is configured correctly, then show the shared state or failed check, the dependency behaviour it changes and the real protected sink. Explain what the software should do, what it actually does, why each important excerpt matters and what the evidence does not settle. Use "we" naturally to guide the walkthrough. Use "I" only to state the exact source review, builds, observations, experiments or limitations that actually occurred.
 
Never call evidence a "witness". Instead, tell the reader what it actually is and what it proves: the request returning Alice's data to Mallory, the input triggering the failure, the captured output showing the result, the test exposing the bug, or the source lines containing the missing check. If an essential real code identifier contains that word, preserve the exact identifier and immediately explain what it represents in plain English.
 
Follow the required report headings. Make the impact no broader than the demonstrated primitive. Discuss realistic stronger routes and useful dead ends only as clearly qualified analysis. Never guess affected versions, prevalence, CVSS, reliability, patch status or runtime results.
 
Include a real PoC only when available or safely and explicitly authorised. Separate exact source review, inspected PoC code, syntax or build checks, actual runs, preserved records, offline evidence verification, source-confirmed but unexecuted releases and expected-but-unobserved behaviour. A convenience reproducer assembled from a real fixture is not an executed exploit unless it was actually run. Include observed output only when observed; otherwise label the expected result and explain the missing execution condition. Use repository- or report-relative paths and commands. Never copy an author-machine-specific absolute path into the report, PoC, build recipe, screenshots, logs or output; preserve a verified absolute target-system path when it is necessary to explain or reproduce the vulnerability.
 
Before returning, reread the report against the PoC, fix and any available exact source and release history. When the user explicitly accepted a report-only assessment, verify that every unavailable source-dependent claim remains conditional. Remove generic filler, unsupported certainty, repeated commit hashes, jargon, inconsistent actor names, repetitive proof labels, token first-person phrases, author-machine-specific absolute paths and claims the artefacts cannot support.

For a rewrite, give the replacement worker the original evidence and precise failed checks, not merely the previous prose:

The previous draft incorrectly or inadequately handled <specific source, trigger, impact, validation or voice failures>. Re-establish each disputed claim against the pinned revision and original artefacts. Rewrite the explanation rather than adding qualifiers or first-person phrases to an unsupported narrative.

Source and exploitability standard

Prove the vulnerability in causal order. Establish the named actor and controlled input, show the real reachable entry point, explain what the software should prevent, carry the relevant value or object through each meaningful step, identify the check or behaviour that fails, and demonstrate the resulting effect at the real sink. In a cross-component finding, show the normal per-component protection first, then the shared key or state, the receiving library's decision and the downstream effect; explain why each excerpt changes the outcome. Quote only short, exact snippets that contain the decisive line. Cite the repository-relative path, function and verified release without repeatedly attaching commit hashes. Explain both what an excerpt proves and the material question it leaves open.

Compare a real fix only after verifying that it addresses the same vulnerable behaviour and actually prevents the reported attack. Distinguish a proposed defensive patch from an upstream fix. Establish introduction, affected-version boundaries, fixed releases and backports using inspected source history and released code; explicitly flag missing release history.

Explore stronger exploitation as research, not advertising. Discuss allocator or protocol behaviour, attacker-controlled bytes, timing, identity, configuration, useful primitives and meaningful dead ends when relevant. Distinguish a possible interleaving from production reliability, a bad state from a usable exploit, and local control from a real privilege or tenant boundary crossing.

Use a diagram or state table only when it clarifies a genuinely difficult object lifetime, ownership boundary or event sequence. Do not add visual material, theory or variants to make a simple finding look more impressive.

Report acceptance

Read references/report-format.md and the finished report yourself. Accept it only when:

• a new reader can understand the component, the named actors and the relevant security boundary;
• the verified release, configuration, attacker prerequisites and affected-version history are accurately scoped;
• the source establishes the same trigger sequence and security failure described in the report, or the user explicitly accepted a report-only assessment and every unavailable source-dependent claim remains visibly conditional;
• every excerpt is exact, attributed to a repository-relative source path and verified software version, necessary and explained;
• source proof, inference, reported claims and runtime observation remain distinguishable;
• meaningful guards, negative controls and alternative explanations are addressed;
• impact, exploitation reliability, affected versions and deployment prevalence are no stronger than the evidence;
• the PoC, commands, output and cleanup instructions reflect real artefacts and actual validation;
• available positive and negative controls rule out the important benign explanations and isolate any tested interim mitigation; when no authorized runtime or verified trace is available, clearly identify those controls as unperformed;
• the proposed fix explains in plain English what the code must do differently and suggests relevant regression coverage;
• the narrative sounds like a thoughtful human researcher, not a scanner, marketing copy or a checklist;
• each supporting observation is identified in concrete language, without calling unexplained evidence a "witness";
• Alice, Bob, Mallory and Eve are used only in their appropriate roles, with consistent example usernames;
• release numbers carry the explanation, and commit hashes appear only when they add specific value;
• we genuinely carries the explanation and I accurately describes performed work and its limits;
• the report and every distributed PoC, script, build file and output contain no author-machine-specific absolute paths, internal provenance, placeholder text or fabricated detail; retain an absolute target-system path when it is necessary to describe or reproduce the verified vulnerability.

Validate the report's Markdown, required headings, and any front matter against references/report-format.md; run an actual report-specific validator only when the repository supplies one. Search every distributable report, PoC, build file, script and captured output for author-machine-specific macOS, Linux and Windows absolute paths, including local user-home, temporary, checkout and file:// paths; remove those details without deleting absolute target-system paths that are essential to the verified behavior. Run relevant real PoC build or dry-run checks only when they exist, are safe and are supported by the target environment. When a disclosure package also contains an advisory, validate the technical report against the report-format reference without misclassifying the advisory or changing the final package layout. Re-run any supplied offline evidence verifier and ensure generated bytecode or local-path leakage does not enter the package. A word search can help identify accidental provenance or missing researcher voice, but neither a pronoun count nor required headings can establish factual accuracy.