The best vulnerability report I ever received was three paragraphs long. It contained: a one-sentence summary of the issue, a minimal reproducer that I could run in under two minutes, and a clear statement of the impact. That was it. No preamble about the researcher's background. No history of prior disclosure attempts at other vendors. No speculation about how a sophisticated attacker might chain this with seven other vulnerabilities to achieve total system compromise. Just the thing, the evidence, and the impact.

I have also been on the receiving end of reports that ran to forty pages, included screenshots of the researcher's terminal going back three weeks, and buried the actual vulnerable function name in a footnote on page thirty-one. Those reports get triaged more slowly. Not because the vendor is being difficult, but because someone has to find the signal in all that noise, and that takes time.

This post is about the craft of writing vulnerability reports that vendors want to receive — not because it will get you a bigger bounty, but because the report is part of the work, and doing the work well matters.

The reader is not you

The most useful thing I can tell you about writing vulnerability reports is to keep the reader in mind at all times — and the reader is not you. You know what you found, how you found it, and why it matters. The reader does not. The reader is an engineer, probably busy, possibly context-switching between your report and four others, who needs to understand the issue quickly enough to decide whether it is urgent, who owns it, and what a fix would look like.

Everything in the report should serve that reader's needs. Background on your methodology: only if it is relevant to understanding the issue. A timeline of your investigation: only if it explains something about the bug. Your personal view on the severity: useful, briefly stated, not argued at length. The reader will form their own view; give them the evidence to do so, not a persuasion attempt.

The reproducer is the report

A vulnerability report without a reproducer is a hypothesis. A report with a working reproducer is evidence. The difference matters enormously to the person receiving it. A reproducer they can run themselves transforms the report from “someone claims this is a bug” to “I have confirmed this is a bug” in the time it takes to run the command.

The reproducer should be minimal. Not the script you used during your three-week investigation, with all the debugging output and commented-out variations. A new script, written after you understood the issue, that demonstrates the issue in the fewest possible steps. If the reproducer requires setup, document the setup. If it requires a specific OS version or configuration, state that. If it requires root, say so and explain why.

What to include, and what to leave out

Include: the affected component (be specific — file name, function name, line number if you have it); the conditions required to trigger the issue; the observed behaviour; the expected behaviour; the impact as you understand it; the reproducer; the version you tested on.

Leave out: your opinion of the vendor's previous handling of security issues; speculation about whether the vendor will fix it quickly; threats about disclosure timelines; the full history of everything you tried before finding the bug; screenshots of your desktop; anything that is not directly relevant to understanding and reproducing the issue.

The disclosure timeline question — when will you publish if the vendor does not respond? — is legitimate to include, but state it once, plainly, without drama. “I intend to publish technical details 90 days from the date of this report” is clear and appropriate. Everything beyond that is theatre.

A note on tone

The engineer reading your report almost certainly did not write the vulnerable code. They are not responsible for the bug existing. They are responsible for fixing it, and they will do that job better if the report treats them as a professional colleague rather than an adversary or a defendant.

Write as if you are handing something useful to a smart person who is on your side. Because, in the best case, that is exactly what you are doing. The vendor who fixes your bug well, credits you properly, and handles the disclosure cleanly is a vendor you want to work with again. That relationship starts with the report.