Experimental Rust/Aya XDP + TC firewall and traffic analyzer. Low-overhead packet filtering with release evidence still pending for production claims.

Aegis is a Rust/Aya firewall built on eBPF (Extended Berkeley Packet Filter), XDP (eXpress Data Path), and TC (Traffic Control). It filters ingress and egress traffic early in the networking stack, with runtime support bounded by the evidence matrix in docs/PORTABILITY.md.

¹ No measured throughput claim is made for this release candidate. Benchmark results require archived kernel, NIC/driver, XDP mode, CPU, packet-size, rule-count, and raw command output evidence.

• Non-privileged gates: passing on latest local validation; rerun before every tag.
• Privileged verifier/load/attach: pending for the current release candidate.
• Packet replay matrix: pending for the current release candidate.
• Stress replay: pending for the current release candidate.
• Production tag: blocked until privileged lab evidence is archived.

To maintain transparency as a security tool, features are strictly categorized by their current validation status:

• XDP Ingress Filtering — Policy path implemented for NIC-driver/SKB attach modes; current release requires privileged verifier/load/attach and replay evidence before production claims.
• TC Egress Filtering — Egress policy path implemented; current release requires TC attach and replay evidence before production claims.
• IPv4 + IPv6 Basic Filtering — Dual-stack support with strict IP/CIDR blocklists
• IP Allowlist — Trusted IPs bypass checks
• CIDR Blocklists — LPM Trie matching

• Stateful Connection Tracking — Native eBPF conntrack (currently tracks SYN/ACK state, no deep stream reassembly)
• Dynamic Auto-Ban — Userspace threat mitigation loop
• Port Scan Detection — Bitmap-based unique port tracking with auto-ban
• SYN Flood Protection — Token bucket rate limiting at XDP layer

• Throughput — XDP driver mode is expected to be low overhead, but no pps number is claimed without benchmark artifacts.

• TLS ClientHello Fingerprinting — Native eBPF TLS payload extraction for JA3 scoring (map exists, DPI deferred to v2)
• Heuristic Intrusion Detection — Advanced protocol anomaly detection beyond basic TCP flags
• IPv6 Extension Header Coverage — Limited today; exact/CIDR IPv6 policy paths exist, while full extension-header replay coverage is pending.
• VLAN / QinQ Payload Parsing — Currently fails-closed (drops all tagged frames)

• Interactive TUI (fd-isolated — zero stdout pollution):
  • Connections view with offline GeoIP lookup (MaxMind GeoLite2)
  • Live statistics with sparklines (packets/sec, drops/sec)
  • Security event log
  • ISP/Geo/Country display per connection
• Module Hotkeys — Toggle PortScan, RateLimit, Threats, ConnTrack, ScanDetect, Verbose on-the-fly
• Space-to-Ban — One-key IP blocking from connections list
• Daemon Mode — Background operation with stdout log printer
• JSON Logging — Machine-readable output for SIEM integration
• Shell Completions — bash, zsh, fish, PowerShell, elvish

• TOML Config File — /etc/aegis/config.toml for persistent settings
• Threat Feeds — Download and load CIDR blocklists from public sources
• Save/Restore — Persist and reload block rules
• Status Command — Query running daemon state via pinned BPF maps
• Single Binary — eBPF bytecode embedded, no external files
• Installer Scripts — documented for the current release matrix in docs/PORTABILITY.md
• Auto XDP Mode — Automatic fallback from driver to SKB mode
• Systemd Integration — Hardened service file with CAP_BPF + CAP_NET_ADMIN

Production release claims require archived verifier/load/attach/detach logs and packet replay artifacts. Build/test success alone is not firewall enforcement proof.

• Portability matrix: docs/PORTABILITY.md
• Release validation: docs/RELEASE_VALIDATION.md
• Troubleshooting and rollback: docs/TROUBLESHOOTING.md

• Linux Kernel >= 5.4 (5.8+ recommended for CAP_BPF)
• Root privileges (for eBPF loading)

curl -sSfL https://github.com/m4rba4s/Aegis-eBPF/releases/download/v4.3.0-rc.1/install.sh -o install.sh
sha256sum install.sh
sudo bash install.sh --check

# Clone and install
git clone https://github.com/m4rba4s/Aegis-eBPF.git
cd Aegis-eBPF
sudo ./install.sh

The installer will:

• Detect your distro and install dependencies
• Build from source (or use pre-built if available)
• Install both XDP and TC eBPF objects
• Install systemd service when available
• Create config directories

TC egress is required by default. --no-tc is an explicit ingress-only waiver.

# Build
cargo run -p xtask -- build-all --profile release
cargo build --release -p aegis-cli

# Run (eBPF is embedded in binary)
sudo ./target/release/aegis-cli -i eth0 tui

# Build fully static musl binary for the documented x86_64 Linux release matrix
docker build --output=dist .

# Outputs:
# dist/aegis-cli     - Static binary (eBPF embedded, no glibc dependency)
# dist/aegis         - Standalone XDP object (optional)
# dist/aegis-tc      - Standalone TC object (optional)

The Docker build produces a statically linked musl binary. Static linking removes the glibc dependency, but it does not prove kernel, XDP, or TC runtime support. Distribution support is evidence-bound; see docs/PORTABILITY.md.

sudo aegis-cli -i eth0 tui
sudo aegis-cli -i wg0 tui           # VPN interface
sudo aegis-cli -i eth0 --no-tc tui  # XDP only, no egress filtering

Controls:

# Start as background service
sudo systemctl start aegis@eth0

# Or run directly
sudo aegis-cli -i eth0 daemon

sudo aegis-cli -i eth0 load
# Interactive commands:
# block 1.2.3.4
# unblock 1.2.3.4
# list
# save / restore

aegis.yaml supports ingress source blocks and TC egress destination blocks:

rules:
  - ip: 198.51.100.10
    port: 443
    proto: tcp

egress_rules:
  - ip: 203.0.113.20
  - ip: 2001:db8::20

egress_cidrs:
  - cidr: 203.0.113.0/24
  - cidr: 2001:db8:bad::/48

# Use custom eBPF objects instead of embedded
sudo aegis-cli \
  --ebpf-path /custom/path/aegis.o \
  --tc-path /custom/path/aegis-tc.o \
  -i eth0 tui

┌─────────────────────────────────────────────────────────────┐
│                      KERNEL SPACE                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐           ┌─────────────┐                  │
│  │  aegis-ebpf │           │  aegis-tc   │                  │
│  │   (XDP)     │           │ (TC Egress) │                  │
│  │  INGRESS    │           │  EGRESS     │                  │
│  └──────┬──────┘           └──────┬──────┘                  │
│         │                         │                          │
│         └──────────┬──────────────┘                          │
│                    ▼                                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                BPF MAPS / RING BUFFERS               │    │
│  │  BLOCKLIST | CONFIG | STATS | FEEDS | TC CONN_TRACK │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ BPF RingBuf
┌─────────────────────────────────────────────────────────────┐
│                      USER SPACE                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │            aegis-cli (Rust/Tokio)                    │    │
│  │  ┌──────────────────────────────────────────────┐   │    │
│  │  │  EMBEDDED eBPF BYTECODE (XDP + TC objects)   │   │    │
│  │  └──────────────────────────────────────────────┘   │    │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────────────┐     │    │
│  │  │   TUI   │  │  Event  │  │  Map Management │     │    │
│  │  │(ratatui)│  │  Loop   │  │  (aya)          │     │    │
│  │  └─────────┘  └─────────┘  └─────────────────┘     │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Aegis-eBPF/
├── aegis-common/       # Shared types (Single Source of Truth)
│   └── src/lib.rs      # PacketLog, Stats, FlowKey, threat/reason constants
├── aegis-ebpf/         # XDP ingress program (no_std, eBPF target)
│   └── src/main.rs     # Packet filtering, rate limiting, scan detection, TLS parsing
├── aegis-tc/           # TC egress program
│   └── src/main.rs     # Outbound connection blocking
├── aegis-cli/          # Userspace controller
│   ├── build.rs        # Embeds eBPF bytecode at compile time
│   ├── src/main.rs     # Application bootstrapper
│   ├── src/event_loop.rs # MPSC Lock-Free Perf Event consumers
│   ├── src/loader.rs   # eBPF/TC program lifecycles
│   ├── src/map_manager.rs # Map pinning, sizing, and threat feeds
│   ├── src/conntrack_gc.rs # Ktime-synced map garbage collection
│   ├── src/tui/        # Terminal UI (ratatui, fd-isolated)
│   ├── src/config.rs   # TOML config parser
│   ├── src/geo.rs      # Offline GeoIP (MaxMind GeoLite2)
│   ├── src/compat.rs   # Kernel capability detection
│   └── src/feeds/      # Threat feed parser/downloader
├── guide/              # Operational & Architectural Engineering Guides
├── deploy/             # Systemd service files
├── Dockerfile          # Reproducible builds
└── install.sh          # Multi-distro installer

PRs welcome! Please ensure:

1. cargo fmt passes
2. cargo clippy has no warnings
3. eBPF programs compile with cargo run -p xtask -- build-all

This tool is intended for defensive security research and system hardening. The author is not responsible for any misuse.

MIT

Crafted with Rust & eBPF