Skip to main content

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};