Files
chess-endgame-trainer/docs/security.md
T
owenrees b41c8bf1a6 Fix deploy docs: Bot Fight Mode status and probe reinstall (#167)
* Record that Bot Fight Mode is off

Both docs still claimed Bot Fight Mode was enabled. It is off; the Caddy
origin allowlist stays in force. Neither CI nor the on-box probe can get
past it on the free plan, so re-enabling needs the changes tracked in #153.

* Note that the probe must be installed to two places

The timer runs /usr/local/sbin/chesstrainer-probe, not the copy under
/opt/chesstrainer/src. Say so next to the install block, as the backup
section already does, so a changed deploy/probe does not silently drift
from what the timer runs.
2026-11-13 13:57:33 +01:00

192 lines
7.3 KiB
Markdown

# Login and edge security
The login surface is protected in layers. The application throttle is the
primary control; Cloudflare is the edge backstop for volume. There is no
origin-level fail2ban for HTTP logins, because it would require storing raw IP
addresses and would ban Cloudflare edge addresses on this deployment.
## Current production configuration
- Caddy accepts only Cloudflare's published ranges and forwards
`CF-Connecting-IP` as `X-Forwarded-For`. The ranges are refreshed hourly by
`chesstrainer-cloudflare-ranges.timer`.
- `TRUST_FORWARDED_FOR=true`, so the app throttles by the real visitor address.
- Cloudflare Bot Fight Mode is off. The Caddy origin allowlist above stays in
force; re-enabling is tracked in #153.
- The free-plan login flood rule allows 10 login POSTs per 10 seconds per IP and
blocks for 10 seconds.
The short Cloudflare block is rate smoothing, not a credential lockout. The
application's 5-per-login and 10-per-address failures in a 15-minute window are
the real control.
## 1. Application login throttle
`ChesstrainerWeb.LoginThrottle` counts failures in two buckets:
| Bucket | Limit | Window |
|---|---|---|
| Normalised login (email or username) | 5 failures | 15 minutes |
| Client address | 10 failures | 15 minutes |
Blocked attempts are rejected before the database lookup and bcrypt, so they do
not consume password-hashing CPU. A successful login clears the login bucket
only, keeping the address bucket in place so one address cannot spray many
accounts.
The bucket keys are boot-scoped HMACs. Raw addresses and raw login identifiers
are never stored in ETS or written to the application logs. The login form
returns the same generic error for unknown accounts, bad passwords and
unconfirmed accounts.
Configured in `config/config.exs`:
```elixir
config :chesstrainer, ChesstrainerWeb.LoginThrottle,
window_ms: :timer.minutes(15),
max_per_login: 5,
max_per_ip: 10,
confirmation_cooldown_ms: :timer.minutes(15)
```
`auth.login.failed` and `auth.login.throttled` are documented in
`docs/logging.md`.
## 2. Real client IPs behind Cloudflare and Caddy
The production chain is:
```text
Internet
└─ Cloudflare
└─ Caddy :443
└─ Phoenix 127.0.0.1:4100
```
Caddy ignores incoming `X-Forwarded-*` values by default and replaces them with
the immediate peer address. Behind Cloudflare that peer is a Cloudflare edge
node, so without configuration the app would throttle whole Cloudflare POPs
rather than individual visitors.
`deploy/Caddyfile` fixes this by:
1. accepting only Cloudflare's published ranges, and
2. setting `X-Forwarded-For` from Cloudflare's single-value `CF-Connecting-IP`
header.
That keeps `TRUST_FORWARDED_FOR=true` safe: direct clients cannot reach the app
through Caddy, so they cannot forge the header.
`deploy/Caddyfile` imports `cloudflare-ranges.caddy`. The file is generated by
`deploy/update-cloudflare-ranges.sh`; do not edit it by hand.
The script is run hourly by `chesstrainer-cloudflare-ranges.timer`. It:
- downloads <https://www.cloudflare.com/ips-v4> and
<https://www.cloudflare.com/ips-v6>,
- rejects empty or malformed responses,
- validates the candidate Caddyfile,
- reloads Caddy only when the ranges changed.
If the download, validation or Caddy reload fails, the previous ranges stay in
place.
Install and run it:
```sh
sudo install -m 0755 /opt/chesstrainer/src/deploy/update-cloudflare-ranges.sh \
/usr/local/sbin/chesstrainer-update-cloudflare-ranges
sudo install -m 0644 /opt/chesstrainer/src/deploy/cloudflare-ranges.caddy \
/etc/caddy/cloudflare-ranges.caddy
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.service \
/etc/systemd/system/chesstrainer-cloudflare-ranges.service
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.timer \
/etc/systemd/system/chesstrainer-cloudflare-ranges.timer
sudo systemctl daemon-reload
sudo systemctl enable --now chesstrainer-cloudflare-ranges.timer
sudo systemctl start chesstrainer-cloudflare-ranges.service
```
If `/opt/chesstrainer/src/deploy` is not present on the VPS, create the same
four files directly with `sudo tee` from the canonical contents in `deploy/`.
The timer only uses the installed copies.
Check the timer and last run:
```sh
systemctl list-timers chesstrainer-cloudflare-ranges.timer
systemctl status chesstrainer-cloudflare-ranges.service
journalctl -u chesstrainer-cloudflare-ranges.service --since "24 hours ago"
```
Apply the site block by hand on the shared Caddy host, then validate and
reload:
```sh
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```
Direct requests to the origin with a spoofed `CF-Connecting-IP` must receive
`403 Access Denied`; only Cloudflare's ranges should reach the Phoenix app. A
host firewall allowlist for Cloudflare on ports 80 and 443 is a useful
defence-in-depth addition.
## 3. Cloudflare edge rate limiting
This is for connection and request floods, not credential guessing. The
application already stops password attempts cheaply.
The production rule is the free-plan version:
| Setting | Value |
|---|---|
| Name | Login POST flood |
| Expression | `(http.request.method eq "POST" and http.request.uri.path in {"/admin/log-in" "/users/log-in"})` |
| Characteristic | IP |
| Period | 10 seconds |
| Requests | 10 |
| Action | Block |
| Duration | 10 seconds |
Because the free plan only offers a 10-second period and a 10-second block, this
is a burst limiter rather than a lasting ban. An attacker can retry after ten
seconds, but the application still stops that login after five failures and that
address after ten failures within fifteen minutes. A slow attacker staying under
10 requests per 10 seconds never gets to make useful guesses because of the app
throttle.
Bot Fight Mode is off. On the free plan it cannot be skipped for CI or for the
on-box health probe, so a datacenter `curl` gets a 403 while the site itself is
healthy; #153 covers the gate and probe changes needed before it goes back on.
If the plan later gains longer rate-limit windows or managed WAF rules, raise
the block duration and consider a broader site-wide rule, such as 100 requests
per 10 seconds per IP with a managed challenge. Use Under Attack Mode during an
active incident.
### Registration cannot be limited this way
`/users/register` is a LiveView. The form submit is a LiveView event sent over
the shared `/live/websocket` connection, not a `POST /users/register` request.
Cloudflare therefore cannot count account creations with a rule on the
registration path.
A Cloudflare rule on `GET /users/register` only limits page opens; a bot can
open one page and submit many registrations over the socket. If registration
spam becomes a problem, add an application-level registration throttle keyed by
`ChesstrainerWeb.ClientAddress.from_socket/1`, and/or add Cloudflare Turnstile
to the form.
While `PRELAUNCH=true`, registration is blocked entirely by the prelaunch plug
and LiveView mount redirect.
## 4. Why not fail2ban for HTTP?
fail2ban needs the raw client address to build a firewall rule. The application
deliberately logs only a boot-scoped HMAC, and this deployment sits behind
Cloudflare. Banning the address that reaches the origin would ban Cloudflare
edges, not attackers.
fail2ban remains useful for services that terminate connections directly on the
VPS, such as SSH. It is not part of the HTTP login defence.