// 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 with the Nmap 2nd-gen probe set — SEQ, OPS, WIN, ECN, T1–T7, U1 (UDP), and IE (ICMP echo) tests assembled in os_scan.rs::probe_ipv4_os().
2. Each candidate nmap-os-db reference fingerprint is scored via MatchPoints + expr_match — the same algorithm upstream nmap uses (compare_fingerprints), driven by the in-tree c/expr_match.cpp binding (fp_match.rs) and the reference DB loaded by os_fp_db.rs.
3. Top-scoring matches print with their OS: / Class: / CPE: values.
4. When raw probes or matching data are unavailable, falls back to the ICMP TTL heuristic (os_detect.rs) + example Class: titles streamed from the DB parse (os_db.rs).

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.

// HOST DISCOVERY ENGINE

Discovery (discovery.rs) runs before the port scan unless -Pn / --no-ping is set. The default (no explicit -P*) fires raw ICMP echo in parallel with raw TCP SYN to ports 443 and 80, with a TCP-connect fallback when raw fails. Explicit probes carry nmap's default ports:

• -PS / -PA — raw TCP SYN / ACK; RST or SYN-ACK marks the host up; same sharded pipelines + connect fallback as the port scan.
• -PU (default 40125) — UDP / ICMP-style socket errors.
• -PY (default port 80) — SCTP INIT; INIT-ACK / ABORT → up; privileged; IPv4/IPv6 merged independently on partial failure.
• -PO (default protocols 1,2,4) — IP-protocol ping; open or closed → up; privileged.
• -PP / -PM — ICMP timestamp / address-mask requests (IPv4 only, Unix raw via icmp_ping.rs); reply → up; connect_timeout bounds the wait; skipped with a warning on non-Unix.
• -PR — ARP ping; auto on local IPv4 subnets unless --disable-arp-ping.

// IDLE & FTP-BOUNCE INDIRECT SCANS

• Idle scan (-sI zombie[:probeport], idle.rs) — spoofed TCP SYN with the source set to the zombie; sequential IP-ID sampling on the zombie (RST to a closed probe port, default 65535) keeps global IP-ID deltas interpretable; delta ≥ 2 → open, else closed; probe/RST failures → filtered (idle-probe-failed). IPv4 only; IPv6 targets are skipped with a warning.
• FTP bounce (-b user:pass@host:port, ftp_bounce.rs) — parallel buffer_unordered sessions, one control connection per probe, issuing PORT against a misconfigured FTP server; 150/125/250 → open, 425/426/421 → closed; IPv4 only; strict servers may yield filtered.

// 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