Vulnerability Writeup

Vulnerability Writeup

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.