Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 31 ยท Exploitation Concepts and Reporting

Writing a Professional Security Report

Learn how to write a professional security report: executive summary, severity ratings, evidence, remediation advice and tone, with a Python stand-in that builds a report from structured findings.

A security test that nobody understands changes nothing. The best technical work in the world is wasted if the write-up is vague, scary without being useful, or so full of jargon that the people who control the budget cannot act on it. The report is the deliverable: it is what the customer paid for, what auditors read, and what engineers use as a to-do list months later.

That makes report writing a core skill, not an afterthought. This lesson covers the structure of a good report, how to describe a finding so it can be reproduced and fixed, how to assign severity honestly, and what tone to use. It follows The Penetration Test Lifecycle and uses the scoring ideas from Vulnerability Assessment Workflow. The runnable part generates a report from structured data, because consistent structure is exactly what makes reports good.

Two readers, one report

Leaders Want risk, impact and decisions.
Engineers Want steps to reproduce and fix.
Auditors Want scope, method and evidence.

Write one document that serves all three.

1 / 2

The structure of a report

Reports differ between firms, but a well-organized one usually contains these parts in this order:

  1. Cover and document control: customer, title, dates, version, author, classification ("Confidential"), and a distribution list. Reports contain a map of the customer's weaknesses, so they are sensitive documents.
  2. Executive summary: one page for non-technical readers (see below).
  3. Scope and methodology: what was tested (exact addresses, applications), what was excluded, the test dates and windows, the type (black, grey or white box), the standards followed (PTES, NIST SP 800-115, OWASP) and any limitations ("production database not tested").
  4. Findings summary: a table of all findings with severity, so a reader sees the whole picture on one page, often with a count by severity.
  5. Detailed findings: one section per finding, sorted by severity.
  6. Positive observations: things done well. This is not flattery. It tells the customer what to keep doing and builds trust in the rest of the report.
  7. Conclusion and next steps: an overall assessment and a recommended order of work, including a retest.
  8. Appendices: tools and versions used, raw scan output, a list of tested hosts.

The executive summary

This is the page most people will read, and sometimes the only one. Write it last, and write it for a reader who has two minutes and no technical background. A good executive summary contains:

  • Purpose and scope in one or two sentences.
  • The overall result in plain language: "We were able to gain access to the internal network from the internet through a forgotten test server."
  • The business impact: what could an attacker do with this? Customer records, downtime, legal exposure, reputation.
  • The few things to fix first (three to five at most).
  • A rating or count of findings by severity.

Avoid acronyms, tool names and command output here. Compare "The server is affected by a flaw with a CVE number" with "An old, publicly known flaw in the customer portal lets an outsider read other customers' invoices." The second tells a manager why to care.

Anatomy of a finding

Every finding should answer the same questions in the same order, so readers learn the layout once. A reliable template:

Part What it contains
ID and title F-03: Customer portal exposes other customers' invoices. Say what is wrong, not "Critical issue found".
Severity The rating and the reasoning (see below).
Affected assets Exact hosts, URLs, parameters or versions.
Description What the weakness is and why it exists, in a few sentences.
Impact What an attacker could achieve, in terms of the business.
Evidence Steps to reproduce, sanitized output, screenshots. Show enough for an engineer to see it for themselves.
Remediation Specific, actionable fixes, ordered by effort and effectiveness, with links to vendor or standards guidance.
References CVE, CWE or OWASP identifiers, so people can look up more.

Some notes on getting each part right:

Evidence. Include the request and the response, or the command and the output, with times. Redact passwords, tokens and personal data: the report itself must not become a leak. Make the steps numbered and complete so a new engineer can reproduce them. A finding that cannot be reproduced gets argued with; one that can gets fixed.

Remediation. "Improve security" is not advice. Compare it with "Use parameterized queries for the invoice_id parameter in /portal/invoice (see the framework's query-builder documentation) and add an authorization check that the invoice belongs to the signed-in user." Give a short-term mitigation (for example a firewall rule) when the permanent fix will take time.

Root cause. Where several findings share one cause (no patch process, no input validation standard) say so. Fixing the cause removes whole groups of findings and is the most valuable advice in the report.

Rating severity honestly

Severity tells the customer in what order to work, so the rating has to be defensible. Two common approaches:

  • CVSS gives a number from 0 to 10 based on measurable properties (how easy it is to exploit, what privileges are needed, the effect on confidentiality, integrity and availability). It is consistent, but it describes the flaw in general, not your customer's situation.
  • A simple risk matrix combines likelihood (how easy and how probable?) with impact (how bad for this business?) into Critical, High, Medium, Low and Informational.

Most reports use CVSS as a starting point and then adjust for context, and state that they did: a flaw on an internal-only test machine with no data deserves a lower rating than the same flaw on the public payment server. Do not inflate ratings to look impressive, and do not shrink them to avoid an awkward conversation. Credibility is your only asset.

A typical set of labels:

Rating Meaning Typical response
Critical Easy to exploit, severe impact, often internet-facing Fix immediately
High Serious impact or fairly easy to exploit Fix within days to weeks
Medium Limited by conditions or modest impact Fix in the normal cycle
Low Minor impact or hard to exploit Fix when convenient
Informational Hardening advice, no direct risk Consider

Tone and language

The reader may be the person who built the system. Your report should make them want to fix it, not defend it.

  • Describe the system, not the people. "The application does not validate the parameter" rather than "the developers failed to validate".
  • Be precise and calm. Avoid hype ("catastrophic", "trivially hacked") and fear. Facts and impact carry more weight.
  • Say what you did not test. An honest limitation avoids false comfort. A clean result means "we found nothing in the time and scope given", not "it is secure".
  • Be consistent. The same words mean the same thing throughout; define terms in a short glossary.
  • Use plain language where you can, and keep the technical depth in the finding sections.
  • Proofread. Wrong addresses, a copy-pasted name of a different customer or an inconsistent count of findings destroy trust faster than a missed bug.

Finally, handle the document as sensitive: encrypt it, share it only with named recipients through a secure channel, and follow the retention terms agreed in the contract. If you found something so serious that it cannot wait for the report, call the emergency contact first.

A stand-in: generate a report from structured findings

Good reports are consistent, and consistency is easier with structure. Real teams use reporting platforms or templates that fill in parts of the document. This stand-in does the same with plain Python: findings are data, and the report is generated from them, sorted by severity, with a summary count. The findings are invented.

Python Build a report from findings data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The critical finding appears first even though it was listed last in the data. Sorting by a defined order is a small detail that makes the document match the reader's priorities.

A stand-in: check a finding for missing parts

A review pass catches thin findings before the customer does. This stand-in checks that every finding has the required fields, a known severity, and remediation text that is not just a vague phrase.

Python Review findings for quality

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Automated checks cannot judge whether a finding is true or well written, but they catch the embarrassing errors cheaply. A human reviewer (a second tester) should still read every report before it leaves the building.

After delivery

The report is not the end. Schedule the debrief, answer questions without defensiveness, and agree who owns each fix. Offer the retest (The Penetration Test Lifecycle), and update the report with the results as an addendum rather than silently rewriting history. Keep your own working files secure and delete them when the contract says to.

Reports improve fastest when you read other people's good examples, keep a library of well-written finding texts (without customer details), and ask for feedback from the engineers who used your advice.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Who is the main audience of the executive summary?

    The summary is written in plain language for people who decide on budget and priorities. Technical detail belongs in the finding sections.
  2. 2. Which remediation advice is best?

    Good advice is specific, actionable and tied to the affected component, so an engineer knows what to change.
  3. 3. A scanner gives a CVSS score of 9.8, but the flaw is on an isolated test machine with no data. What should the report do?

    CVSS is a starting point. Adjusting for context is fine when the reasoning is shown, because the rating is meant to help prioritize.
  4. 4. Why include a section on positive observations?

    Recording what is done well helps the customer protect those practices and shows the assessment was balanced.
  5. 5. What should a report say about areas that were not tested?

    Limits must be stated. A clean result only covers what was tested in the time available.

Summary

  • The report is the deliverable: it must work for leaders, engineers and auditors at the same time.
  • Structure: cover, executive summary, scope and method, findings table, detailed findings, positive observations, conclusion, appendices.
  • Each finding has an ID, title, severity, affected assets, description, impact, reproducible evidence, specific remediation and references.
  • Rate severity with a stated method (CVSS or a risk matrix), adjust for context and explain it. Never inflate or shrink it.
  • Keep a calm, precise tone, describe systems rather than people, and state the limits of the test.
  • Treat the report as a sensitive document: redact secrets, share it securely and follow the retention terms.
  • The Python examples generate and review a report from invented structured data as stand-ins for reporting tools.

Next: Project: Security Log Analyzer.