Spoonmap from trustedsec wraps masscan and nmap into an interactive, resumable scanning pipeline for authorized network reconnaissance and vulnerability triage work.
| Tool | trustedsec/spoonmap — Python wrapper orchestrating masscan and nmap for large-scale port discovery, host discovery, banner grabbing, and NSE-based script scanning |
| Category | Network reconnaissance / scanning orchestration (Python, 208 stars) |
| Primary Use | Authorized external or internal network assessments: service-category port scans, banner enumeration, and NSE script triage driven by masscan speed with nmap depth |
| Safe Use | Use only against networks you own or are explicitly authorized to assess, such as contracted penetration tests, internal asset inventories, and lab environments |
| Telemetry Note | Generates high-pps SYN traffic from masscan (default 20000 packets/second) plus nmap probes, both highly visible to IDS; writes config.json, cli_targets.txt, and nmap_results/ XML files on disk, leaving a clear record of scan scope |
Spoonmap is trustedsec's answer to a problem every operator knows: masscan is blisteringly fast but shallow, nmap is thorough but slow, and gluing them together with shell scripts gets unwieldy at engagement scale. The tool, written in Python 3.8+ (the CI floors at 3.8 per pyproject.toml's requires-python), is a wrapper that delegates the right job to the right engine: nmap handles host discovery and, for smaller scans, port discovery, service banner grabbing, and NSE script execution, while masscan takes over large-scale port discovery where raw speed matters. The README is unusually candid about the division of labor, which tells you the authors have actually run this against real, large ranges rather than treating it as a toy.
The first thing that stands out operationally is the port taxonomy. Rather than asking you to memorize port lists, the interactive prompt presents twelve service categories — Web, Database, Remote Management, Email, LDAP, Network Infrastructure, File Transfer, SMB, Specialized, Containers & Debuggers, and a notably contemporary Local LLM category covering ports like 11434 (Ollama), 1234, 7860, and 5000. That last category is a strong signal of the tool's currency; exposure of local inference endpoints is a live concern in modern internal assessments, and few scanners of this vintage bother to enumerate them. UDP-heavy infrastructure ports — SNMP at U:161, IKE at U:500, IPMI at U:623, IPP at U:631 — are prefixed with U: and folded into the relevant categories, which matters because the Full Port Scan option is explicitly TCP-only, a limitation the README calls out twice.
The interaction model is prompt-driven by default: running ./spoonmap.py with no arguments walks you through categories, banner enumeration (banner_scan), NSE script scanning (script_scan), internal versus external target mode, scan rate (default 20000 packets/second), a target file (default /opt/spoonmap/ranges.txt), exclusions, host discovery, and advanced tuning knobs like nmap_threads, masscan_batch_size, and nmap_threshold. For repeatable authorized engagements, everything moves into a config.json derived from the bundled config.json.sample, which suppresses all prompts — handy for running from a jumpbox where interactivity is painful. Custom port lists are supported via a dest_ports key, mixing TCP and UDP entries like "80","443","U:53".
Installation is deliberately PyPI-free. There is no published package — the README emphatically warns that whatever spoonmap resolves to on pypi.org now or later is not this project — so the supported path is uv tool install git+https://github.com/trustedsec/spoonmap, which drops a spoonmap executable on your PATH. Crucially, this does not vendor the engines: masscan and nmap remain system dependencies you install yourself, and the wrapper only packages its own Python code plus its bundled NSE scripts. Running from a checkout is equally valid via uv run spoonmap.py.
The resume machinery is where the engineering quality shows. --resume reuses completed host and port discovery whose output is newer than resolved_targets.txt, skips nmap_results/portN.xml files unconditionally, and — the clever part — automatically invalidates cached discovery when ranges.txt changes, because resolved_targets.txt only gets rewritten when the resolved target set actually shifts. That timestamp-cascade design means you can add ranges mid-engagement without silently missing them, a failure mode that has bitten everyone who has scripted masscan by hand. Interactive answers are persisted to config.json with a __generated_by_prompts__ marker, so an interrupted prompt-driven run resumes exactly like a config-driven one, and re-answered prompts merge rather than clobber hand-added keys.
Ad-hoc targeting is handled by --target, which accepts bare IPs, CIDR notation, A-B ranges, and address netmask forms, comma-separated. The README documents a refreshingly honest piece of history: before the move to argparse, the hand-rolled '--flag' in sys.argv parsing silently ignored --target=10.0.0.5 (the = form) and — worse — fell through to scanning ranges.txt instead, silently changing scope. That class of bug is exactly the kind that gets an operator outside their authorized boundary, and the fact that the project both fixed it with argparse (typo'd flags now abort with a non-zero exit) and documented it in the README is a good trust signal. Targets passed this way land in cli_targets.txt while ranges.txt is never modified, preserving your engagement scope file as a clean record.
Hygiene details extend to update checks. The tool makes no network connections beyond the scan itself unless you opt in — the authors explicitly note it is routinely run from jumpboxes inside client networks, where an unprompted call to api.github.com would be unwanted engagement-host traffic. --check-update is the on-demand path, "check_for_updates": true in config.json enables it at startup, and only stable releases are advertised — nightly release candidates never surface as updates. --version reports from package metadata derived from git tags, printing unknown (running from source) from a checkout, which is documented as expected behavior rather than an error.
Where files live is another README section worth internalizing before you install: config.json, target and exclusion files, and scan output all resolve against your current working directory, not the module's install location. With uv tool install, the Python module sits in uv's managed environment where you'd never look for output, so the relative-resolution rule matters more, not less. --cleanup removes scan data non-interactively, taking its path from output_path or an explicit argument. On re-runs, the tool detects prior output and offers [d]elete, [a]ppend, or [r]esume, with delete and append re-asking every prompt with previous values pre-filled as defaults — press Enter to reproduce, tweak one field to adjust.
From a defensive perspective, everything spoonmap does is loud by design. masscan at the default 20000 pps trips rate-based IDS rules almost anywhere, and the follow-on nmap banner grabs and NSE scripts are fingerprintable. The on-disk artifacts — config.json, cli_targets.txt, resolved_targets.txt, nmap_results/*.xml — mean the tool leaves a precise audit trail of what was scanned and when, which is a feature for engagement documentation and for blue teams reconstructing activity afterward. As with any scanner, the authorized-use framing is non-negotiable: this belongs in contracted assessments, internal asset inventory work, and labs, pointed only at ranges you own or are scoped to test.
Spoonmap occupies a specific niche: not a framework, not an exploitation platform, just a well-engineered orchestration layer that makes the masscan-then-nmap two-phase workflow resumable, repeatable, and scope-safe. The README's attention to edge cases — flag parsing bugs, file resolution, update-check telemetry, TCP-only full scans versus UDP categories — reads like it was written by people who have been burned in the field, and that documentation quality is itself a reason to consider it for your next authorized internal or external assessment.
trustedsec/spoonmap.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.