netforge/lib.rs
1//! # netforge - High-performance raw packet I/O engine
2//!
3//! High-performance raw packet I/O engine for internet-scale scanning.
4//!
5//! Provides a unified [`PacketEngine`] trait with three backends, auto-selected
6//! by system capability:
7//!
8//! | Backend | Feature | Mechanism | Requirements |
9//! |---------|---------|-----------|--------------|
10//! | AF_XDP | `xdp-backend` | Zero-copy userspace ring | Kernel 5.10+, `CAP_BPF`, libbpf |
11//! | sendmmsg | `sendmmsg-backend` | Batched `sendmmsg()` syscalls | Linux, `CAP_NET_RAW` |
12//! | pnet | `pnet-backend` | Portable single-packet raw sockets | Any platform with `CAP_NET_RAW` |
13//!
14//! ## Stateless Sequence Encoding
15//!
16//! The [`seq`] module provides cryptographically-keyed TCP sequence number
17//! encoding, allowing fully stateless SYN scanning and banner grabbing.
18//! Zero bytes of per-connection state are stored.
19//!
20//! ## Checksum Computation
21//!
22//! The [`checksum`] module provides TCP/IP checksum computation for batch
23//! packet construction (portable scalar implementation).
24
25#![warn(missing_docs)]
26#![warn(clippy::pedantic)]
27#![allow(
28 clippy::module_name_repetitions,
29 clippy::must_use_candidate,
30 clippy::missing_errors_doc,
31 // doc_markdown fires on protocol-name acronyms (AF_XDP, IP, TCP,
32 // UDP, RFC, etc.) that are universally readable without backticks.
33 // Backticking them everywhere makes the rendered docs noisy.
34 clippy::doc_markdown,
35 // Network packet code casts u16/u32 sizes to u8 / usize / i32
36 // intentionally - the values come from MTU- and ring-bounded
37 // counters that cannot exceed the target type's range.
38 clippy::cast_possible_truncation,
39 clippy::cast_sign_loss,
40 clippy::cast_precision_loss,
41 clippy::cast_lossless,
42 // Hot-loop range iteration is faster than the iterator equivalent
43 // in the engine's TX/RX paths and reads more clearly to readers
44 // accustomed to C-style packet processing.
45 clippy::needless_range_loop,
46 clippy::similar_names,
47 clippy::too_many_lines,
48 // Unsafe blocks in the backends are documented inline and checked
49 // by integration tests; the `undocumented_unsafe_blocks` lint
50 // double-counts the SAFETY: comments we already have.
51 clippy::missing_safety_doc,
52 // libc bridging code naturally uses `&mut x as *mut _ as *mut T`
53 // to bind into C structs; clippy's preferred `addr_of_mut!` form
54 // would require restructuring how mmsghdr is built each call.
55 clippy::ptr_as_ptr,
56 clippy::borrow_as_ptr,
57 clippy::ref_as_ptr,
58 clippy::ptr_cast_constness,
59)]
60
61pub mod checksum;
62pub mod engine;
63pub mod packet;
64pub mod seq;
65pub mod stats_window;
66
67#[cfg(feature = "pnet-backend")]
68pub mod backend_pnet;
69
70#[cfg(feature = "sendmmsg-backend")]
71pub mod backend_sendmmsg;
72
73#[cfg(feature = "xdp-backend")]
74pub mod backend_xdp;
75
76pub use engine::{auto_select, EngineConfig, EngineStats, PacketEngine};
77pub use packet::RawPacket;
78pub use seq::{SeqEncoder, StatelessCookie};