warpbox/docs/security-runbook.md

# Security Runbook

## Trusted Proxy Setup (Caddy)

Set `WARPBOX_TRUSTED_PROXY_CIDRS` to only the CIDRs of your reverse proxies/load balancers. Without this, WarpBox intentionally ignores forwarding headers and every request may appear to come from the proxy/container bridge, such as `172.30.0.1`.

Example:

```bash
WARPBOX_TRUSTED_PROXY_CIDRS=172.30.0.1/32
```

Caddy example:

```caddyfile
:443 {
  reverse_proxy warpbox: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`. Prefer the exact proxy IP as a `/32` when it is stable. If Caddy is on a changing Docker/Podman network, use that network's CIDR instead. You can find it with `docker network inspect <network>` or `podman network inspect <network>`.

## 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`