Python wrapper around masscan and nmap for large-scale port discovery, host discovery, banner grabbing, and NSE-based vulnerability scanning across internal or external networks.
This script is a wrapper for masscan and nmap. nmap handles host discovery and (for smaller scans) port discovery, service banner grabbing, and NSE scripts. Masscan is used for large-scale port discovery where raw speed matters. Install both from your favourite package manager or from source.
Python 3.8+ is required (requires-python in pyproject.toml; CI floors at 3.8).
SpooNMAP can be run straight from a checkout — no installation step needed, see "Usage" below — or installed as a standalone command with uv:
uv tool install git+https://github.com/trustedsec/spoonmap
This puts a spoonmap executable on your PATH, so you can invoke it as
spoonmap from any directory instead of cloning the repo and running
./spoonmap.py. There is no PyPI package — this project has never
published to pypi.org, and the command above installs directly from the
git repository instead. Use the full git+https://... form above, not a
bare uv tool install spoonmap; whatever that name resolves to on PyPI, now
or in the future, is not this project.
To update to the latest commit:
uv tool upgrade spoonmap
Installing this way does not make SpooNMAP a self-contained scanner:
masscan and nmap are still separate system tools that must be installed
independently (see "Dependencies" above), exactly as when running from a
checkout — uv tool install only packages SpooNMAP's own Python code and its
bundled NSE scripts, not the external binaries it shells out to.
The one thing worth understanding before installing this way: an installed
spoonmap's Python module lives wherever uv put its managed tool
environment — not in a directory you would ever think to look in for a
config file or scan output. That is exactly the scenario the "Where Files
Live" section below is about — read that section for what resolves against
your current directory and why; installing via uv tool install doesn't
change the rule, it just makes the rule matter, since there is no checkout
directory left for a config or output path to fall back to by habit.
Simply executing the script will prompt you for all required options.
config.json, target/exclusion files, and scan output all resolve against
the directory you run the command from — see "Where Files Live" below if
your output isn't where you expect it, especially if you're used to invoking
SpooNMAP by path from outside its own directory.
If you use uv, you can run without a separate virtual environment:
uv run spoonmap.py
Or invoke directly if the script is executable:
# ./spoonmap.py
________ _____ _______ _________________
__ ___/______________________ | / /__ |/ /__ |__ __ \
_____ \___ __ \ __ \ __ \_ |/ /__ /|_/ /__ /| |_ /_/ /
____/ /__ /_/ / /_/ / /_/ / /| / _ / / / _ ___ | ____/
/____/ _ .___/\____/\____//_/ |_/ /_/ /_/ /_/ |_/_/
/_/
Service Categories (comma-separated numbers, default: All)
(1) Web [80, 443, 7001, 7002, 8000, 8080, 8081, 8443, 8888, 9090, 10443]
(2) Database [1433, U:1434, 1521, 3306, 5432, 6379, 9200, 27017]
(3) Remote Management [22, 23, 3389, 5900, 5901, 6129, 1723, 5985, 5986]
(4) Email [25, 110, 143, 465, 587, 993, 995]
(5) LDAP [389, 636]
(6) Network Infrastructure [53, 179, U:500, U:161, U:623, U:631, U:1194, 1194]
(7) File Transfer [21, 111]
(8) SMB [445, 135, 139, U:137]
(9) Specialized [1090, 3300, 4786, 6970, 2375, 4243, 9100, 8530, 8531]
(10) Containers & Debuggers [2377, 10250, 8001, 9229, 2345, 5005, 61616, 8009, 6000]
(11) Local LLM [11434, 1234, 7860, 5000, 5001, 1337, 3000, 8000, 8080]
(12) Full Port Scan [1-65535, TCP only — no UDP]
(c) Custom Port Scan [enter your own comma-separated ports]
(The Full Port Scan number increments automatically with the number of categories.)
**Full Port Scan is TCP only.** It sweeps TCP 1-65535 and runs no UDP discovery at
all, so every `U:` port listed in the categories above — SNMP (U:161), IKE (U:500),
IPMI (U:623), IPP (U:631), OpenVPN (U:1194), NetBIOS (U:137), SQL Browser (U:1434) —
is skipped, along with the NSE scripts and findings that depend on them. It is
*wider* than All on TCP and *narrower* on UDP. For both, run All and Full as two
passes, or use the Custom option with the UDP ports appended
(e.g. `1-65535,U:161,U:500,U:623`).
Which categories would you like to scan (e.g. 1,3 — default: All)?
Would you like to enumerate service banners for any identified services (default: Yes)?
Would you like to run NSE security scripts on identified services (default: No)?
Target Scan
(1) External
(2) Internal
Is this an internal or external scan (default: External)?
How fast would you like to scan (default: 20000 packets/second)?
Please enter the full path for the file containing target hosts (default: /opt/spoonmap/ranges.txt):
Would you like to exclude any hosts? (default: No)
Run host discovery before port scanning (default: Yes)?
Tune advanced settings (nmap threads, masscan batch size, nmap work-unit threshold)? (default: No)
You can also create a config.json file (based on config.json.sample) to skip all prompts:
{
"scan_categories": ["Web", "Database", "Remote Management"],
"banner_scan": "True",
"script_scan": "False",
"host_discovery": "True",
"target_scan": "Internal",
"max_rate": "2000",
"target_file": "ranges.txt",
"output_path": "./",
"exclusions_file": "exclusions.txt",
"nmap_threads": 5,
"masscan_batch_size": 5,
"nmap_threshold": 5000000
}
To scan all categories, set "scan_categories": "All".
To scan all 65535 TCP ports, set "scan_categories": "Full" — note this is TCP only and performs no UDP discovery.
For a fully custom port list, omit scan_categories and use "dest_ports": ["80","443","U:53"] instead.
UDP ports are specified with a U: prefix (e.g. "U:53").
When you answer the interactive prompts, the selected options are written to config.json before the scan begins. The generated file documents each editable field the same way config.json.sample does, and carries a __generated_by_prompts__ marker key. This means an interrupted interactive scan can be resumed the same way as a config-driven one — just re-run with --resume, and all prompts are skipped.
If a previous scan's output is detected in output_path, the tool offers three choices: [d]elete (remove the prior output and start fresh), [a]ppend (keep the prior output but re-run all phases), or [r]esume (keep the prior output and skip already-completed work, exactly as the --resume flag does).
Changing options on a re-run. Picking [d]elete or [a]ppend re-asks every option, with the saved config.json values pre-filled as the defaults — so pressing Enter through the prompts reproduces the previous scan, and you can change just the ports, rate, or targets you care about. [r]esume skips the prompts, since it is continuing the same scan. The re-prompt applies only to a config.json the tool generated (one carrying __generated_by_prompts__); a config you wrote by hand keeps the strict skip-all-prompts behavior described above. Remove that key to opt out, or delete config.json entirely to start from scratch.
Re-answering the prompts rewrites config.json, merging rather than overwriting: any keys you added to the file by hand are preserved.
To scan a single address (or a short list) without editing a target file, use --target:
./spoonmap.py --target 10.0.0.5
./spoonmap.py --target 10.0.0.0/24
./spoonmap.py --target 10.0.0.5,10.0.1.0/24,10.0.2.1-10.0.2.9