Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: Write a Scan Report

Create a professional scan report from Nmap XML: executive summary, findings with severity, evidence and recommendations, generated as Markdown and HTML with Python.

Raw scan output is for specialists. The people who must act on a scan, such as managers, system owners and administrators, need a report: what was tested, what was found, how serious it is and what to do. Writing clear reports is half of professional security work. In this project you turn parsed Nmap XML into a short report with an executive summary, a findings table and recommendations, in both Markdown and HTML, all with Python.

The data is sample data for documentation addresses. Run the final program on your own authorised scan results to get a real report.

What a good report contains

  1. Scope and method: what was scanned, when, with which options, and any limits (for example "TCP top 1000 ports only").
  2. Executive summary: three to five lines for decision makers: number of hosts, number of findings per severity, the single most important action.
  3. Findings: each with an ID, severity, affected hosts, evidence (the actual line from the scan), why it matters and how to fix it.
  4. Appendix: the full inventory, the exact command lines, and file names of raw output.
  5. Caveats: a scan is a snapshot from one vantage point; filtered ports hide the truth and version strings can mislead.
flowchart LR
    X["Nmap XML"] --> P["Parse"]
    P --> R["Apply finding rules"]
    R --> S["Sort by severity"]
    S --> M["Markdown / HTML report"]

From scan data to a readable report.

Step 1: define findings as rules

Each rule has a check, a severity, a title, an explanation and a fix. Keeping this in a table makes the report consistent and easy to extend. The checks work on parsed service information.

Python Finding rules applied to scan 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.

Step 2: write the Markdown report

The generator below produces the whole document: header, executive summary with counts, a findings table and, per finding, evidence, reasoning and the fix. It groups affected hosts per rule so the report does not repeat itself.

Python Generate the Markdown report

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.

Step 3: HTML output (safely)

HTML is convenient for sharing. The key rule: escape everything that comes from scan data. A banner or script output is attacker-influenced text, and a banner like <script>... would otherwise run in the reader's browser. Python's html.escape makes text safe.

Python Escape scan data in an HTML report

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.

Writing quality: tips

  • Lead with impact. "Anyone on the office network can read the customer database port" beats "port 3306 open".
  • Give evidence, not opinions. Paste the exact scan line, with date and command, so others can reproduce it.
  • Rank honestly. If everything is "critical", nothing is. Define severity levels (impact and likelihood) and apply them evenly.
  • One fix per finding, written for the owner of the system: concrete, with the command or setting if possible.
  • Mention what you did not test. Ports outside the scan, UDP, hosts that were down, and anything out of scope.
  • Protect the report. It is a map of weaknesses. Share it only with those who must fix them.
  • Re-scan after fixes and mark findings as resolved, using the comparison methods from Automating Scans and Comparing Results.

Extensions

  1. Read the findings straight from XML with the code in Parsing XML Output.
  2. Add a "resolved since last scan" section.
  3. Add CVSS-style scores or your own risk matrix.
  4. Add a hosts appendix using the inventory project: Network Inventory.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What belongs at the top of a report for decision makers?

    Readers who stop after a few lines should still learn the main result and what to do first.
  2. 2. Why must scan data be escaped in an HTML report?

    Text collected from remote systems is untrusted. html.escape turns markup into harmless text.
  3. 3. What is good evidence for a finding?

    Exact lines let owners and reviewers reproduce and verify the finding.
  4. 4. Why include a limitations section?

    Honest limits prevent false confidence: 'nothing found' does not mean 'nothing exists'.

Summary

  • A report states scope, method, an executive summary, findings with evidence and fixes, and limitations.
  • Express findings as rules over parsed data so reports stay consistent.
  • Escape all scan-derived text before putting it into HTML.
  • Rank honestly, write for the system owner, protect the report and re-scan after fixes.

Next: Nmap Practice and Cheat Sheet