fix!: default-deny HostConfig on create; check Mounts and read-only binds (#88)

[abienkowski]

Description

Closes #88.

On POST /containers/create the proxy checked only the host paths in HostConfig.Binds (and the top-level Volumes keys). HostConfig.Mounts, the bind mode and every other HostConfig field reached the daemon unchanged, so --mount type=bind,src=/,dst=/host, -v /etc/jwt_dir:/jwtdir:rw on a read_write: false volume, --cap-add SYS_ADMIN --pid host, --device and --group-add all went through. A policy without volumes let any bind through, and without a container_config the mutator returned early and did not force Privileged: false.

While testing, one more gap showed up: the daemon matches JSON field names without regard to case and keeps the last match. {"HostConfig":{"privileged":true}} produced a privileged container on Docker 29 even before this change (the mutator wrote "Privileged": false, and Go and Rust serialise privileged after it), and "securityopt": null cleared a forced SecurityOpt. The same applies at the top level ("image", "user", "hostConfig"): on main, {"Image":"chainsafe/lodestar:beacon","image":"alpine:latest"} passes the router and RegistryGate, which read Image, and the Go proxy's re-serialised body puts image last, so the daemon created an alpine:latest container (201 in the pre-fix integration run) and inside NetworkingConfig: with #87 merged, {"EndpointsConfig":{"default":{}},"endpointsconfig":{"evil-net":{}}} passes NetworkEndpointsGate, which reads the exact key only, and the daemon attaches evil-net (checked on Docker 29: NetworkSettings.Networks lists it).

What changes

• HostConfigGate (new, all three): default-deny on HostConfig. A key outside the allowlist must be absent or zero (null, false, 0, "", [], {}); MaskedPaths/ReadonlyPaths must be absent or null. Any-value fields: NetworkMode, RestartPolicy, LogConfig, CapDrop, ReadonlyRootfs, Init, AutoRemove, ConsoleSize, ShmSize, PortBindings, PublishAllPorts, Dns*, ExtraHosts, Tmpfs, Ulimits, the CPU/memory/pids/blkio-weight limits, ContainerIDFile. SecurityOpt entries must be in the policy's security_options or be no-new-privileges[:true]. PidMode, UTSMode, UsernsMode, Cgroup must be ""; IpcMode ∈ {"", private, shareable, none}; CgroupnsMode ∈ {"", private}; Isolation ∈ {"", default}; OomScoreAdj ≥ 0. The gate runs after the mutator, on the body that is forwarded, so Privileged: true stays neutralised (as documented and integration-tested) rather than denied.
• Case variants: a key that folds (ASCII case, Kelvin sign, long s, as Go's encoding/json does) to a known field name but is spelled differently is denied, at the top level, in HostConfig, in Mounts entries and BindOptions, and in NetworkingConfig (whether or not the policy forces network_mode). The other nested objects need no check: the mutator replaces RestartPolicy and LogConfig whole when the policy sets them and they are any-value otherwise; no gate reads Healthcheck or an endpoint entry's settings by key.
• MountSourceGate: no volumes means no binds. Binds options must be ro, rw, z, Z, nocopy, private, rprivate; a read_write: false volume needs ro (and not rw). Mounts: bind with Source equal to a policy volume, ReadOnly: true for read-only volumes, Propagation empty/private/rprivate, ReadOnlyNonRecursive zero; tmpfs without a Source; every other type denied.
• ContainerConfigMutator: forces Privileged: false on every create; leaves a non-object HostConfig for the gate (Rust panicked on one, TypeScript threw). Rust now applies log_driver/log_options, as Go and TypeScript already did.
• Spec (spec/docker_socket_policy.qnt, next to Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87's network_endpoints_model): module create_model with flag LEGACY_CREATE, rule property createChecksEveryField, security properties daemonSeesOnlyAllowlistedHostConfig, daemonMountsOnlyWhitelisted and daemonAttachesOnlyForcedNetwork (checked exhaustively over every single-field/bind/mount request of the model and the NetworkingConfig variants), 43 rows plus createSoundTest on create, and create_pre88, which witnesses the reproductions and the endpointsconfig gap. The state machine uses the create rules, with two new P0 invariants (hostConfigInAllowlist, hostMountsInWhitelist).
• Tests: the same 131 rows, by name, in Go, Rust and TypeScript (including the full Docker CLI 29 create body and a community.docker.docker_container-shaped body), and 17 integration checks against the real daemon. Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87's real-container starts (net-host, net-none) pass through the new gate unchanged.
• Docs: README HostConfig rules table, read_write enforcement, pipeline; spec/README.md; AGENTS.md and CONTRIBUTING.md counts.

Review notes

• Release: merging cuts v0.4.0 (breaking, below 1.0 = minor). The BREAKING CHANGE: footer is in the fix!: branch commit itself, so the default squash carries it. Simulated with scripts/release-version.sh v0.3.11 over the branch messages: bump=minor tag=v0.4.0; the same with a plain fix: squash title.
• Breaking: creates that set a non-allowlisted field, a volume/image mount, a shared/slave propagation, a read-only volume without :ro, or any bind under a policy without volumes are now 403. --runtime, --gpus, --sysctl, --device*, --group-add, --cap-add, --link, --volumes-from, --security-opt systempaths=unconfined and the host namespaces are denied.
• make verify BACKEND=typescript on the main spec took 737 s locally (14 traces/s) with the create rules in the state machine; worth watching in CI.
• Order with fix: route image pulls on the query string and normalise image references in all three (#83, #84) #91: the router picks the policy from Body["Image"] and RegistryGate parses that same key; a lone image (no Image) is denied by the router with image field is required, and Image plus a variant passes the router and is denied by HostConfigGate in the chain, so no create with a variant is forwarded whichever gate runs first.
• Follow-up drafted (not filed): settings inside NetworkingConfig endpoint entries (Links, DriverOpts, IPAMConfig, Aliases) are forwarded as sent under a forced bridge/named network_mode or with no forced mode, so endpoint Links passes while HostConfig.Links is denied.
• Go keeps its escaped-colon handling in Binds (\:); Rust and TypeScript split on : as the daemon does. The daemon rejects every spec where the two readings differ in the mode, so no row depends on it.
• The policy's ports field is parsed but enforced nowhere, so PortBindings stays any-value (documented).
• Not changed here: when a policy does not force network_mode, NetworkMode: host / container:<id> and any EndpointsConfig still pass (any-value, per Container create: default-deny HostConfig, validate Mounts and the bind read-only mode #88 and Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87); the settings inside an endpoint entry (Links, IPAMConfig, DriverOpts, …) are forwarded as sent under a forced mode, as Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87 does.
• Integration: the read-only Mounts allow check accepts the daemon's 400 (bind source path does not exist): Mounts binds are not auto-created like Binds, and /etc/jwt_dir does not exist on the test daemon's host.

Verification

• Spec: create passes createSoundTest and 43 rows; create_pre88 asserts the three security properties fail and that the Container create: default-deny HostConfig, validate Mounts and the bind read-only mode #88 reproductions and the endpointsconfig variant were allowed. Mutations: dropping the HostConfig case-variant check fails caseVariantZeroSecurityOptDenied and createSoundTest; dropping the read-only clause for Mounts fails mountBindReadOnlyVolumeWritableDenied and createSoundTest; dropping the NetworkingConfig variant check fails both networkingConfigVariant* rows and createSoundTest.
• Before the fix (test commit on top of main with Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87 and fix: route image pulls on the query string and normalise image references in all three (#83, #84) #91): 73 rows fail in Go, 74 in Rust and TypeScript (the extra one is the old Rust/TS bind message), plus the two Rust and one TypeScript tests that pinned the old behaviour; the Rust row test panics on "HostConfig": "x" (as_object_mut().unwrap()) and TypeScript throws Cannot create property 'NetworkMode' on string 'x'. Integration on the pre-fix Go proxy:

  FAIL: create with Mounts bind of / -> 403 (expected 403 with "mount source "/" is not in the whitelist", got 404: {"message":"No such image: chainsafe/lodestar:beacon"})
  FAIL: create with read-only volume bound :rw -> 403 (expected 403 with "volume mount "/etc/jwt_dir" must be read-only (:ro)", got 404: ...)
  FAIL: create with CapAdd -> 403 (expected 403 with "HostConfig.CapAdd is not allowed for service beacon", got 404: ...)
  FAIL: create with PidMode host -> 403 (expected 403 with "HostConfig.PidMode value "host" is not allowed", got 404: ...)
  FAIL: create with lower-case privileged -> 403 (expected 403 with "HostConfig.privileged is not allowed", got 404: ...)
  FAIL: create with an extra lower-case image -> 403 (expected 403 with "image is not allowed for service beacon (the daemon reads it as Image)", got 201: {"Id":"c4393c1b…","Warnings":[]})
  FAIL: create with lower-case endpointsconfig -> 403 (expected 403 with "NetworkingConfig.endpointsconfig is not allowed", got 404: ...)
  80 PASSED, 14 FAILED
  

• This branch (rebased on Containers created with a policy network_mode do not start: NetworkingConfig still names the "default" network #87 and fix: route image pulls on the query string and normalise image references in all three (#83, #84) #91): make test-all Go 119 (131 subtests in TestHostConfigRows), Rust 146, TS 300 (1 skipped); make lint-all, make build-all, make typecheck, make test-spec, make verify BACKEND=typescript, make test-release pass; integration ALL 94 TESTS PASSED for Go, Rust and TS.

Type of change

• Bug fix
• New feature
• Breaking change
• Documentation update

Implementation(s) changed

• Go
• Rust
• TypeScript
• Quint specification
• CI / infrastructure

Testing

• Unit tests pass (make test-all)
• Integration tests pass (94 per implementation)
• Quint verification passes (make verify, make test-spec)
• New tests added for the change

Checklist

• I have read CONTRIBUTING.md
• My code follows the project's coding style
• I have updated documentation as needed

🤖 Generated with Claude Code