Documentation Index

Fetch the complete documentation index at: https://wiki.krkn.tech/llms.txt

Use this file to discover all available pages before exploring further.

​

DDoS Protection

​

Requirements

​

Architecture Overview

┌───────────────────────────────────────┐
│                     NETWORK TRAFFIC                          │
└───────────────────┬───────────────────┘
                                │
                               ▼
               ┌─────────────────┐
               │   XDP Program (Kernel)     │
               │   aegis_xdp_filter         │
               │                            │
               │  ban_map  ─► XDP_DROP    │
               │  rate_map ─► XDP_DROP    │
               │  config_map (thresholds).  │
               └──────┬──────────┘
                          │
           ┌────────┼─────────┐
           │              │              │
     XDP_PASS        XDP_DROP       Ring Buffer
           │         (banned/       (events)
           │          rate/syn)          │
           ▼             │            ▼
    TCP/IP Stack          │    ┌───────────┐
           │              │    │  readEvents()    │
           ▼             │    │  goroutine       │
    Aegis Reverse         │    └─────┬──────┘
    Proxy + WAF           │              │
                          │             ▼
                          │    ┌───────────┐
                          │    │ processEvents()  │
                          │    │ goroutine        │
                          │    │ • DB logging     │
                          │    │ • Auto-ban logic │
                          │    └────────┬──┘
                          │             │
                          │             ▼
                          └────► ban_map (kernel)
                                 (auto-ban writes
                                  IP back to BPF)

​

How It Works

​

Kernel-Level Filtering (XDP)

1. Check enable state — reads config_map[0]; if disabled, returns XDP_PASS
2. Parse Ethernet/IP headers — extracts source IP, destination IP, protocol
3. Parse L4 headers — if TCP, checks the SYN flag; if UDP, extracts ports
4. Ban map lookup — checks ban_map[src_ip]; if found and not expired, drops immediately with XDP_DROP
5. Rate limit check — looks up rate_map[src_ip] for per-IP packet and SYN counters within a 1-second sliding window; drops if thresholds exceeded
6. Pass — increments stats and returns XDP_PASS

​

BPF Maps

​

Kernel Data Structures

expires_ns    — Monotonic timestamp (0 = permanent ban)
reason        — Code: 1=manual, 2=rate_limit, 3=syn_flood, 4=app_layer
drop_count    — Atomic counter of packets dropped for this IP

window_start_ns — Start of the current 1-second window
packet_count    — Total packets in current window
syn_count       — TCP SYN packets in current window

packets_per_second — Global PPS threshold (0 = disabled)
syn_per_second     — Global SYN/sec threshold (0 = disabled)
event_sample_rate  — Emit 1 pass event per N packets
enabled            — Master enable flag

​

Rule Types

​

ip_ban — Direct Kernel-Level Ban

• Enforcement: Kernel-level, per-IP
• Latency: Immediate — packets never reach the TCP/IP stack

​

cidr_ban — CIDR Block Ban

• Enforcement: Kernel-level for /32 only
• Broader CIDR support: Planned

​

rate_limit — Packets Per Second Threshold

• Start with the configured DefaultPPS
• For each enabled rate_limit rule with a packets_per_second value > 0: take the minimum
• The strictest enabled rule wins

• Adding a stricter rate_limit rule changes the kernel threshold immediately
• Adding a looser rule has no effect if a stricter enabled rule already exists
• The XDP program always reads one current packets_per_second value from config_map
• Enforcement: Kernel-level, single global threshold

​

syn_limit — SYN Packets Per Second Threshold

• Enforcement: Kernel-level, single global threshold

​

Rule Lifecycle

1. The service reloads all rules from the database
2. Recomputes effective global thresholds (minimum across all enabled rules + default)
3. Writes updated values into the kernel config_map
4. For ip_ban and /32 cidr_ban rules: syncs the ban_map directly

​

Auto-Ban

1. Kernel drops packet, emits drop_rate or drop_syn event
2. readEvents() goroutine parses the event from the ring buffer
3. processEvents() goroutine calls handleAutoBan()
4. Auto-ban TTL is computed as the maximum of:
   • Global AutoBanDuration config value
   • The auto_ban_duration_sec of the first enabled matching rule
5. If TTL > 0: the source IP is written into the kernel ban_map with that TTL
6. Subsequent packets from that IP are dropped at the XDP level without rate-map evaluation

​

Ban Entry Lifecycle

• Bans are stored with a monotonic expiration timestamp
• The XDP program checks expiry on every lookup — expired entries are deleted inline
• A cleanupLoop() goroutine runs every 30 seconds to sweep expired bans from userspace

​

Ban Reasons

​

Event System

​

Event Types

​

Event Sampling

• Drop events: Emitted every 100th dropped packet per ban entry
• Pass events: Sampled at the configurable event_sample_rate (default: 1 in 1,000)

​

Event Data

• Source and destination IP
• Source and destination port
• Protocol (TCP, UDP, other)
• Event type
• Packets in current window
• Drop count

​

Configuration

​

Real-Time Statistics

​

Service Lifecycle

​

Startup

1. Remove memory lock limit (rlimit.RemoveMemlock)
2. Load pre-compiled BPF bytecode (x86-64 or ARM64)
3. Attach XDP program to the configured network interface
4. Create ring buffer reader for kernel events
5. Sync configuration, rules, and bans to kernel maps
6. Launch goroutines: readEvents(), processEvents(), cleanupLoop()

​

Shutdown

1. Close ring buffer reader
2. Detach XDP program from network interface
3. Close BPF map file descriptors

​

Concurrency

​

API Endpoints

​

Current Limitations