netforge - High-performance raw packet I/O engine
High-performance raw packet I/O engine for internet-scale scanning. Three
backends, auto-selected by system capability, with a unified PacketEngine trait.
| Backend | Feature | Mechanism | Requirements |
|---|---|---|---|
| AF_XDP | xdp-backend |
Zero-copy userspace ring | Kernel 5.10+, CAP_BPF, libbpf |
| sendmmsg | sendmmsg-backend |
Batched sendmmsg() syscalls |
Linux, CAP_NET_RAW |
| pnet | pnet-backend |
Portable single-packet raw sockets | Any platform with CAP_NET_RAW |
auto_select() tries the fastest available backend first and falls through on construction failure.
Quick start
use ;
use Ipv4Addr;
let config = EngineConfig ;
let engine = auto_select?;
let mut tmpl = build_syn_template;
stamp_syn;
let sent = engine.tx_batch?;
println!;
let stats = engine.stats;
println!;
# Ok::
Stateless sequence encoding
The seq module provides cryptographically-keyed TCP sequence number
encoding for fully stateless SYN scanning. The full probe identity
(src_ip, dst_ip, dst_port, src_port, phase) is encoded into the 32-bit
sequence number using a keyed hash; SYN-ACK responses are verified
against the hash at receive time, with zero per-connection state.
use ;
use Ipv4Addr;
let enc = with_cookie;
let seq = enc.encode;
// Later, when a SYN-ACK arrives with ack_num = seq + 1:
assert!;
Checksum computation
The checksum module provides RFC 1071 Internet checksum computation for IP
and TCP headers using folded 32-bit scalar sums.
When to use / when not to use
When to use
- High-throughput raw SYN scanning or stateless probe generation on Linux systems.
- Applications needing zero per-connection memory overhead for millions of concurrent targets.
- Multithreaded network components requiring platform-adaptive packet engine backends (AF_XDP,
sendmmsg,pnet).
When not to use
- General-purpose HTTP/TCP client applications where standard OS TCP stack features (retransmission, congestion control, TLS) are required.
- Unprivileged user environments where
CAP_NET_RAW/CAP_BPFcannot be granted.
Compared to alternatives
Existing raw socket engines in Rust often depend exclusively on single-packet pnet calls or expose raw OS bindings without unified multi-backend abstractions. netforge provides a single PacketEngine trait that seamlessly upgrades from portable pnet to batched sendmmsg and zero-copy AF_XDP rings when hardware and permissions allow.
Compared to C engines like Masscan, netforge integrates memory-safe packet templates, in-tree token-bucket rate limiting, and cryptographic sequence encoding powered by keyed SipHash-2-4 to resist probe response spoofing.
How it fits in Santh
netforge lives in libs/performance/io/netforge as Santh's low-level raw network I/O layer. It depends on santh-ratelimit for rate limiting and provides packet transmission and reception primitives to higher-level network discovery, port scanning, and banner grabbing tools.
License
Dual-licensed under either of:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.