Organising large nmap scans into reports

On an engagement, you may have thousands of hosts in-scope that need to be scanned. This quickly gets out-of-hand because once those scans are finished, it becomes difficult to view and filter them out for plausible targets that are worth exploring.

For that, nmap XML outputs can be easily converted into HTML reports using xsltproc, and if you’re doing your scans in one-shot then this option is perfectly valid for you.

xsltproc nmap.xml -o report.html

To suit my workflow for how I perform my scans, this needed a few tweaks to get it working.

How I scan large IP blocks

If you had a long list of hosts to scan, you’d maybe use the -iL flag in nmap to do everything in one-go.

nmap -iL ips.txt -sS -vv -oA scans/

However, there are a couple of nuisances when doing scans this way in my opinion:

1. If you need to cancel your scans mid-way, you lose all your output results. I’m not sure why results don’t get appended as each host is being scanned, but this is the main drawback for me.
2. Your scan output files don’t get written until the full scan is finished, and if you’re scanning thousands of hosts, this could mean hours before you get any meaningful results.
3. If you messed up while interrupting your scan, you’re cooked.

For me, I like to split my list of IPs into smaller chunks, and then do my scans in batches. This lets me work on batches that finish earlier, while others are still running in the background.

# split into 30 lines chunks
split -l 30 ../ip-targets.txt

# then do the scans
mkdir -p nmapscans
for file in x*; do sudo nmap -sS -vv -oA nmapscans/$file -iL $file; done

Converting nmap XMLs into a report

Once the scans are done, you’ll end up with a bunch of x*.xml outputs. To combine them into a single XML, you can use xml-cat from xml-coreutils to concatenate them.

The easiest way to install xml-coreutils that I found was through homebrew.

xml-cat *.xml > combined.xml

To use the combined XML with xsltproc, we will need to replace the <root> nodes with <nmaprun>, and insert the XML stylesheet for nmap.

Here’s the script for automating those steps.

#!/usr/bin/env python3
import shutil
import argparse
import sys
import subprocess
import glob


def is_tool_available(name):
    """Check whether `name` is on PATH and marked as executable."""
    return shutil.which(name) is not None


def check_tools() -> bool:
    for tool in ("xml-cat", "xsltproc"):
        if is_tool_available(tool) is None:
            print(f"{tool} is not installed. Go install it.")
            return False
    return True


def run() -> None:
    parser = argparse.ArgumentParser(
        description="Parse nmap XML results into a HTML report"
    )

    parser.add_argument(
        "-d", "--directory", type=str, help="Directory containing nmap XML results"
    )

    parser.add_argument(
        "-o",
        "--output",
        type=str,
        default="report.html",
        help="Path to the output file (default: report.html)",
    )

    args = parser.parse_args()

    if len(sys.argv) == 1:
        parser.print_help(sys.stderr)
        sys.exit(1)

    if not check_tools():
        sys.exit(1)

    files = glob.glob(f"{args.directory}/*.xml")

    xml_results = subprocess.run(
        ["xml-cat", *files], stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
    ).stdout

    xml_results = xml_results.replace(
        "<root>",
        """<!DOCTYPE nmaprun>
<?xml-stylesheet href="file:///usr/share/nmap/nmap.xsl" type="text/xsl"?>
<nmaprun>""",
    )
    xml_results = xml_results.replace("</root>", "</nmaprun>")

    PARSED_XML = "nmap.xml"

    with open(PARSED_XML, "w") as f:
        f.write(xml_results)

    r = subprocess.run(
        ["xsltproc", PARSED_XML, "-o", args.output], capture_output=True, text=True
    )
    print(r.stdout)


if __name__ == "__main__":
    run()

You now have a nice HTML report to look through all your scan results :)