H5: Security review, and fixes for connection-slot exhaustion

docs/SECURITY_REVIEW.md lists the scope, nine findings and what was done.

- High, fixed: a peer that connects and stops answering kept its ENet slot
  for up to 15 s after being turned away, so one address could fill every
  slot. Flood refusals now disconnect at once (reason in the disconnect
  data, which NetClient now honours for REASON_BUSY), peers told to leave
  get 1 s to acknowledge, and when slots run short the longest-waiting
  silent guest makes room.
- Medium, mitigated: ENet holds half-open slots for spoofed CONNECTs that
  the script never sees. The host now has 512 slots (NetServer.peer_slots).
- Medium, fixed: SourceLimiter, handshakes per source and the list
  server's per-address cap count an IPv6 /64 as one source.
- Low, fixed: CommandLog refuses a header with non-numeric fields instead
  of raising errors.
- tools/godot.sh unsets DISPLAY and WAYLAND_DISPLAY so the engine's error
  alerts can never reach the host desktop.
- A test fixture's 10.0.0.9 is now the documentation address 192.0.2.9.

Tests: 4 new handshake tests with real non-acknowledging ENet peers,
test_source_limiter (3), a CommandLog type test. make check, make fuzz,
make client-check, make discovery-check and make soak-selfcheck pass.

Closes #58

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 02:36:36 -05:00
co-authored by Claude Opus 5.5
parent e3c0d2814c
commit 9b5064d7a8
14 changed files with 515 additions and 23 deletions
+13 -6
View File
@@ -160,13 +160,14 @@ People join a server three ways, none needing a third-party service:
a CHALLENGE carrying a token derived from a per-start secret and the sender's
address and port, and lists the server only when a REGISTER echoes it. Servers are
listed under the address their packets come from, never a claimed one. Entries
expire after 45 s, with at most 8 per address and 256 in all. Clients ask for the
expire after 45 s, with at most 8 per address (per /64 for IPv6) and 256 in all. Clients ask for the
list four servers per page, one page after another.
The messages are in `NetDiscovery`. Every QUERY is padded to 512 bytes and no answer
is larger, so neither the beacon nor the list server can amplify a spoofed request.
Both rate-limit each source address (`SourceLimiter`: 20 packets a second, at most
4,096 addresses tracked per second).
Both rate-limit each source (`SourceLimiter`: 20 packets a second, at most 4,096
sources tracked per second). A source is an IPv4 address, or an IPv6 address's whole
/64, since one ordinary connection is handed a /64 (H5).
**Lobby, backfill and late arrivals.** People who connect during the lobby or the
countdown take places (`Match.join()`); bots are only added when the match starts,
@@ -199,9 +200,15 @@ likes. The server's defences, and the tests that attack them
commands and an exact length, or it is dropped whole. At most 32 game packets per
player are kept per poll. Anything on the control channel after the handshake is
dropped.
- **Bounded connections.** At most 32 new connections per address per 10 s and 8
handshakes in progress per address (`REASON_BUSY`), a 5 s handshake timeout, and
ENet's own peer limit.
- **Bounded connections.** At most 32 new connections per source per 10 s and 8
handshakes in progress per source (`REASON_BUSY`), and a 5 s handshake timeout.
No slot is left to a silent stranger for long (H5): a connection turned away for
flooding is dropped at once, with the reason only in the disconnect's data; a peer
told to leave has 1 s to acknowledge before it is cut off; and when ENet's slots
run short, the guest that has waited longest for its HELLO makes room. The host
has 512 slots whatever the player limit, because ENet takes a slot for every
CONNECT before the sender has proved its address and never reports those
half-open slots to the script; see docs/SECURITY_REVIEW.md.
- **Parsers.** Every decoder refuses malformed input by returning an empty result,
never by raising an error. `make fuzz` feeds 1,000,000 mutated and random messages
to all of them, the snapshot receiver and the list server, and checks for engine
+181
View File
@@ -0,0 +1,181 @@
# Security review (H5)
Reviewed on 2026-11-14 against commit `e3c0d28` plus the fixes below. Tidewall has no
accounts, payments, chat or user-generated files, so the review is mostly about two
things: a hostile peer must not crash a server, corrupt a match or lock people out,
and the public repository must not leak anything about the machines it is built on.
Severity follows the usual scale. **High** and **critical** findings are fixed, with
regression tests. Lower ones are fixed when the fix is small and safe, and otherwise
recorded here as accepted, with the reason.
## Scope
| Area | Files | How it was checked |
|---|---|---|
| Game handshake and transport | `src/net/net_protocol.gd`, `net_server.gd`, `net_client.gd`, `source_limiter.gd` | Read; `test/net/test_net_handshake.gd` (20 tests, 4 new) |
| Player input | `src/net/net_snapshot.gd` (`decode_input`), `src/sim/player_command.gd`, `src/server/net_game.gd`, the simulation's use of each command field | Read every use of `selection`, `material`, `view_lag`, `tick`; `test/server/test_hostile_client.gd` |
| Server-to-client messages | `net_snapshot.gd`, `net_world.gd`, `net_fx.gd`, `net_feed.gd` | Read; `make fuzz` |
| LAN discovery and list server | `src/net/net_discovery.gd`, `src/server/server_beacon.gd`, `list_server.gd` | Read; `test/net/test_net_discovery.gd`, `test/server/test_list_server.gd` |
| Health endpoint | `src/server/health_server.gd` | Read; `test/server/test_health_server.gd` |
| Server configuration and files | `src/server/server_config.gd`, `command_log.gd`, `src/client/game_settings.gd`, `input_settings.gd`, `key_bindings.gd` | Read; `test_command_log.gd` (1 new test) |
| Packaging | `packaging/docker/`, `packaging/systemd/`, `packaging/server/`, `packaging/dist/` | Read; `make server-package-check` covers non-root and read-only |
| Repository contents | every tracked file and the whole git history | `git grep` and `git log -p` for keys, passwords, tokens, private and internal addresses, host names and home paths |
## Findings
### H5-1 High, fixed: one address could hold every connection slot
ENet has a fixed number of peer slots, and a peer keeps its slot until ENet hears it
leave or times it out (5 to 15 s). The server turned every unwanted peer away with
`peer_disconnect_later`, which waits for the REJECT to be acknowledged. A client that
connects and then stops answering never acknowledges, so:
- each connection refused for flooding (`REASON_BUSY`) kept its slot for up to 15 s,
and a single address could open them faster than they expired, until the server had
no slots left and real players' connections were silently dropped;
- silent guests (8 per address, each for the 5 s handshake timeout) did the same from
four addresses.
**Fix** (`NetServer`):
- A connection refused for flooding is dropped at once with `peer_disconnect_now`; the
reason travels as the disconnect's data. `NetClient` now accepts `REASON_BUSY` from
that data (`NetProtocol.is_server_reason`), so the player still reads "Too many
connections from your address".
- A peer told to leave has `leave_grace_msec` (1 s) to acknowledge, then is cut off.
- When the slots run short (one left), peers already told to leave go first, then the
guest that has waited longest for its HELLO. An honest client sends HELLO within one
round trip, so it is never the oldest guest for long.
**Tests:** `test_a_flood_from_one_address_cannot_hold_the_slots`,
`test_silent_guests_make_room_for_a_newcomer`,
`test_a_peer_that_never_acknowledges_leaving_is_cut_off`,
`test_busy_reaches_the_client_without_a_reject_message`. The silent peers in these tests
are real ENet hosts that complete the connection and then never service their socket
again.
### H5-2 Medium, mitigated: half-open connections from spoofed addresses
ENet takes a slot for each CONNECT it receives and answers it, before the sender has
shown it can receive at that address. The slot is held for ENet's own timeout, and
the script is never told about it (Godot reports a peer only once the handshake
completes), so nothing in GDScript can see or evict it. Someone able to send packets
with forged source addresses could keep every slot half-open with a few packets a
second, and each answer goes to the forged address.
This is a property of ENet, not of Tidewall's code, and fixing it properly would mean
changing the engine. **Mitigation:** the server now creates 512 ENet slots whatever
its player limit (`NetServer.peer_slots`), so filling them takes hundreds of forged
packets every few seconds instead of a few dozen. The per-source limits and the
eviction in H5-1 still govern every connection that completes. This has not been
tested against a real spoofing attack: the tests can't forge source addresses. A
public server operator's best protection is a network that drops forged packets and
an upstream per-source rate limit.
### H5-3 Medium, fixed: one IPv6 connection counted as millions of senders
`SourceLimiter` and the per-address caps keyed on the full address. An ordinary IPv6
connection is given a whole /64, so one user could rotate addresses to get a fresh
allowance each time, fill the limiter's table of 4,096 sources (locking everyone else
out for the rest of the window), take the list server's 256 entries (every address
there can answer its own CHALLENGE), or hold more handshakes than the per-address cap.
**Fix:** `SourceLimiter.source_of()` maps an IPv6 address to its /64 (and an
IPv4-mapped address to the IPv4 address). The limiter, the server's handshakes per
source and the list server's entries per address all count by source.
**Tests:** `test/net/test_source_limiter.gd` (3 tests).
Accepted: someone holding many /64s (a /48 has 65,536) or many IPv4 addresses can
still fill the list server or the limiter's table. The list server is optional,
self-hosted and has nothing to steal; entries expire in 45 s.
### H5-4 Low, fixed: a damaged replay file could raise script errors
`CommandLog.from_bytes` checks every length, but took JSON values with `int()` without
checking their type, so a hand-edited header holding an array or object where a
number belongs raised an engine error instead of being refused. Replay files are only
read from a path given on the command line, so this was never reachable from the
network. **Fix:** only numbers and booleans are read. **Test:**
`test_a_header_with_the_wrong_types_is_refused_without_errors`.
### H5-5 Low, accepted: a server can make a client spend memory
A client trusts the server it chose to join for the size of the world: every WORLD,
SNAPSHOT, FX and FEED message is length-checked and validated (and fuzzed), but a
hostile server could still send many valid pieces or large reliable messages (ENet's
limit is 32 MB a packet). The player picked the server, and the worst case is the game
running out of memory or being closed. Not worth bounding further for v1.0.
### H5-6 Low, accepted: names are not authenticated
There are no accounts, so anyone can join under any name. Names are cleaned (control,
formatting, bidirectional and private-use characters removed, 16 characters) and made
unique on the server with a number. The UI never interprets markup in names (no
BBCode-enabled labels exist in `src/`).
### H5-7 Low, accepted: claimed view lag
A command says how far behind the shooter was seeing (`view_lag`), and the server
rewinds other players by that much when judging a hit. A modified client can always
claim the maximum, `Tuning.LAG_COMPENSATION_MAX_TICKS` (15 ticks, 0.5 s). This is the
usual trade-off of lag compensation and is bounded. Nothing else in a command can
claim a position, hit, target or item (see "Trusting nothing from clients" in
docs/ARCHITECTURE.md).
### H5-8 Info: release builds stop on a null call
Godot release templates end the process (exit 139) on a GDScript call on null, where a
debug build reports an error and carries on. A remote input that reached such a call
would therefore stop a packaged server. The parsers and the simulation are fuzzed and
tested in debug builds, where any script error fails the run, and the server packages
restart on failure (`Restart=on-failure`, `restart: unless-stopped`). Recorded so a
future crash report is read with this in mind.
### H5-9 Info: the container base image is not pinned by digest
`packaging/docker/Dockerfile` starts `FROM debian:13`. A rebuild picks up Debian's
security updates, which is what a server image wants, at the cost of exact
reproducibility. The engine inside is checked against `tools/engine.sha512`.
## Checked and found sound
- **Handshake.** One HELLO per guest, exact lengths, strict UTF-8 (overlong forms and
surrogates refused), a 96-byte cap, nothing on the control channel after joining,
32 game packets per player per poll.
- **Input.** An INPUT has an exact length and at most `MAX_INPUT_COMMANDS` commands.
Every field is clamped on decode. A tick behind the last one taken, or more than
`MAX_COMMAND_LEAD_TICKS` ahead, is ignored. `selection` is bounds-checked in
`Inventory.select` and `Building.target` (which returns null, handled by
`Building.check`), `material` by `Materials.is_valid`, `view_lag` clamped in
`Weapons`.
- **Discovery and list server.** No answer is larger than the 512-byte QUERY that asked
for it, so neither can amplify a forged request; a REGISTER is answered with a
smaller CHALLENGE. The token is a SHA-256 of a per-start random secret, address and
port, so a server can only be listed at an address where it receives. A server's
CHALLENGE handling only accepts one from a list server it chose. Both rate-limit
each source and bound packets handled per frame.
- **Health endpoint.** Loopback by default, at most 8 connections, 2 KiB and 2 s per
request, `GET /health` only, no input reflected in the answer. The Docker health
check talks to it on loopback inside the container.
- **Configuration.** Unknown or malformed options are errors; a config file can't
include another; `--health-bind` must be an IP address; server names are cleaned
like player names. Files are read only from paths the operator gives.
- **Client settings.** Read with `ConfigFile` from the player's own `user://`, each
value type-checked with a fallback.
- **Packaging.** The Docker service runs as an unprivileged user with a read-only root,
all capabilities dropped and `no-new-privileges`; only the game port is published.
The systemd unit uses `DynamicUser`, `ProtectSystem=strict`, `ProtectHome`,
`PrivateDevices`, an empty capability set and restricted address families. The
launcher quotes its arguments and keeps engine state in its own directory.
- **Repository.** No keys, passwords, tokens, internal host names, private network
addresses or home paths in any tracked file or in history. Example addresses use the
documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32);
one test fixture that used 10.0.0.9 now uses 192.0.2.9. Every commit is authored by
the project's own identity.
## Not covered
- No external penetration test or review by a second person.
- Nothing was tested against forged source addresses (H5-2) or over a real WAN.
- Godot and ENet themselves were not audited; the engine is the official 4.7.2 build,
checked against its published SHA-512 sums.