~/tutorials/025-the-report-shape.md

025: The report shape

You have run the scans, counted at the joints, and written the limit clause. The last discipline of honest recon is the report: what a finding looks like written down, versus what it felt like when you found it. Most findings die in translation, and they die in one of two directions.

What you felt

The feeling of a finding is "nginx, obviously vulnerable, probably the thing". It arrives with certainty attached, no timestamp, and no provenance. It is not wrong, exactly. It is unusable: nobody can check it, including you, an hour later.

What a finding is

A finding is four fields, and every one of them comes from a command you can re-run:

1. What: the observation, in the tool's own words. A port, a version string, a record, a count.
2. Where: the target and the path, precise enough that the next person does not rediscover it.
3. When: the timestamp of the command, not of the writing. Snapshots are stamped for exactly this reason.
4. What it does not prove: the limit clause, lesson twenty, in your own words.

Build one now

nmap -sV 127.0.0.1 | grep 443

443/tcp open  ssl/http nginx 1.24.0 (Ubuntu)

The finding in shape:

> What: 443/tcp open, ssl/http, banner claims nginx 1.24.0 (Ubuntu). > Where: 127.0.0.1, this shell's snapshot of its own host. > When: snapshot stamped 2026-09-21; command re-runnable any time. > What it does not prove: that the running nginx is 1.24.0, that the port is open now, or that this version has no exposure. The banner is a claim by the service, and the snapshot is a moment.

Four lines, two commands, and every word checkable. The block quote is the shape to steal.

The census is a report too

for f in ~/news/*; do grep class: $f; done | wc -l

Twelve. A count is a finding with the same four fields, compressed: what (12 class lines across 11 files), where (~/news, all files), when (the tree as of this lesson's writing, aging as it grows), and the limit (one file says class twice, so the count is of lines, not files). A number without its limit clause is where reports go wrong, because twelve gets copied as "twelve findings" and the file that spoke twice becomes two incidents by morning.

Why the shape matters

The four fields are not bureaucracy. They are what makes a finding survivable: re-runnable by a stranger, dated by the machine, bounded by its own admission. Write findings this way and your report becomes a set of receipts. Write them from the feeling and your report becomes a set of opinions with your name on them, and the difference shows up the first time somebody re-runs your commands and gets different numbers. With the shape, that is corroboration of a stale timestamp. Without it, that is your credibility.

Try it

Each of these has one answer, and the shell gives it to you. Check yourself.

1. Write the four-field finding for port 22, using the -sV grep of your choice. The banner line is above for 443; produce its sibling.
2. Run the class census and write the finding for the count, limit clause included, before you read the next sentence. The limit is the double speaker.
3. Write a finding for something the scan refused to do. Refusals are findings too: what, where, when, and what the refusal proves about the boundary rather than the target.
4. Take any finding you have ever written elsewhere and rewrite it in the four fields. Notice what you had to leave out to make it fit. That residue is what your old reports were made of.

The snapshot is stamped, the tree grows, and the commands remain the current truth. A finding that says so is a finding that survives.