# Write vulnerability reports

> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

Use `$codex-security:vulnerability-writeup` to create a self-contained report
for each distinct vulnerability. You can start from Codex Security scan results
or use supplied findings, disclosure notes, PoCs, and source code directly. A
Codex Security scan isn't required.

## Prepare the evidence

Provide the workflow with:

- The findings, disclosure notes, or assessment documents to review.
- The target source tree and affected revision or release.
- Existing PoCs, logs, traces, screenshots, or diagnostic output.
- Fix commits or diffs when available.
- The authorization boundary for any testing.

Source access is important because Codex checks each claim against the affected
code before writing the final report. If the source or affected revision isn't
available, decide whether an explicitly labeled, lower-confidence report is useful
before proceeding.

## Run the workflow

Send a prompt like:

```text
Use $codex-security:vulnerability-writeup to create one self-contained report for each distinct vulnerability in [input paths]. Verify the claims against [source path and revision], preserve or improve the supplied PoCs, and write the reports to [output directory]. Do not test public or production systems.
```

Codex inventories the supplied material, groups reports that describe the same
root cause and vulnerable path, and creates one report directory per distinct
vulnerability. Each directory contains a descriptively named Markdown report
and a `poc/` directory when supporting PoC files are available.

## Review each report

Before distributing a report, confirm that it:

- Traces the bug from the attacker-controlled entry point to the broken
  security invariant and impact.
- Distinguishes verified behavior from hypotheses and unresolved constraints.
- Includes focused source excerpts with paths, functions, and the affected
  revision.
- Includes usable PoC source, build or run instructions, representative output,
  and safety limitations when a PoC is practical.
- Uses portable paths and doesn't depend on internal storage or local absolute
  paths.

Never test a public or production target unless you have explicit authorization
for that exact target.

## Use reports from a scan

Detailed vulnerability reports are optional for standard, deep, and change
scans. When you request them, Codex writes each report to
`findings/<slug>/<slug>.md`, stores supporting files under
`findings/<slug>/poc/`, and links the report from `report.md`.

Keep the complete scan directory together when sharing or archiving a scan. To
look for improvements that address patterns across the reports, continue
with [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening).