netforge 0.1.2

High-performance raw packet I/O engine with AF_XDP, sendmmsg, and pnet backends
Documentation

netforge - High-performance raw packet I/O engine

santh status Crates.io License

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

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:

at your option.