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.

​

WAF Engine

The Aegis WAF engine evaluates every proxied request against a chain of compiled rules. Each proxy host independently runs in off, detect, or enforce mode.

---

​

WAF Modes

---

​

Built-in Capabilities

---

​

Detection Categories

The built-in rule library covers the following attack classes:

---

​

IP Whitelists

IP whitelists let you exempt trusted source IPs from WAF enforcement. This is distinct from the Allow Lists access control system — whitelists are per-host CIDR lists configured directly on the proxy host.

​

How Whitelists Work

When a request arrives from a whitelisted IP:

1. The IP is checked against the host’s whitelist_cidrs list (compiled to net.IPNet for fast matching)
2. If the IP matches, the request is marked as whitelisted
3. All subsequent WAF checks still run — method restriction, body size, CORS, rate limiting, and rule chain evaluation — but any match that would normally be blocked is downgraded to detect (logged but allowed through)
4. The request is proxied to the upstream regardless of WAF matches

This means whitelisted traffic is still fully evaluated and logged — you see what would have been blocked — but enforcement is suppressed. This is useful for:

• Internal monitoring tools that trigger WAF rules with legitimate traffic
• Penetration testing IPs where you want visibility without blocking
• Trusted office/VPN ranges that should never be interrupted

​

Whitelist vs Allow List

​

Evaluation Order

The WAF evaluates IP lists in this order:

1. Allow list (if attached) — if the IP is NOT in the allow list, block immediately
2. Whitelist — if the IP IS in the whitelist, mark as whitelisted (suppress enforcement)
3. IP timeouts — check for active temporary blocks
4. Blacklist — check static blacklist CIDRs
5. WAF rules — evaluate rule chain (whitelisted IPs get detect-only)

---

​

Auto Blocking

Aegis can automatically block source IPs when a WAF rule fires with action: block and the matched rule’s severity meets or exceeds a configured threshold. Auto blocking supports two action modes: permanent blacklist or temporary timeout.

​

How It Works

1. A request is blocked by the WAF
2. Aegis compares the matched rule’s severity against the configured minimum severity threshold
3. If the severity meets or exceeds the threshold, auto blocking fires
4. Depending on the configured action mode:
   • Blacklist — the IP is added as a permanent /32 CIDR entry to the host or global blacklist
   • Timeout — the IP is added to a temporary block table with an expiration timestamp

Requests that are only detected or logged (not actively blocked) do not trigger auto blocking.

​

Configuration

Four settings control auto blocking behavior: All settings are configurable in Admin UI -> Settings.

​

Severity Threshold

​

Blacklist vs Timeout

When action is timeout, the IP is blocked for the number of seconds configured in waf.auto_blacklist_timeout_seconds (default: 1 hour). After expiration, the IP can access the host again. If the IP triggers another WAF block, a new timeout is created.

​

Scope

​

IP Timeout Lifecycle

When auto blocking uses timeout mode:

1. WAF blocks a request that meets the severity threshold
2. An IPTimeout record is created with expires_at = now + timeout_seconds
3. On every subsequent request, the WAF checks active timeouts before evaluating rules
4. If an active (non-expired) timeout exists for the client IP, the request is blocked immediately
5. Expired timeouts are cleaned up automatically during the next query

---

​

Geolocation

Aegis enriches traffic analytics with city and country geolocation using the embedded GeoLite2 city database. Used for:

• Dashboard Traffic Origins
• Analytics geographic distribution
• City and country enrichment on traffic and top-IP views

Setup:

1. Start Aegis normally
2. Open Aegis Settings
3. Confirm the Geolocation panel shows the embedded GeoLite2 database status

Aegis opens a shared GeoIP reader at startup and performs lookups internally instead of calling an external API. Lookups are cached locally in SQLite so repeated dashboard and analytics loads stay fast. If the embedded GeoIP database cannot be opened, the dashboard reports that geographic analytics are unavailable.