> ## 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. # Aegis > Aegis — Production-grade Web Application Firewall & Reverse Proxy Manager Transparent GIF # Aegis — Web Application Firewall & Reverse Proxy Manager Aegis is a production-grade Web Application Firewall (WAF) and Reverse Proxy Manager written in Go. It combines the host management experience of Nginx Proxy Manager with a full WAF engine that evaluates a customizable set of rules including the OWASP Top 10 and other malicious payloads on every proxied request. **Single binary. SQLite storage. Zero dependencies.** Aegis ships as a single static binary with an embedded admin UI, uses SQLite (WAL mode) for all persistent storage, and binds the admin dashboard to `127.0.0.1:9443` by default for security. No Nginx, no Docker, no external database required — just run the binary and start adding hosts. Image *** ## Design Principles * **NPM replacement** — domain-based routing, load balancing, SSL/TLS termination, health checks, and WebSocket proxying without needing a separate reverse proxy * **Per-host WAF profiles** — each proxy host independently runs in `off`, `detect`, or `enforce` mode with its own rule chain * **Zero-lock hot path** — atomic pointer swaps for config, channel-buffered log writes, per-bucket rate limiters; no mutex on the request path * **First-run setup wizard** — no default credentials; forces secure initialization on first launch *** ## WAF Paranoia Level The paranoia level is a global setting that controls which WAF rules are active across all proxy hosts. Every built-in and imported rule is tagged with a paranoia level from 1 to 4. When you set the global paranoia level, all rules at or below that level are automatically enabled, and all rules above it are automatically disabled. ### Paranoia Levels | Level | Sensitivity | Description | | ----- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **1** | Low | Core detection rules only — minimal false positives, catches obvious attacks | | **2** | Standard (default) | Balanced detection — recommended for most deployments | | **3** | High | Aggressive detection — catches more sophisticated attack variants, may produce false positives on complex applications | | **4** | Maximum | All rules enabled — highest sensitivity, expect false positives that require tuning | ### How It Works When the paranoia level is changed (via Settings or during initial setup), Aegis executes a bulk update across all rules: * Rules with `paranoia <= level` are **enabled** * Rules with `paranoia > level` are **disabled** * This only affects rules in **inherit** mode (the default) At runtime, the WAF engine skips any rule whose paranoia level exceeds the host's configured level, so the rule chain only evaluates rules that should be active. ### Per-Rule Override (Manual Mode) Individual rules can be switched to **manual** paranoia mode, which opts them out of the global paranoia system entirely. A manual rule's enabled/disabled state is controlled only by its own toggle — changing the global paranoia level will not affect it. This is useful for: * Keeping a specific high-paranoia rule enabled even when the global level is low * Disabling a rule that causes false positives without lowering the global paranoia level * Custom rules that should always be active regardless of the global setting | Paranoia Mode | Behavior | | --------------------- | ------------------------------------------------------------------------------------- | | **inherit** (default) | Rule follows the global paranoia level — enabled when `rule.paranoia <= global_level` | | **manual** | Rule ignores the global paranoia level — enabled/disabled by its own toggle only | ### Configuration * **Location:** Admin UI -> Settings -> WAF Paranoia Level * **Setting key:** `waf_paranoia_level` * **Default:** `2` * **Range:** 1–4 * **API:** `PUT /api/v1/settings` with `{"waf_paranoia_level": "3"}` Changing the paranoia level takes effect immediately — Aegis updates all inherited rules in SQLite and reloads the proxy rule chains without a restart. *** ## Feature Overview NPM-equivalent multi-host routing, load balancing, SSL/TLS, WebSocket proxying 26 built-in OWASP rules, rate limiting, IP blacklists/whitelists, CORS enforcement IP/CIDR, local auth, OAuth/OIDC SSO, Active Directory access control Kernel-level XDP/eBPF packet filtering — ban maps, rate limiting, SYN flood protection AI crawler blocking, robots.txt generation, scanner detection Built-in challenge system — proof-of-work, browser verification, interactive checkbox Stateful multi-request correlation engine for detecting attack campaigns Condition builder, raw regex, and correlated rule authoring with live testing Let's Encrypt, Cloudflare Origin CA, custom upload, SNI routing, key encryption Mutual TLS for upstream connections — client certificates, custom CAs, zero-trust backends Gradual traffic splitting with automatic rollback based on error rates and latency Ingest OpenAPI 3.x or Swagger 2.0 specs to auto-generate per-endpoint defense rules Automatic failover between two Aegis instances with virtual IP and real-time config replication TCP/UDP streaming proxy with TLS termination, bandwidth limits, and access control CLI reference, configuration, service management, environment variables Full REST API for hosts, rules, traffic, analytics, SMTP, and system management *** ## Quick Start ### Build from source ```bash theme={null} git clone https://github.com/KrakenTech-LLC/aegis.git cd aegis go build -o aegis ./cmd/aegis/ ``` ### First run ```bash theme={null} ./aegis run ``` On first launch, Aegis starts in setup mode. Open `http://127.0.0.1:9443` in your browser to run the setup wizard, which prompts for: 1. Admin username and password (minimum 12 characters) 2. Email address (for magic link authentication, optional) 3. SMTP configuration (optional, enables passwordless login and alerts) After setup completes, the default WAF rules are seeded into SQLite and the proxy begins listening. ### Default Listeners | Service | Default Address | Description | | ----------- | ---------------- | ---------------------------------------------- | | Admin UI | `127.0.0.1:9443` | Dashboard and API (localhost only) | | HTTP Proxy | `:80` | Inbound HTTP traffic + ACME HTTP-01 challenges | | HTTPS Proxy | `:443` | Inbound HTTPS traffic with TLS termination | *** ## Architecture ```text theme={null} +-------------------------------------+ Clients -----►| Aegis (Go) | | | | +-----------+ +---------------+ | | | Reverse | | WAF Engine | | | | Proxy |◄-| (per-host | | | | Router | | rule chains) | | | +-----+-----+ +---------------+ | | | | | +-----v-----+ +---------------+ | | | Upstream | | Admin Web UI | | | | Backends | | (localhost) | | | +-----------+ +---------------+ | | | | | +-----v-------------------------+ | | | SQLite Storage | | | +-------------------------------+ | +-------------------------------------+ ``` ### Request Lifecycle ```text theme={null} Client | v TLS Termination (autocert / custom cert via SNI) | v Host Lookup (domain -> runtimeHost via atomic.Pointer) | v Aegis Shield Challenge (if enabled, check aegis_shield cookie) | v WAF Mode Check ──► "off" ──► skip directly to Reverse Proxy | v (detect / enforce) IP Whitelist ──► match ──► suppress enforcement (detect-only) | v IP Timeouts ──► active timeout ──► block (temporary auto-block) | v IP Blacklist ──► match ──► block (enforce) or log (detect) | v Method Restriction | v Body Size Check | v CORS Origin Validation | v Rate Limiting (token bucket) | v Rule Chain Evaluation (26 compiled regex rules) | v Mnemos Correlation (multi-request campaign detection) | v Reverse Proxy (httputil.ReverseProxy with load balancing) | v Response Filtering (strip headers, inject security headers, SameSite cookies) | v Client Response ``` ### Concurrency Model * **Goroutine per request** — Go's `net/http.Server` default model * **Atomic config reads** — `atomic.Pointer[map[string]*runtimeHost]` for zero-lock host lookups * **Per-bucket rate limiting** — `sync.Map` of token buckets with per-bucket `sync.Mutex` * **Buffered log writes** — request logs sent to a buffered channel, batch-inserted by a background goroutine * **Background health checks** — periodic goroutine checks upstream health without blocking requests *** ## Building ### From source ```bash theme={null} go build -o aegis ./cmd/aegis/ ``` ### With version injection ```bash theme={null} go build -ldflags "-X main.version=1.0.0" -o aegis ./cmd/aegis/ ``` ### Requirements * Go 1.22 or later * No CGO required (uses `modernc.org/sqlite`, a pure Go SQLite implementation) ### Dependencies | Module | Purpose | | ----------------------------------------- | -------------------------------------------------------- | | `modernc.org/sqlite` | Pure Go SQLite driver (no CGO) | | `golang.org/x/crypto` | bcrypt password hashing, ACME/autocert for Let's Encrypt | | `gopkg.in/yaml.v3` | YAML configuration file parsing | | `github.com/cilium/ebpf` | eBPF program management for kernel-level DDoS protection | | `github.com/oschwald/maxminddb-golang/v2` | Embedded GeoLite2 database reader for geolocation | *** ## Logs & Retention Aegis stores traffic request logs and admin audit logs in SQLite. A background rotation cycle runs hourly to manage log retention, optional archiving, and cleanup. Image ### Retention Settings | Setting | Key | Default | Description | | ------------------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------- | | **Traffic log retention** | `logging.traffic_retention_days` | `30` | Days to keep traffic/request logs before deletion or archiving | | **Audit log retention** | `logging.audit_retention_days` | `30` | Days to keep admin audit log entries | | **Archive enabled** | `logging.traffic_archive_enabled` | `false` | Archive expired traffic logs to ZIP files instead of deleting directly | | **Archive retention** | `logging.traffic_archive_retention_days` | `90` | Days to keep archived ZIP files before deletion | All settings are configurable in Admin UI -> Settings. ### How Log Rotation Works Every hour, the log rotation cycle runs: 1. **Traffic logs older than retention period** — either archived to ZIP (if archiving enabled) or deleted directly 2. **Archived ZIP files older than archive retention** — deleted from disk 3. **Audit logs older than retention period** — pruned from SQLite When archiving is enabled, expired traffic logs are batch-exported (500 records per batch) to `traffic-{date}-{timestamp}.zip` files containing `traffic.jsonl` (newline-delimited JSON). This preserves a compressed historical record while keeping the SQLite database lean. ### Log Types | Log | Contents | Storage | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------- | | **Traffic log** | Every proxied request — host, source IP, method, path, status, action, matched rule, headers, WAF details, latency | SQLite `request_log` table | | **Audit log** | Every admin action — user, action type, resource ID, description, timestamp | SQLite `audit_log` table | | **Structured application log** | Server runtime events — JSON output via `slog` | stdout/stderr | *** ## Authentication * **Password-based** login with bcrypt hashing (minimum 12 characters) * **Passwordless magic link** authentication via email * Backup email address support * Per-session CSRF token protection * Session cookies with `HttpOnly`, `Secure`, `SameSite=Strict` *** ## Notifications * SMTP sending profile management (create, update, delete, test connection) * Encrypted SMTP password storage (AES-256-GCM) * Magic link authentication emails * Alert notification emails * Configurable `From` name and address *** ## Admin Dashboard * Real-time traffic analytics (request counts, block rates, 24h stats) * Top attacker IPs with request and block counts * Top attacked hosts breakdown * Attack trend timeline with allowed/blocked/detected bucketing * Rule effectiveness stats (hits per rule) * Geographic analytics with country enrichment and local cache * Live traffic streaming via Server-Sent Events (SSE) * Audit log of all admin actions