skills/vulnerability-writeup/references/report-format.md

# Vulnerability Report Format

Write one self-contained Markdown report for a technically experienced security engineer who has not seen the original finding. The report should read like one careful researcher guiding another from the affected component and attacker prerequisites through the exact vulnerable source, demonstrated impact and appropriate fix.

Use the language and locale requested by the user, or their normal default when unstated, with a warm professional voice and direct technical language. Let `we` guide real reasoning: carry the same input, object or state between relevant excerpts and explain why each step matters. Use `I` only for what the author actually reviewed, built, ran, observed or could not test. Explain the expected behaviour and the actual failure in plain language.

During Codex Security final reporting, use `findings/<slug>/<slug>.md`, matching directory and filename exactly so `writeup.reportPath` satisfies the findings schema. Outside Codex Security final reporting, preserve the user's requested report directory and filename; when no filename is specified, choose a descriptive name such as `freebsd-shm-ftruncate-uaf.md`. Cite repository-relative paths, functions and verified release versions. Give fenced source excerpts the correct language. Use one natural source line per instruction paragraph or list item; do not hard-wrap Markdown prose in the middle of a sentence.

## Evidence and voice

Start with evidence, not confidence. Before calling a finding exploitable, establish the assessed software version, configuration, attacker capability, reachable path, the security behaviour that should have held and the narrowest demonstrated boundary crossing. Open with the actual attack in ordinary language: name Mallory's legitimate starting credential or input, the separate owner or policy she crosses and the real sink she reaches. Immediately state important non-claims, such as that she reused her own session rather than stealing someone else's or breaking a protocol. Treat supplied notes, unexecuted PoCs and reported traces as claims until the underlying source or runtime artefact is actually inspected.

Introduce classic named actors when they clarify the story: Alice is the legitimate owner, Bob is another legitimate user or intended recipient, Mallory is the active attacker, and Eve is a passive eavesdropper. Carry `alice`, `bob`, `mallory` and `eve` into example account names, requests, commands and PoC output. Introduce only the actors the actual vulnerability needs and preserve the product's real account roles and permissions.

Keep the differences between exact source, inspected PoC code, observed execution, supplied reports, inference and unknowns clear in natural prose. Do not mechanically prefix every sentence with an evidence label or add a generic confidence disclaimer to every section.

Do not describe supporting material as a "witness". Name the specific thing the reader can inspect: a source excerpt showing the missing check, Mallory's request for Alice's document, the server response disclosing that document, a failing test, an input that triggers memory corruption, a captured execution trace, or an observed PoC result. Explain what that particular example establishes. If a genuine source symbol or required field is literally named `witness`, quote it accurately and immediately explain its actual purpose.

Trace the vulnerable behaviour back to its introducing change, inspect release tags and maintained branches, and verify fixed releases or backports. Do not let a shallow checkout end the investigation when complete history or exact release archives can be obtained safely. Tell that history primarily through public version numbers, and explain what the introducing change was meant to fix when that explains the root cause. Give the first affected and first fixed release only when confirmed against actual release snapshots. When older tags, history or branch coverage are unavailable, say `the earliest version I could verify` rather than inventing a definitive affected range; name unsampled patch releases or branch tips instead of implying they were checked.

Do not invent an affected-version range, introduction date, fixed release, deployment prevalence, default configuration, reliable race, root shell, tenant crossing, CVE, CVSS score, log or expected result. A documented configuration establishes that the configuration exists; it does not establish that most deployments enable it. A timing-controlled test establishes a controlled ordering; it does not establish production reliability.

Avoid abstract security jargon, grand claims, dramatic severity language, marketing phrasing, repetitive signposting, empty praise, token `we can see` sentences and conclusions disconnected from the evidence. Describe what should have happened, what happens instead and why it affects Alice or benefits Mallory. Prefer the exact small fact that the source proves.

Do not fill the report with Git hashes. Pin the exact source privately, cite the public software version and relevant repository-relative path in the report, and mention a short commit reference only when a specific introducing or fixing change genuinely matters or when no released version exists.

Never include an author-machine-specific absolute filesystem path anywhere in the distributable report or PoC. This applies to prose, source citations, links, shell commands, build files, comments, screenshots and captured terminal output. Use repository-relative or report-relative paths and remove local user-home, temporary, checkout and `file://` paths from included material. Preserve an absolute target-system path such as `/etc/passwd`, `/proc`, `/dev`, or a Unix-domain socket when that path is necessary to describe or reproduce the verified vulnerability.

The final report must contain the following seven headings, in this order.

## Executive Summary

Name the component, assessed software version, required attacker position, essential configuration, vulnerable operation and narrowest demonstrated impact. State the verified first affected release, affected release range and fixed release when established by source history and inspected release snapshots. Distinguish the earliest release inspected from an unproven first affected version, and separate a plausible stronger effect from a demonstrated one.

Use the first paragraph to tell the concrete attack and its limits, not to announce a generic vulnerability class. Say who Mallory is, what legitimate access she starts with, which separate boundary should stop her, what happens instead and whether this is distinct from session theft, a protocol flaw or another tempting but unsupported explanation.

Include a truthful first-person statement of the validation basis. For example: `I reviewed the affected release, its earlier release history and the fix directly; I did not execute the trigger because no disposable test machine was available.` Do not imply that source review reproduced an exploit.

## Background

Introduce only the component behaviour, named actors, controlled values, ownership, privilege boundary and expected security behaviour needed to understand this finding. Put the complete tested topology and prerequisites near the beginning. Separate default behaviour from opt-in configuration and deployment assumptions without guessing prevalence.

If the attack involves similar objects or values, name them concretely and preserve that distinction throughout the report. For example, distinguish `alice`'s document from Mallory's authenticated `mallory` session. Include a short source excerpt only when it establishes the real entry point, security boundary or normal behaviour.

## Vulnerability Details

Follow the reported trigger in causal order. Begin with Mallory's actual controlled input. When source is available, inspect each material check or state change and show the precise line where the code fails to enforce the expected behaviour. When the user explicitly accepted a report-only assessment without source, describe the supplied trigger sequence as conditional, identify its actual evidence and unavailable checks, and never invent a source excerpt, line or observed state. First establish any verified ordinary policy or ownership check, then describe the evidenced shared state, receiving component or dependency decision and downstream operation without upgrading an unverified claim. Carry the same request, object, field or state through that whole path. When a named attacker does not fit the actual mechanism, describe the real actor without forcing the example.

For each available, verified source excerpt, identify its repository-relative source path, function and assessed software version. For a runtime-tested vendor or distribution package, verify excerpts and line numbers against that exact patched source; do not quote a nearby upstream tag as if it ran. Cite available dependency code in causal order and explain concrete log or trace fields in plain English. Quote only the lines necessary to establish the decisive behaviour, then explain what they prove and what remains unverified; omit source excerpts entirely when an explicitly accepted report-only assessment has no source. Refer to each demonstration by what it actually is, such as `Mallory's request`, `the returned document`, `the failing test` or `the execution trace`, rather than using an unexplained evidence label. Address relevant validation, locking, cancellation, cleanup, permissions, timing and alternative explanations rather than assuming they cannot prevent the path.

When release history is available, explain how the vulnerable behaviour entered the project and which released versions contain it; otherwise identify the unavailable history and do not guess affected releases. Use a commit reference only where the introduction or fix is materially relevant to that explanation.

If the exact source contradicts the claimed sequence, explicitly say so. Do not silently replace the finding with a nearby weaker bug or a more convenient test event.

## Exploitability Analysis

Start with the narrow primitive the evidence actually establishes. Explain which account, privilege, tenant, process, memory object or availability boundary it can cross under the verified prerequisites.

Discuss stronger exploitation routes only where the underlying source or authorised experiments support their premises. Explain meaningful constraints such as allocator behaviour, controllable bytes, protocol ordering, configuration, scheduling and cleanup. Label a possible chain or timing window as conditional when it has not been demonstrated.

When an authorized disposable target or a verified execution trace is available, include positive and negative controls that rule out the strongest alternative explanations: show normal allowed access, fresh rejection at the crossed boundary, same-domain success where relevant, the real sink reached only by the attack and any one-setting mitigation that was actually tested. Explain what each observed control rules out. When execution or a verified trace is unavailable, describe relevant controls as unperformed validation work rather than implying runtime observations. Do not turn ordinary reachability into remote code execution, an artificial interleaving into production reliability or a different identity into privilege escalation.

## Proof of Concept

Identify the real PoC artefacts, target requirements, build steps, execution safety and expected state. Use consistent example account names such as `alice` and `mallory`. Separate exact source review, preserved run records, offline evidence verification, PoC code that was inspected, a syntax or build check that succeeded, a convenience reproducer that was assembled but not run, source-confirmed releases and a run that was actually observed.

Use relative commands from the distributable report directory, for example:

```sh
cd poc
make
./poc
```

Include command output only when generated by the author or directly verified in a supplied trace. Explain what each request, response, test run or output line actually shows instead of referring to it as a "witness". Remove local absolute paths from genuine captured output without inventing results; visibly mark a necessary omission if it matters. If execution was unavailable or unsafe, say why; describe the unobserved result explicitly as expected behaviour, not a successful run. Never fabricate a crash, shell, leaked value, log or fixed-target result.

Explain any cleanup and warn clearly when a PoC could corrupt data, exhaust resources, crash a machine or change privileges. If no real PoC can safely be developed, explain the limitation instead of inventing an artefact.

## Remediation

Explain in plain English what the fixed code must do: for example, check that the requested document belongs to Alice before returning it to the signed-in user, or accept a resumed session only when the current effective authentication policy also accepts the identity recorded in it. Name every policy input that must remain distinct, preserve that distinction through serialisation or restoration and include it in shared lookup keys where relevant. Provide a small, source-compatible proposed fix when the surrounding source supports it, or cite and explain an inspected upstream fix. Clearly distinguish proposed remediation from a fix that has actually shipped and identify the verified fixed release when known.

Recommend regression tests covering the real entry point, the failing state transition, a meaningful negative control and nearby variants where justified. Suggest broader hardening only when it addresses the demonstrated mechanism.

## Summary

Restate the verified prerequisites, actual security failure, affected versions and demonstrated impact without upgrading any earlier conditional claim. Briefly identify the most useful remaining validation, exploitation question or related source path only when grounded in the evidence.

The report and every file in any sibling `poc/` directory must remain understandable outside the author's environment. Check all Markdown, source, scripts, build recipes and included output for personal-machine and other local absolute paths. Do not include internal storage locations, scanner implementation detail, drafting workflow or placeholders. If the final disclosure package also includes a separate advisory, keep its format separate and validate the technical report through an isolated temporary directory or link so the advisory is not mistaken for a second technical report.