nmaprs 0.1.3

 ███╗   ██╗███╗   ███╗ █████╗ ██████╗ ██████╗ ███████╗
 ██╔██╗ ██║████╗ ████║██╔══██╗██╔══██╗██╔══██╗██╔════╝
 ██║╚██╗██║██╔████╔██║███████║██████╔╝██████╔╝███████╗
 ██║ ╚████║██║╚██╔╝██║██╔══██║██╔══██╗██╔══██╗╚════██║
 ╚██╗ ╚██╔╝██║ ╚═╝ ██║██║  ██║██║  ██║██║  ██║███████║
  ╚═╝  ╚═╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝

[RUST GRID SCANNER // NEON WIRE // PARALLEL SOCKETS // NMAP-SHAPED CLI]

┌──────────────────────────────────────────────────────────────┐ │ STATUS: ONLINE    THREAT LEVEL: NEON    SIGNAL: ████████░░ │ └──────────────────────────────────────────────────────────────┘

"Every port has a story. We read them all in parallel."

[0x00] OVERVIEW

nmaprs is a Rust-native network scanner that speaks nmap's CLI dialect (nmap --help plus the long-option set from upstream nmap.cc, e.g. --resolve-all, --defeat-rst-ratelimit, --versiondb, --oM / --oH, --vv, --proxy as an alias of --proxies). Evasion flags (-g source port, --ttl, --badsum, -D decoys, -S source spoofing, --data/--data-string/--data-length, -f/--mtu fragmentation) are wired at the packet level for raw TCP scans. --proxies routes TCP connect scans through SOCKS4 or HTTP CONNECT proxies; --dns-servers resolves targets via custom DNS servers (hickory-resolver); --spoof-mac spoofs the source MAC on ARP discovery frames; --stats-every prints periodic scan progress with ETC and probes/sec. Multiple -iL lines and CLI targets resolve in parallel (order preserved) with the same --max-parallelism / --min-parallelism / timing template cap as port probes. It is not a byte-for-byte reimplementation of Nmap: the full NSE Lua runtime is not embedded. IPv4 -O runs raw TCP/IP probes (SEQ/OPS/WIN subset plus extras in progress), builds a subject fingerprint, and scores nmap-os-db reference entries with MatchPoints + expr_match (not every Nmap probe or field is implemented yet). With Nmap's nmap-service-probes and nmap-os-db files under --datadir (default ./data), -sV runs TCP and UDP probes with ports / sslports filtering, tls (rustls) for probe sslports, rarity vs --version-intensity, and match / softmatch handling (Rust regex; Perl-only patterns skipped). -O falls back to ICMP TTL heuristics and example DB titles when raw probes or matching are unavailable. This tool implements real TCP connect, UDP probes, ICMP ping discovery, raw IPv4/IPv6 half-open TCP including SYN / NULL / FIN / Xmas / ACK / Window / Maimon (privileged), target list / random hosts, IPv6, resume checkpoints, traceroute, and built-in Rust "scripts" (banner grab) for --script / -sC.

Created by MenkeTechnologies.

[0x01] TRUTH TABLE // READ THIS

┌──────────────────────────────────────────────────────────────┐ │ SCAN CAPABILITY MATRIX // IMPLEMENTED vs PARTIAL vs PLANNED │ └──────────────────────────────────────────────────────────────┘

If you need authoritative Nmap NSE/OS DB behavior, use Nmap.

[0x02] BUILDING THE PAYLOAD

cargo build --release

Binaries: target/release/nmaprs and target/release/nms (same CLI and behavior; nms is a short alias).

Install the man pages (short + full reference):

sudo cp man/man1/nmaprs.1    /usr/local/share/man/man1/
sudo cp man/man1/nmaprsall.1 /usr/local/share/man/man1/
man nmaprs        # short reference (key flags, examples)
man nmaprsall     # full reference (every scan technique, parity matrix, examples)

[0x03] ZSH COMPLETION // TAB-COMPLETE ALL THE THINGS

completions/_nmaprs completes nmaprs and nms. Add the repo's completions directory to fpath before compinit (e.g. in ~/.zshrc):

fpath+=("$HOME/path/to/nmaprs/completions")
autoload -Uz compinit && compinit

Or symlink _nmaprs into a directory already on fpath.

[0x04] HELP // SYSTEM INTERFACE

Combined flags like -sT, -Pn, -PS80, -T4 are expanded before parsing.

-h / --help prints a custom screen styled like tp (temprs CYBERPUNK_TEMPLATE): cyan section rules and box, magenta banner accents and tagline, yellow USAGE / copyright line, green // column, red/magenta/cyan ASCII bands. On a non-TTY or when NO_COLOR is set, escapes are omitted.

[0x05] SCANNING DATA STREAMS // EXAMPLES

# TCP connect — top ports from embedded frequency table
nmaprs scanme.nmap.org
# same as: nms scanme.nmap.org

# Ping scan (no port scan)
nmaprs -sn scanme.nmap.org

# UDP top ports
nmaprs -sU --top-ports 100 target

# Targets from file + resume
nmaprs -iL hosts.txt --resume state.json -oN out.txt

# IPv6
nmaprs -6 -p 80,443 2001:db8::/126

[0x06] TESTS

cargo test

[0x07] BENCHMARKS // PERFORMANCE MATRIX

┌──────────────────────────────────────────────────────────────┐ │ BENCHMARK: nmaprs vs nmap // WALL CLOCK COMBAT │ └──────────────────────────────────────────────────────────────┘

All runs on 127.0.0.1, TCP connect (-sT), -n -Pn, --min-rtt-timeout 50ms, --max-retries 0, output to /dev/null. Measured with hyperfine (warmup + 10–30 runs). macOS arm64, nmap 7.99.

BY PORT COUNT (M=256)

BY PARALLELISM (--top-ports 1000)

BY PARALLELISM (-p-, all 65535)

BY OUTPUT FORMAT (--top-ports 100, M=256)

PING SCAN (-sn, no -Pn)

ANALYSIS

nmaprs is 1.5–5.1× faster across all port counts. Small scans (2–100 ports) see the largest gains (3–5×) because nmap's startup overhead (Lua/NSE, libpcap, service databases) dominates. Full 65535-port sweeps show 1.5–1.6× speedup thanks to a worker-pool architecture with blocking std::net::TcpStream::connect_timeout (fewer syscalls than tokio async — no per-socket ioctl/fcntl non-blocking setup) plus lock-free UnsafeCell result slots indexed by atomic work counter. Ping scan shows 1.5× improvement. Output format has negligible impact on either tool.

CRITERION // RUST INTERNALS

TCP connect scan to three closed localhost ports — measures pure scan-loop overhead:

tcp_connect_scan_localhost_3_ports  time: [74.0 µs 77.4 µs 81.7 µs]

RUNNING BENCHMARKS

# Criterion microbenchmark
cargo bench --bench scan

# vs nmap (requires nmap + hyperfine on PATH)
cargo build --release
./scripts/benchmark_vs_nmap.sh

[0x08] ARCHITECTURE // SYSTEM INTERNALS

 ┌─────────────────────────────────────────────────────────────┐
 │  [1] ARGV EXPAND      ▓▓  normalize glued nmap tokens      │
 │  [2] PLAN             ▓▓  ScanPlan + optional --scanflags   │
 │  [3] TARGETS          ▓▓  IPv4/6, CIDR, DNS, -iL, -iR      │
 │  [4] DISCOVERY        ▓▓  ICMP + raw SYN + ARP + fallbacks  │
 │  [5] SCAN ENGINE      ▓▓  worker-pool, sharded pipelines    │
 │  [6] POST-SCAN        ▓▓  ping, trace, resume, NSE, OS, sV  │
 │  [7] OUTPUT           ▓▓  -oN, -oG, -oX, -oS, -oM, -oH     │
 └─────────────────────────────────────────────────────────────┘

1. Argv expansion (src/argv_expand.rs) normalizes glued nmap tokens before clap.
2. Plan (src/config.rs, src/scanflags.rs) → ScanPlan (optional --scanflags TCP byte for raw scans).
3. Targets (src/target.rs, src/lib.rs expand_specs_ordered) — IPv4/IPv6, CIDR, nmap-style IPv4 ranges, DNS, -iL, -iR; parallel expand_target with stable ordering.
4. Discovery (src/discovery.rs, src/icmp_ping.rs) — before port scan (unless -Pn); default ICMP + raw SYN (syn.rs) run concurrently; -PS raw SYN, -PA connect, -PU UDP, -PY SCTP, -PO IP protocol (ip_proto.rs), -PP/-PM legacy ICMP on Unix (icmp_ping.rs); connect_timeout from --min-rtt-timeout / timing template.
5. Scan (src/scan.rs, src/syn.rs, src/sctp.rs, src/ip_proto.rs, src/ftp_bounce.rs, src/icmp_listen.rs, src/ipv6_l4.rs) — optional --min-hostgroup / --max-hostgroup batching in src/lib.rs (host_batches); UDP ICMP listeners are one session per scan (shared DashMap across batches). TCP connect uses a worker-pool of conc OS threads (blocking std::net::TcpStream::connect_timeout — fewer syscalls than async) draining a shared atomic work index into lock-free UnsafeCell result slots; falls back to async tokio tasks when --proxies are configured. UDP / ping use tokio::spawn + Semaphore / raw IPv4 + IPv6 half-open TCP + SCTP (-sY/-sZ, CRC32c, IPv4 Layer3 + IPv6 raw SCTP, sharded blocking pool, mixed v4+v6 tokio::join) + IP protocol (-sO: IPv4 ICMP + Unix IPv6 raw + ICMPv6 Parameter Problem, sharded, mixed v4+v6 tokio::join) + FTP bounce (-b, Tokio parallel FTP sessions).
6. Ping (src/ping.rs), trace (src/trace.rs — bounded parallel traceroute / tracert, ordered output), resume (src/resume.rs), NSE builtins (src/nse.rs), OS guess (src/os_detect.rs, src/os_db.rs, src/os_fp_db.rs, src/os_scan.rs, src/fp_match.rs), version scan (src/vscan.rs), script-kiddie output (src/skiddie.rs).
7. Output (src/output.rs) — optional -oM / -oH, XML stylesheet options.

[0x09] DATA // SIGNAL DATABASES

data/top_ports.txt — regenerate with bash scripts/fetch_top_ports.sh.

data/nmap_ip_protocols_fast.txt — one IP protocol number per line (from Nmap's nmap-protocols: entries 0..=255 with a registered name, plus 253 and 254). Regenerate with:

curl -sL https://raw.githubusercontent.com/nmap/nmap/master/nmap-protocols | awk '!/^#/ && !/^$/ {for(i=1;i<=NF;i++) if($i ~ /^[0-9]+$/) {print $i+0; break}}' | sort -n -u

-sV / -O (optional, large upstream files): place Nmap's nmap-service-probes and nmap-os-db under ./data/ or pass --datadir DIR. Fetch both in one step:

bash scripts/fetch_nmap_data.sh

Those files are not committed; without them, -sV logs a warning and -O uses TTL-only heuristics (no DB titles, no fingerprint match).

OS FINGERPRINT PROBES // PARTIAL

IPv4 loads a single FingerprintDb from nmap-os-db (MatchPoints, Fingerprint, Class), sends Nmap 2nd-gen probes SEQ×6, ECN, T2–T7, U1, IE×2 from src/os_scan.rs (raw IPv4 Layer3 + ICMP), builds SEQ/OPS/WIN/ECN/T1–T7/U1/IE subject tests, and scores against all reference entries with expr_match (C++ FFI in c/expr_match.cpp). Real IPID classification (Z/I/BI/RI/RD) and TS classification (0/1/7/8/U/hex) are implemented; CI comes from T5–T7, II from IE echo replies, SS detects shared IPID sequence. IPv6 OS detection remains TTL-oriented until a v6 probe path exists.

[0xFF] LICENSE

┌──────────────────────────────────────────────────────────────┐ │ MIT OR APACHE-2.0 // UNAUTHORIZED REPRODUCTION WILL BE MET │ │ WITH FULL ICE │ └──────────────────────────────────────────────────────────────┘

[0xFE] LEGAL // ETHICS

┌──────────────────────────────────────────────────────────────┐ │ ONLY SCAN NETWORKS YOU OWN OR ARE AUTHORIZED TO TEST │ └──────────────────────────────────────────────────────────────┘

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░ >>> JACK IN. SCAN THE GRID. OWN EVERY PORT. <<<         ░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

created by MenkeTechnologies