Finding descriptions

The description is the technical body of a finding. It should let another engineer understand what we found, how we got there, and how to verify it themselves.

See also Report writing, Finding titles, and Screenshots.

Goal

A good description:

• Contains all essential information needed to understand and reproduce the issue.
• Follows a clear path from observation to conclusion.
• Walks through the path as a clear sequence of actions, usually in narrative prose rather than a numbered list.
• Stays factual and does not defame anyone.
• Explains unfamiliar technology in a short paragraph when needed.
• States limitations openly when we could not fully investigate.

Quick rules of thumb

• Write in past tense and prefer active voice (see Report writing).
• Write a step-by-step path in narrative prose. Prefer sentences that lead the reader through what we did, not a default 1., 2., 3. list. Number steps only when a list genuinely helps, for example a long reproduction sequence with many tools or commands.
• Tailor every description to the client's environment. Include their actual hostnames, paths, and roles.
• Redact sensitive data (tokens, passwords, names of uninvolved people). See Report writing and Screenshots.

Walk the reader to the conclusion

The description is not a list of disconnected facts. It is a short narrative that answers: how did we know this was a real issue?

A clear path usually looks like this:

• We started from X (entry point, account, or exposed surface).
• We tried Y (specific action or payload).
• The application responded with Z (error, unexpected data, or elevated access).
• Therefore, an attacker with the same preconditions could ...

Avoid jumping straight to the impact without showing how we reached it. If we chained multiple weaknesses, explain each link in order.

Example (good narrative flow)

During testing of the customer portal at app.example.com, we logged in as a standard user. After authentication, the application set a session cookie named SESSION that contained a plaintext userId field. We changed the userId value from our account identifier to the administrator's identifier, and resent it with a request to /portal/admin. The server accepted the modified cookie and returned the administrator dashboard. This shows that the application trusts the user identifier inside the session cookie without server-side validation. The userId in the session cookie could be changed to any user, including administrators; therefore, authenticated attackers could take over the application.

The path is clear without numbering: login, observe the cookie, change a value, resend, observe the result, conclude. Prefer this narrative style for most findings. Additionally, add screenshots where it matters.

Example (too abrupt)

The application suffered from insecure session management where users could impersonate other users by changing a cookie value. Authenticated attackers could therefore take over administrator accounts.

The second version states a conclusion without the path and is too vague. The reader cannot verify or reproduce it.

Reproduction steps

Reproduction steps belong in the description. They should be complete enough that another technical person can repeat the test. Write them as a continuous narrative that shows order and outcome, not as a numbered checklist by default.

Include:

• Preconditions (account type, network access, required tools, limitations).
• Exact URLs, HTTP methods, headers, or commands.
• Payloads or parameter values we used.
• What the reader should expect at each step (status code, response snippet, UI change).

Use 1., 2., 3. only when numbering makes the sequence easier to follow than prose, for example many discrete commands or a long multi-tool chain. Most findings read better as paragraphs that still move step by step.

Explain unfamiliar technology

If understanding the finding requires niche or highly specific knowledge, add a short background paragraph (two to three sentences) before the technical details. Explain what the technology is and how it is used in this environment.

Write for an engineer who may not work with that stack every day.

Example

Background: Azure AD Conditional Access policies evaluate sign-in requests against rules such as device compliance and location. In this engagement, remote access to the VPN relied on a policy that only checked group membership, not device state.

Keep background paragraphs factual and short. Do not turn them into product documentation.

Stay factual

Descriptions are often read by engineers and developers. Write about systems, configurations, and behaviors and not about people's competence or intent.

• Attribute issues to missing controls, misconfigurations, or code flaws, not to individuals.
• Do not name employees, contractors, or third parties unless it is strictly required to reproduce the finding (and even then, prefer roles: "a domain administrator account" instead of a person's name).
• Avoid blame language ("negligent", "incompetent", "obviously broken"). State what we observed and what it enables.
• Do not speculate about why someone made a decision unless we have direct evidence. "The setting was enabled" is fine; "the admin carelessly enabled" is not.
• Do not assign business, compliance, or reputational impact beyond what we verified in testing. That is for the client to assess.

Be transparent about limitations

If we could not fully confirm something, say so plainly. Partial findings are still worth reporting when we explain the gap.

Examples:

• "Due to time constraints, we did not verify whether this issue affects all tenant environments."
• "We confirmed read access to the endpoint but did not attempt to modify production data."

Transparency builds trust. It also helps the client prioritize follow-up work.

What to include in every description

At minimum, make sure the reader can answer:

Question	Example detail
Where?	Hostname, URL path, API endpoint, AD object, or file path
What?	Vulnerability type or misconfiguration (linked to the title)
Who?	Required access level: unauthenticated, standard user, admin
How?	Steps, tools, and payloads we used
Proof?	Screenshot, request/response, or command output

Common mistakes

• Generic copy-paste text that does not mention the client's systems.
• Missing preconditions, so the reader cannot reproduce the issue.
• Default numbered lists (1., 2., 3.) for every action when prose would already make the order clear.
• Walls of text that hide the sequence of what we did and what happened next.
• Conclusions without evidence, or evidence without explaining what it proves.
• Buried key detail, the affected URL or account type hidden in a long paragraph.
• Sensitive data left in screenshots or request dumps.

Further reading

• OWASP Web Security Testing Guide — Reporting
• Google Tech Writing Course