Masscan Inventory Scanner

A fast, parallel network inventory scanner powered by masscan. It reads IPv4 and IPv6 targets from a file, runs one scan per target, and writes normalized CSV, JSON, and text reports. Current version: 3.3.0.

Use this scanner only on networks that you are explicitly authorized to scan. High packet rates or large target ranges can disrupt systems and networks.

Features

• IPv4 and IPv6 addresses and CIDR networks, validated before scanning
• parallel masscan jobs with configurable rate and concurrency
• deduplicated targets and deterministically sorted inventory data
• raw and normalized results for every target
• aggregated inventory in CSV, JSON, and plain-text formats
• optional, bounded IPv6 splitting with protection against accidental expansion
• meaningful exit codes for automation
• no third-party Python runtime dependencies
• optional parallel reverse-DNS enrichment through explicitly configured resolvers

Requirements

• Python 3.10 or newer
• masscan 1.3 or newer available on PATH
• optional: the dns installation extra for reverse-DNS enrichment
• Linux: usually root privileges or suitable raw-socket capabilities

Masscan is not bundled with this project. Follow the upstream build and permission instructions.

Installation

From a checkout:

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .

This installs the masscan-inventory command. Alternatively, run the script directly with python masscan_inventory_scanner.py.

Install optional DNS support with:

python -m pip install ".[dns]"

Usage

1. Copy the example file and enter only authorized targets:

   cp targets.example.txt targets.txt

2. Start a conservative scan:

   masscan-inventory --targets-file targets.txt --ports 22,80,443 --rate 500

Important options:

-f, --targets-file PATH       target file (required)
-p, --ports PORTS             ports/ranges, such as 22,80,443 or 1-1024
-r, --rate RATE               packets per second per scan (default: 1000)
    --concurrency N            parallel scans (default: 4)
    --outdir PATH              base output directory
    --masscan-extra "..."      additional masscan arguments
    --ipv6-split-prefix N      explicitly enable IPv6 splitting
    --max-targets N            expansion limit (default: 4096)
    --dns-servers PATH         enable PTR enrichment with resolvers from a file
    --dns-concurrency N        parallel PTR lookups (default: 20)
    --dns-timeout SECONDS      total timeout per PTR lookup (default: 1.0)

The target file accepts one IP address or CIDR network per line. Empty lines, comment lines, and comments following a target are ignored. Hostnames and masscan range syntax such as 10.0.0.1-10.0.0.20 are deliberately rejected so that all input can be unambiguously validated.

IPv6 splitting

IPv6 networks are passed directly to masscan by default. Automatically splitting a /32 into /48 networks would create 65,536 processes and is therefore not a safe default. Enable expansion only when individual subnets are required:

masscan-inventory -f targets.txt --ipv6-split-prefix 64 --max-targets 256

The run stops before the first scan if the configured limit would be exceeded.

Optional DNS enrichment

DNS enrichment is disabled by default and does not affect the base scanner installation. Install the optional dependency, copy the example resolver file, and enable the enrichment stage:

python -m pip install ".[dns]"
cp dns_servers.example.txt dns_servers.txt
masscan-inventory \
  --targets-file targets.txt \
  --dns-servers dns_servers.txt \
  --dns-concurrency 20 \
  --dns-timeout 1.0

The resolver file accepts one IPv4 or IPv6 DNS server address per line. Empty lines, comments, and duplicates are ignored. PTR results use the statuses OK, NO_RECORD, TIMEOUT, and ERROR. DNS enrichment runs only after the scan inventory has been written; a DNS failure never discards the original scan results.

Output and exit codes

Every run gets a separate directory:

Masscan_Inventory_Scanner_YYYYMMDD_HHMMSS/
├── logs/
│   ├── masscan.log
│   └── errors.log
└── output/
    ├── <target>_masscan_output.json
    ├── <target>_parsed.csv
    ├── <target>_parsed.json
    ├── <target>_summary.txt
    ├── inventory_hosts.csv
    ├── inventory_hosts.json
    ├── inventory_hosts_report.txt
    ├── inventory_hosts_dns.csv   # only with --dns-servers
    └── inventory_hosts_dns.json  # only with --dns-servers

• 0: all scans completed successfully
• 1: at least one masscan job or result parser failed
• 2: configuration, input, or dependency error before scanning

CSV files retain their headers and JSON files remain valid empty arrays even when no open ports are found.

Development and quality checks

python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy masscan_inventory_scanner.py masscan_inventory_dns.py
pytest
python -m build
pip-audit -r requirements-dns.txt

CI runs these checks on every supported Python version. CodeQL and Dependabot provide static security analysis and automated updates for Python and GitHub Actions dependencies. A matching vX.Y.Z tag builds a wheel and source archive, attests the artifacts, and publishes them as a GitHub Release. See CONTRIBUTING.md and SECURITY.md for details.

Limitations

This project detects open ports and can optionally request PTR records. It deliberately does not perform service detection, vulnerability assessment, or operating-system fingerprinting. Results can be incomplete depending on permissions, platform, routing, and packet rate. Verify important findings with an appropriate authorized follow-up scan.

Migration from masscan_inventory_dns

The former heckpiet/masscan_inventory_dns repository has been incorporated into this project. Use the dns installation extra and --dns-servers instead of the former standalone script. Scan and DNS output filenames remain compatible, while the scanner core, tests, documentation, and release lifecycle are now maintained in one place.

License

MIT