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>
182 lines
11 KiB
Markdown
182 lines
11 KiB
Markdown
# 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.
|