Aegis is a low-latency, multi-threaded Deep Packet Inspection (DPI) and packet filtering framework inspired by architectural patterns commonly used in high-performance packet processing systems, trading infrastructure, and network security software.
Aegis is a systems engineering project exploring low-latency packet processing techniques commonly used in network security, trading infrastructure, and high-performance gateways. The project emphasizes deterministic memory management, lock-free concurrency, and cache-efficient data structures over feature completeness.
- Zero Heap Allocation on the Hot Path: Pre-allocated contiguous memory pools (
PacketBufferPool) manage packet memory. All components pass cache-aligned indices and zero-copy packet slices rather than allocating dynamic arrays or buffers. - Lock-Free Producer/Consumer Queues: Uses bounded, single-producer single-consumer (
LockFreeSPSCQueue) structures aligned to 64-byte CPU cache lines (alignas(64)) to completely eliminate mutex contention and false sharing. - Zero-Copy Packet Parsing: Designed
PacketViewcontaining offsets and nested sub-views directly mapping to raw packet header bytes, avoiding string copying. - Flow Affinity: Distributes packets to dedicated worker cores using 5-tuple consistent hashing, ensuring flow affinity and enabling local connection tracking without cross-core locks.
- Deterministic Latency: All critical path algorithms use bounded structures, avoiding dynamic memory expansion or locks that introduce latency spikes.
- Benchmark-Driven Optimization: Optimization iterations are verified against microbenchmarks measuring nanosecond-level components.
[ Ingest / PCAP Reader ]
│
Lock-Free SPSC Queue
│
[ Load Balancer ]
│
┌─────────────┴─────────────┐
│ │
Lock-Free SPSC Lock-Free SPSC
│ │
[ Worker Core 0 ] [ Worker Core N ]
│ │
Lock-Free SPSC Lock-Free SPSC
└─────────────┬─────────────┘
│
[ Polling Writer ]
│
[ Output PCAP / File ]
The pipeline operates as a set of decoupled execution stages connected by ring buffers:
- Ingest / PCAP Reader: Streams packets directly from the file system or interface into pre-allocated memory pool slots.
- Load Balancer: Dispatches the memory block index to a dedicated worker core based on a 5-tuple hash of the packet headers.
- Worker Cores: Classify flow protocols (DNS, TLS, HTTP) using zero-copy matching, evaluate access control policies (IP lists, CIDR blocks, wildcard domains), and track flows bidirectionally.
- Polling Writer: Performs a lock-free round-robin poll of all worker output queues, writing permitted packets to disk and releasing the memory slots back to the pool.
# Clone the repository
git clone https://github.com/rajveer100704/aegis.git
cd aegis
# Configure the build in Release mode
cmake -B build -DCMAKE_BUILD_TYPE=Release
# Compile all targets (aegis_tests, aegis_benchmark)
cmake --build build --config Release
# Run the unit and pipeline integration tests
# Windows:
build\Release\aegis_tests.exe
# Linux/macOS:
./build/aegis_tests
# Run the performance microbenchmarks
# Windows:
build\Release\aegis_benchmark.exe
# Linux/macOS:
./build/aegis_benchmark- Preallocated Memory Pools: Reuses contiguous byte arrays to eliminate
malloc/freeoverhead. - RCU Rule Engine: Employs atomic
std::shared_ptrswaps to implement lock-free, zero-overhead rule queries on worker threads. - Cache-Friendly Design: Explicit cache line alignment preventing false sharing between producer and consumer threads.
- Zero-Copy Parsing: Inline extraction of SNI and DNS hostname metadata from protocol byte slices.
Aegis/
├── include/ # Header files
│ ├── lock_free_queue.h # Bounded, cache-aligned SPSC queue
│ ├── packet_pool.h # Preallocated block memory pool
│ ├── packet_view.h # Zero-copy packet descriptor
│ ├── packet_parser.h # Network header parser
│ ├── connection_tracker.h # Flat bidirectional connection map
│ ├── rule_manager.h # RCU-based subnet & wildcard rules
│ ├── load_balancer.h # Flow-consistent load balancer
│ ├── fast_path.h # Worker Core (Packet Processing Worker) declarations
│ └── dpi_engine.h # Core orchestration engine
│
├── src/ # Core source implementations
│ ├── packet_pool.cpp
│ ├── packet_parser.cpp
│ ├── connection_tracker.cpp
│ ├── rule_manager.cpp
│ ├── load_balancer.cpp
│ ├── fast_path.cpp # Worker Core (Packet Processing Worker) loop
│ ├── dpi_engine.cpp
│ └── pcap_reader.cpp
│
└── tests/ # Validation & Performance suites
├── aegis_tests.cpp # Unit and integration test suite
└── aegis_benchmark.cpp # Nanosecond-level microbenchmark suite
Aegis uses CMake to configure cross-platform, optimized builds.
# Configure build directory
cmake -B build -DCMAKE_BUILD_TYPE=Release
# Compile all targets
cmake --build build --config Release# Executing unit & pipeline integration tests
# Windows:
build\Release\aegis_tests.exe
# Linux/macOS:
./build/aegis_testsNote
Aegis validation and safety assurances include:
- ASan / UBSan: Validated using Clang/GCC Debug builds.
- TSan: Validated on Linux with Clang or GCC.
- MSVC Release: Clean Release compilation.
# Executing nano-second level performance benchmarks
# Windows:
build\Release\aegis_benchmark.exe
# Linux/macOS:
./build/aegis_benchmark- CPU: AMD Ryzen 5 7530U (6C/12T)
- RAM: 8 GB DDR4
- OS: Windows 11 Home (x64)
- Compiler: MSVC 2022
- Standard: C++17
- Build: Release (/O2)
| Component | Operation | Throughput | Average Latency |
|---|---|---|---|
| Lock-Free SPSC Queue | Push/Pop | 16.03 million ops/sec | 57.79 ns |
| Packet Buffer Pool | Acquire/Release | 90.27 million cycles/sec | 11.08 ns |
| Zero-Copy Parser | Header Decoding | 13.37 million packets/sec | 74.80 ns / packet |
- Measurement Harness: Custom benchmarking loop (
tests/aegis_benchmark.cpp) usingstd::chrono::high_resolution_clock. - Iterations: 10 million operations for the SPSC queue, 5 million cycles for the Packet Buffer pool, and 2 million packets for the parser.
- Optimization Options: Built with full compiler optimization flags (
/O2on MSVC, equivalent to-O3 -march=nativeon GCC/Clang) and warning levels elevated to/W4 /WX. - Latency Characterization: Queue operations sample 10,000 requests dynamically to output percentile distributions (p50, p95, p99).
- Version 1.1: SIMD Packet Parser: Accelerate header parsing and substring matching using AVX2/AVX-512 vectorization.
- Version 1.2: Dynamic Plugin API: Support registering custom L7 protocol analyzer blocks dynamically.
- Version 1.3: QUIC & UDP Support: Classification and tracking of encrypted QUIC/HTTP3 flow handshakes.
- Version 2.0: Kernel Bypass (AF_XDP / DPDK): Feed the packet buffer pool directly from raw network interfaces, bypassing OS kernel context switches and leveraging NUMA node pinning.
For advanced systems design summaries, refer to the following documents:
- DPI & Networking Tutorial - Fundamental concepts & packet journeys
- Architecture Design - Pipeline & synchronization details
- Memory Architecture - Buffer preallocation details
- Optimization Log - Log of optimization phases
- Complexity Analysis - Time/space complexity metrics
- Interview Appendix - Systems engineering interview notes
README.md (Overview & Quickstart)
│
├──► docs/03_ARCHITECTURE.md (Pipeline & Thread Sync)
│ └──► docs/05_CONCURRENCY.md (Lock-Free Queues)
│ └──► docs/06_MEMORY_ARCHITECTURE.md (Block Pools)
│
├──► docs/00_TUTORIAL.md (DPI & Networking Tutorial)
│
├──► docs/adr/ (Architecture Decision Records)
│
└──► src/ & tests/ (Implementation & Benchmarks)