# netforge - High-performance raw packet I/O engine
[](https://santh.dev/standard)
[](https://crates.io/crates/netforge)
[](#license)
High-performance raw packet I/O engine for internet-scale scanning. Three
backends, auto-selected by system capability, with a unified `PacketEngine` trait.
| 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
```rust,no_run
use netforge::{auto_select, EngineConfig, RawPacket, packet::build_syn_template};
use std::net::Ipv4Addr;
let config = EngineConfig {
source_ip: Ipv4Addr::new(192, 168, 1, 10),
rate_pps: 1_000_000,
interface: Some("eth0".into()),
..Default::default()
};
let engine = auto_select(config)?;
let mut tmpl = build_syn_template(Ipv4Addr::new(192, 168, 1, 10), 49_152);
netforge::packet::stamp_syn(&mut tmpl, Ipv4Addr::new(1, 1, 1, 1), 80, 0);
let sent = engine.tx_batch(&[tmpl])?;
println!("sent {sent} packet(s)");
let stats = engine.stats();
println!("backend={} tx_pps={}", engine.name(), stats.tx_pps);
# Ok::<_, netforge::engine::EngineError>(())
```
## 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**.
```rust
use netforge::{SeqEncoder, StatelessCookie};
use std::net::Ipv4Addr;
let enc = SeqEncoder::with_cookie(StatelessCookie::with_key(0xDEAD_BEEF));
let seq = enc.encode(Ipv4Addr::new(1, 1, 1, 1), 80, 49_152, 0);
// Later, when a SYN-ACK arrives with ack_num = seq + 1:
assert!(enc.verify_synack(seq.wrapping_add(1), Ipv4Addr::new(1, 1, 1, 1), 80, 49_152));
```
## 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_BPF` cannot 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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.