The Docker suite does not cover the MASQUERADE rule it is named for

[FAZuH]

Found by mutation testing while verifying the audit refactor (commit 0a1e63c). The suite is green, but a piece of the behaviour the Docker tests exist to verify is not actually verified there.

The experiment

Mutating build_masquerade_args in crates/natmap/src/iptables.rs:184 from MASQUERADE to ACCEPT — a real behaviour change, the POSTROUTING rule no longer masquerades:

cargo test -p lab-ops_natmap                    -> 1 FAILED (masquerade_args_matches_ctn_ip)
cargo test -p lab-ops --test natmap_docker      -> 34 passed, 0 failed

The unit suite caught it. The Docker suite, whose whole reason for existing is to run privileged containers with real iptables, did not notice at all. The mutant was reverted and the tree is clean.

Why it matters

The audit already found 19 tests that pass vacuously (#44 covers those). This is the other half of the problem: a test that is green because it never checked. Here the gap is that the Docker harness greps for DNAT and never for the MASQUERADE rule it installs, so the one rule that makes source-IP preservation work end to end has no integration-level check.

What to build

The Docker suite asserting the rules it actually installs, not just the ones it greps for today.

Suggested: a mapping scenario that installs a Docker port mapping and then asserts the full rule set in iptables-save output — the DNAT, the FORWARD ACCEPT, the POSTROUTING MASQUERADE, and the comment. The two loopback-MASQUERADE tests that exist today (docker_mapping_loopback_host_installs_loopback_masquerade and its negative counterpart) are the closest model, so the assertion shape is already in the suite.

Acceptance criteria

• Re-applying the MASQUERADE → ACCEPT mutation makes a Docker test fail. Demonstrate this; it is the acceptance criterion.
• The rule set asserted is the full set the daemon installs for a mapping, not a substring of it
• The test is falsifiable: no early return, no soft skip, no assertion that passes on a host without the rule
• Consistent with the argv-assertion work in Table-drive the parse_port_mappings and iptables argv tests #45 (exact comparison, not contains)
• cargo test -p lab-ops --test natmap_docker --all-features still passes 34/34 on a clean run

Blocked by

None (can start immediately).

NixOS hosts need the OPENSSL_LIB_DIR and LD_LIBRARY_PATH exports from AGENTS.md to run this at all.

[FAZuH]

Landed on v0.2 as f67cf19, merged 2fbd56c. Closed by hand: a closing keyword only fires from commits reaching the default branch.

The criterion is a demonstration, so here it is

Applied at crates/natmap/src/iptables.rs:184, "MASQUERADE".into() → "ACCEPT".into():

run	loadavg	result
natmap_docker, clean	1.30 / 2.09	ok. 35 passed; 0 failed
natmap_docker, mutated	1.24 / 2.06	FAILED. 34 passed; 1 failed
natmap_docker, reverted	—	ok. 35 passed; 0 failed

Failing test: natmap_docker::docker_mapping_installs_full_rule_set

assertion \`left == right\` failed: natmap rule set for one mapping does not match:
  left:  ... "-A POSTROUTING -s 172.18.0.2/32 -d 172.18.0.2/32 ... -j ACCEPT"
  right: ... "-A POSTROUTING -s 172.18.0.2/32 -d 172.18.0.2/32 ... -j MASQUERADE"

The other three rules matched, so the failure isolates the MASQUERADE rather than the test as a whole.

The original finding no longer holds. cargo test -p lab-ops --test natmap_docker with MASQUERADE replaced by ACCEPT now fails. Before this change it reported 34 passed, 0 failed.

The test

docker_mapping_installs_full_rule_set in tests/natmap_docker.rs:769. It adds one mapping, reads iptables-save in the container, and asserts the exact sorted set of natmap-commented rules with one assert_eq!:

• the nat/NATMAP DNAT to the container port
• the filter/NATMAP FORWARD ACCEPT
• the OUTPUT DNAT
• the POSTROUTING MASQUERADE

Each rule carries --comment "natmap:portainer-remote:32771", so the comment is asserted as part of the string rather than checked separately. No contains, no early return, no skip. The grep is -- 'natmap:', which excludes the two chain jumps the daemon creates but does not own.

The criterion asked for the full set rather than a substring, and that is the substance: a substring assertion is precisely what let the MASQUERADE go unchecked.

Two notes

The count moved. natmap_docker is 35 tests, not the 34 the criterion quotes. The new test is the 35th; the criterion's intent is preserved.

The same gap still exists on the loopback hairpin rule, filed as a new issue. docker_mapping_loopback_host_installs_loopback_masquerade greps for -s 127.0.0.0/8 -d 172.18.0.2 without checking the jump target, so it stays green under this same mutation. Same class of weakness, different rule.