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:
@@ -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.
|
||||
Reference in New Issue
Block a user