// NMAPRS — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

nmaprs is a from-scratch Rust implementation of the nmap CLI dialect, with packet-level evasion, pipelined raw I/O on IPv4 + IPv6, and OS / version detection scored against nmap's own reference databases (nmap-os-db, nmap-service-probes). The CLI surface accepts the union of nmap --help and the long-option set from upstream nmap.cc — existing nmap scripts, integrations, and XML pipelines drop in unchanged.

What it does ship that vanilla nmap doesn't: async / parallel by default (no -T5 needed for "fast"), SOCKS4 + HTTP CONNECT proxy support for TCP connect scans, custom DNS resolution via hickory-resolver, sharded raw send/recv pipelines that scale to 16 concurrent shards per address family with race-free reply matching, and --resume JSON checkpoints across all scan types (TCP connect, UDP, raw half-open, IP-protocol, SCTP, idle, FTP bounce). What it doesn't ship: the NSE Lua runtime.

~SCAN ENGINE ARCHITECTURE

Per address family, raw scans spin up a dedicated recv thread blocking on poll(2), a sharded send pool (up to 16 concurrent shards), and a global rate limiter shared across IPv4 + IPv6. The recv-key registration happens before each send to eliminate the classic "reply landed before we knew to listen" race that ad-hoc raw scanners hit at high concurrency.

$PARITY MATRIX vs UPSTREAM NMAP

Every nmap flag that nmaprs actually parses (128 options) plus where it stops short of nmap's behavior. Numbers from the project's TRUTH TABLE in the README.

&SUBSYSTEM DEEP DIVES

// PIPELINED RAW SEND/RECV (16 SHARDS / FAMILY)

The naive raw scanner pattern — send packet; recv loop; classify — loses replies under load when the reply arrives before the recv loop registers the per-target callback. nmaprs's raw engine inverts the order:

1. Register the recv key first in a DashMap<(IpAddr, port, scan-type), oneshot::Sender>.
2. Then send the probe from the main thread of the shard.
3. The dedicated recv thread demuxes incoming frames against the registered keys and fires the matching oneshot.
4. Timeout falls back to filtered after the per-probe RTT cap.
5. Connect-mode fallback per address family kicks in when raw send fails outright (PERM, EAFNOSUPPORT, etc.) — not when probes individually time out.

Shard count defaults to min(16, effective_probe_concurrency()) per family. effective_probe_concurrency() is the bound between the timing template's parallelism estimate and explicit --min-parallelism / --max-parallelism / --min-rate floors.

// nmap-os-db SCORING

When -O is on, IPv4 is privileged, the scan found both open and closed TCP ports, and --datadir contains nmap-os-db:

1. Raw Layer-3 probes build a subject fingerprint — SEQ, OPS, WIN subsets implemented today; the full nmap probe set (T1..T7, ECN, U1, IE1, etc.) is in progress.
2. Each candidate nmap-os-db entry is scored via MatchPoints + expr_match — the same algorithm upstream nmap uses.
3. Top-scoring matches print with their OS: / Class: / CPE: values.
4. When raw probes or matching data are unavailable, falls back to ICMP TTL heuristic + example Class: titles from the legacy DB parse.

IPv6 OS detection currently uses only the TTL heuristic.

// nmap-service-probes MATCHER

The -sV path parses nmap-service-probes and runs probes parallel-per-open-port:

• TCP + UDP probe blocks — both directions.
• ports / sslports filtering — ports outside the probe's set are skipped.
• TLS via rustls when the port matches the probe's sslports.
• rarity vs --version-intensity — high-rarity probes are skipped at low intensity, identical to nmap's behavior.
• match / softmatch with full template fields — p/ (product), v/ (version), i/ (info), o/ (OS), d/ (device type), cpe:/ (CPE URIs).
• Perl-only regex features in the upstream patterns are detected and the matcher skips that entry — this is the source of the "partial" parity rating.

// EVASION AT PACKET LEVEL

Source-port spoofing, custom TTL, bad checksums, decoys, source-IP spoofing, custom payload (hex / string / random length), fragmentation (-f, --mtu), and MAC spoofing on ARP discovery frames are all wired into the raw IPv4 packet construction for -sS / -sN / -sF / -sX / -sM / -sA / -sW. These are not wrappers around an external scapy-style helper — they manipulate the packet bytes nmaprs writes to the raw socket.

!WHEN TO USE NMAP INSTEAD

If your workflow requires authoritative behavior of any of the items below, reach for upstream nmap:

• NSE Lua scripts — nmaprs ships banner + default Rust builtins, not the Lua runtime. Any script that ships with nmap (vuln checks, HTTP enum, SNMP, SMB, etc.) needs upstream.
• Full IPv6 OS detection — nmaprs's IPv6 OS detection is a TTL heuristic, not the IPv6 OS probe engine nmap has.
• Multi-round OS retry / --max-os-tries with adaptive intervals — nmaprs honors the flag but doesn't do the full retry behavior.
• The exact -oH hex dump format — currently a placeholder file in nmaprs.
• Service-probe entries that use Perl-only regex features — nmaprs's regex matcher skips them with a warning.

/SECURITY & ETHICS

Run nmaprs only against networks and hosts you own or have explicit written permission to scan. Unauthorized scanning is illegal in many jurisdictions. The author and contributors disclaim responsibility for misuse. This tool exists because Rust's memory safety + async runtime + raw-socket bindings combine to make a credible parallel scanner without C's footguns — not to make scanning easier for hostile actors.

#PROJECT METADATA