Daniel Legt
73bd14572d
All checks were successful
Build and Publish Docker Image / deploy (push) Successful in 1m41s
- Implement storage backend deletion, which automatically resets default storage settings and user-specific overrides when a backend is removed. - Add unit tests covering the delete action and its cleanup side effects. - Improve admin UI responsiveness, fixing table scrolling, flex wrapping, and text truncation for long storage backend names. - Update security documentation to clarify trusted proxy configurations and explain how trusted proxies are protected from automatic bans.
70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
# Security Proxy Notes
|
|
|
|
Warpbox usually runs behind a reverse proxy such as Caddy. IP-based quotas,
|
|
manual bans, and automatic bans depend on Warpbox seeing the real client IP.
|
|
|
|
## Caddy
|
|
|
|
Use this shape when Caddy and Warpbox are on the same host:
|
|
|
|
```Caddyfile
|
|
warpbox.dev {
|
|
reverse_proxy 127.0.0.1:6070 {
|
|
header_up X-Forwarded-For {http.request.remote.host}
|
|
header_up X-Real-IP {http.request.remote.host}
|
|
}
|
|
}
|
|
```
|
|
|
|
By default, Warpbox trusts `X-Forwarded-For` and `X-Real-IP` so simple Docker,
|
|
Podman, and systemd deployments work without extra setup. This is convenient,
|
|
but it is only safe when the Warpbox port is not directly reachable by the
|
|
public internet.
|
|
|
|
## Trusted Proxies
|
|
|
|
For stricter deployments, set `WARPBOX_TRUSTED_PROXIES` to the IPs or CIDR
|
|
ranges that are allowed to provide forwarded headers. Use proxy IPs only.
|
|
|
|
```env
|
|
WARPBOX_TRUSTED_PROXIES=127.0.0.1,::1,172.30.0.1
|
|
```
|
|
|
|
When this value is set, Warpbox trusts `X-Forwarded-For` and `X-Real-IP` only
|
|
if the TCP peer address is inside one of those trusted ranges. Requests coming
|
|
directly from any other IP ignore forwarded headers and use the socket address.
|
|
|
|
Recommended values:
|
|
|
|
- Same-host Caddy with systemd: `127.0.0.1,::1`
|
|
- Docker/Podman bridge gateway: add the exact gateway IP, for example `172.30.0.1`
|
|
- Docker bridge networks: use a CIDR such as `172.16.0.0/12` only if the exact gateway changes often
|
|
- Private reverse-proxy networks: add the exact private CIDR used by the proxy
|
|
|
|
Warpbox prefers the first public address in `X-Forwarded-For` when a trusted
|
|
proxy sends a chain. Loopback addresses and trusted proxy addresses are also
|
|
protected from manual and automatic bans so a bad header setup cannot ban Caddy,
|
|
the container gateway, or Warpbox itself.
|
|
|
|
## Direct Exposure
|
|
|
|
If you expose Warpbox directly without Caddy, either leave
|
|
`WARPBOX_TRUSTED_PROXIES` empty and ensure clients cannot spoof headers at the
|
|
network edge, or set it to a value that does not include public clients. Direct
|
|
public exposure is not recommended; use a reverse proxy for TLS and request
|
|
normalization.
|
|
|
|
## Ban Behavior
|
|
|
|
Active bans return:
|
|
|
|
```text
|
|
HTTP/1.1 403 Forbidden
|
|
Content-Type: text/plain; charset=utf-8
|
|
|
|
forbidden
|
|
```
|
|
|
|
Blocked requests are still written to the JSON logs and appear under
|
|
`/admin/logs` with `source=ban`.
|