feat/security

Reviewed-on: #2

docs/geoip-guide.md

@@ -0,0 +1,19 @@
+# GeoIP Guide (Planning)
+
+This project intentionally does not enable GeoIP enforcement yet.
+
+Planned integration target: `github.com/rabuchaim/geoip2fast`.
+
+## Recommended approach
+
+1. Load one shared GeoIP provider instance at startup.
+2. Add a small in-memory cache keyed by IP with TTL.
+3. Apply lookup timeout and fallback to `unknown` values on failures.
+4. Use results first in the admin security detail pane.
+5. Add aggregated statistics only after detail pane behavior is stable.
+
+## Why this is safe
+
+- No request path should fail because GeoIP lookup fails.
+- Lookup cost stays bounded with caching.
+- Security decisions remain independent from GeoIP quality.

docs/security-runbook.md

@@ -0,0 +1,40 @@
+# Security Runbook
+
+## Trusted Proxy Setup (Caddy)
+
+Set `WARPBOX_TRUSTED_PROXY_CIDRS` to only the CIDRs of your reverse proxies/load balancers.
+
+Example:
+
+```bash
+WARPBOX_TRUSTED_PROXY_CIDRS=10.0.0.0/8,192.168.0.0/16
+```
+
+Caddy example:
+
+```caddyfile
+:443 {
+  reverse_proxy 127.0.0.1:8080 {
+    header_up X-Forwarded-For {http.request.remote.host}
+    header_up X-Real-IP {http.request.remote.host}
+  }
+}
+```
+
+WarpBox will trust `X-Forwarded-For` only if the direct remote IP is inside `WARPBOX_TRUSTED_PROXY_CIDRS`.
+
+## IP Ban Operations
+
+- Use temporary bans by default.
+- Use `ban_until` only for active incidents requiring explicit windows.
+- Before unbanning, inspect related activity and alerts for repeated abuse patterns.
+- For destructive actions (`bulk_unban`, `unban_all`), require explicit confirmation.
+
+## Tuning Guidance
+
+- Low traffic deployments: reduce max-attempt thresholds to catch abuse faster.
+- High traffic deployments: increase windows and max-attempts incrementally to reduce false positives.
+- Watch for:
+  - repeated `auth.admin.failed`
+  - repeated `security.scan`
+  - frequent `security.upload_limit`