IronSovereign Documentation
Complete guides for the out-of-band zero-trust platform: sovProbe setup, sovVault configuration, the 64-byte WAL contract, and troubleshooting.
Getting Started
Prerequisites
- Linux kernel with BTF support (5.8+)
- clang and Linux kernel headers (for eBPF)
- Rust toolchain (stable, MSRV 1.75+)
Build from Source
git clone https://github.com/dataxcash/sovProbe.git cd sovProbe/sov-probe cargo build --release # static single binary: target/release/sovprobe (2.1 MB)
Quick Start
sudo ./target/release/sovprobe \ --interface eth0 \ --capture-ports 8080 \ --shm-path /dev/shm/sov-probe
The probe attaches an eBPF tc hook (ingress + egress) and never sits in the data path. Only port-whitelisted packets are mirrored into a 1 MB kernel ring buffer — everything else passes through untouched.
Architecture
kernel eBPF (tc)
Port-Filter whitelist → 1 MB kernel ring buffer. Zero blocking, zero inline risk, zero SPOF anxiety.
userspace sovprobe
etherparse parse → Head-Slicer → dual-layer circuit breaker. Emits a standard 64-byte contract log.
slimSync → Zenoh → sovVault
FastCDC-dedup, ChaCha20-encrypted transport, sealed into epoch-isolated LMDB for forensic-grade storage.
[ kernel eBPF (tc) ] Port-Filter whitelist → RingBuffer (1 MB)
↓
[ userspace sovprobe ] etherparse parse → Head-Slicer → circuit breaker
↓
/dev/shm/sov-probe/segment_*.wal ← 64 B header contract (standard local pipe)
↓ (inotify/fanotify)
[ slimSync ] FastCDC → ChaCha20 → Zenoh → SovVault
sovProbe Setup
Configuration
TOML config at /etc/sovprobe.toml mirrors the CLI flags:
# /etc/sovprobe.toml interface = "eth0" capture_ports = [8080] shm_path = "/dev/shm/sov-probe"
Metrics
Prometheus metrics on :9101/metrics:
sovprobe_written_total— WAL segments committedsovprobe_dropped_total— tail drops under pressuresovprobe_degraded_now— circuit breaker state
sovVault Configuration
Storage Hub
sovVault ingests encrypted WAL streams, decrypts, reassembles out-of-order TCP streams, matches request/response QR pairs, and lands everything into three storage planes — all inside zero-copy LMDB with generational (epoch) isolation. Ghost packets are physically sealed off from late ACK/RSTs.
Forensic Export
Judicial-grade PCAP export streams over the RECORD_TS time cursor with in-memory BPF pre-filtering,
re-reading original WAL payloads (Magic→Version→Length→CRC32 quadruple validation) and reproducing
orig_len vs incl_len so Wireshark renders
[Packet size limited] faithfully.
64-Byte WAL Contract
Magic (u32) → Length (u32) → CRC32 (u32) → ... payload
- Triple validation — dirty tails are rejected; no silent bad data.
- Unlink-Oldest rotation — monotonic segment numbers, RAMDisk bounded ≤ 512 MB, files globally unique.
- Verified E2E — 11-segment WAL re-verification: md5 11/11 byte-identical; real traffic at 1885 req/s.
- Offline decoder —
sov2pcapconverts WAL → PCAP for Wireshark.
FAQ
Does it slow down my production traffic?
No. The probe is a passive out-of-band tap. It never sits in the data path, never injects RST, and non-target packets pass through completely untouched.
What happens under extreme load?
The dual-layer circuit breaker (hot-path queue watermark > 80% + slow-path procfs sampling) triggers Drop-Tail fail-open with automatic recovery. The probe degrades gracefully — your traffic never feels it.
How is evidence protected from tampering?
Every WAL segment carries a 64-byte header (Magic → Length → CRC32). In sovVault, epoch isolation physically separates generations in the B+ tree, and batch atomicity (2PC-lite) makes crash-window replay idempotent and convergent.
Can I export evidence for external audit?
Yes. sovVault exports judicial-grade PCAP (Wireshark-ready), with the full chain from original WAL payloads
reproduced faithfully — orig_len vs incl_len intact.