# SPEC - netforge
## Overview
`netforge` is a high-performance raw packet I/O engine designed for internet-scale network scanning. It provides a unified `PacketEngine` trait over three execution backends:
1. **AF_XDP (`xdp-backend`)**: Linux 5.10+ zero-copy userspace ring using `xsk-rs` / `libbpf`.
2. **sendmmsg (`sendmmsg-backend`)**: Linux batched raw socket syscalls using `sendmmsg()` and `recvmmsg()`.
3. **pnet (`pnet-backend`)**: Portable single-packet raw sockets using `pnet::transport`.
The engine automatically selects the fastest available backend based on system capabilities (`auto_select`).
---
## Architecture & Data Flow
```
+---------------------------------------+
| PacketEngine |
+---------------------------------------+
|
+----------------------------+----------------------------+
| | |
v v v
+------------------+ +------------------+ +------------------+
+------------------+ +------------------+ +------------------+
| | |
v v v
UMEM Ring Buffers Raw Sockets (v4) pnet Layer4 Channel
```
### Packet Representation
Packets are represented by `RawPacket`, a fixed-size zero-allocation stack buffer of `MAX_PACKET_SIZE` (1514 bytes).
- **Template Stamping**: Probes are pre-built as templates (`build_syn_template`) and stamped in-place per target (`stamp_syn`) with target IP, port, sequence number, and pre-calculated checksums.
- **Buffer Safety**: Slices derived from `RawPacket` go through `clamped_len()`, preventing out-of-bounds reads or buffer overruns.
### Stateless Sequence Encoding (`seq`)
To achieve zero per-connection state during SYN scanning:
- Sequence numbers are computed using a keyed SipHash-2-4 digest of `(dst_ip, dst_port, src_port, phase)` combined with a 64-bit secret key drawn from `getrandom` (OS CSPRNG).
- `verify_synack` checks whether incoming SYN-ACK `ack_num - 1` matches the expected SipHash-2-4 sequence number.
- `verify_data_ack` verifies sequence progress for multi-phase stateless banner grabbing.
### Rate Limiting & Performance Accounting (`stats_window`)
- **Token Bucket**: Optional in-tree rate limiting via `santh-ratelimit` enforced in `tx_batch` across all backends.
- **PpsTracker**: Lock-free, two-sample rolling window tracking lifetime packets and drops. `snapshot_pps()` enforces a minimum sample interval (`MIN_SAMPLE_SECS = 1ms`), returning cached rates for rapid reads to ensure idempotency across multiple consumers.
---
## Guarantees & Invariants
1. **No Silent Fallback**: Malformed or unparseable frames on receive are discarded (`None`) rather than emitted as empty or corrupted `RxPacket` structs.
2. **Error Propagation**: Real socket I/O errors (e.g. `EBADF`, `EIO`) surface as `EngineError::Io`. Non-blocking `EAGAIN` / `EINTR` return 0 packets without corrupting state.
3. **Drop-Order Safety**: In `XdpEngine`, `umem` is declared last so queues tearing down during drop execute before UMEM mmap deallocation.
4. **Memory Allocation Bounds**:
- `sendmmsg` uses thread-local `RX_PKT_BUFS` scratch buffers.
- `xdp` uses thread-local `COMP_SCRATCH`, `RX_DESC_SCRATCH`, and `TX_FRAME_SCRATCH` buffers.
---
## API Contract
### Engine Selection
```rust
pub fn auto_select(config: EngineConfig) -> Result<Box<dyn PacketEngine>, EngineError>;
```
Tries `XdpEngine` -> `SendmmsgEngine` -> `PnetEngine`. Returns `EngineError::PermissionDenied` when host capabilities or permissions are insufficient, falling through to the next backend.
### PacketEngine Trait
```rust
pub trait PacketEngine: Send + Sync {
fn tx_batch(&self, packets: &[RawPacket]) -> Result<usize, EngineError>;
fn rx_batch(&self) -> Result<Vec<RxPacket>, EngineError>;
fn rx_batch_into(&self, buf: &mut [RxPacket]) -> Result<usize, EngineError>;
fn stats(&self) -> EngineStats;
fn name(&self) -> &'static str;
}
```
---
## Roadmap
- **SIMD Checksums**: Implement explicit AVX2 SIMD vectorization for `checksum::ones_complement_sum` when targeting x86_64 architectures with AVX2 feature flags.
- **IPv6 Support**: Extend `RawPacket` templates and stateless sequence encoding to IPv6 raw socket scanning.