[LXC] Make firewall chain identity collision-free

[Darren Hoehna (dhoehna)]

Scope contract — [LXC] Make firewall chain identity collision-free

Veto line: if the one-sentence scope below is wrong, say so and nothing else
needs reading.

Scope: make NetworkIptablesManager's chain name a total, ASCII-safe,
length-bounded, collision-resistant function of the container name — and
nothing else.

Problem

Observed, in main at src/backends/lxc/common/src/network_iptables.rs:185-199:

let sanitized: String = container_name
    .chars()
    .filter(|c| c.is_alphanumeric() || *c == '-' || *c == '_')
    .take(20)
    .collect();
chain_name: format!("MXC-{}", sanitized)

Three defects, each independently sufficient to make two distinct containers
share one firewall chain:

1. Filtering is lossy and collapses distinct names. a.b and ab both
   produce MXC-ab.
2. Truncation is lossy. Any two names agreeing on their first 20
   sanitized characters produce the same chain.
3. char::is_alphanumeric is Unicode-aware, and take(20) counts chars,
   not bytes. 容器 survives the filter, so 20 retained chars can be up to
   80 bytes.

Expected: distinct container names get distinct chains, and every chain name is
accepted by iptables.

Why it matters: a shared chain means one container's teardown flushes and
deletes another's chain, leaving the second running with no egress filtering —
fail-open. This is the same hazard class as the merged PR 724, one layer up.

Evidence

• The 28-character ceiling was measured, not inferred. iptables -N on this
  host accepts 28 and rejects 29 with "chain name … too long (must be under 29
  chars)". XT_EXTENSION_MAXNAMELEN is 29 including the NUL.
• Six of the eleven still-valid unresolved review threads on the abandoned
  PR 633 are this one defect: threads Change the WXC projects to statically link the CRT. #11, Handle container creation and policy more cleanly #15, Bump minimatch from 9.0.5 to 9.0.8 in /sdk #16, Bump minimatch from 10.2.2 to 10.2.4 in /sdk #19, #24, and Add copyright header #35.

Design

MXC-<slug>-<hash>      4 + 7 + 1 + 16 = 28 bytes, the exact ceiling
MXC-<hash>             when the name yields no ASCII-safe slug characters

• slug — up to 7 characters of the original name, keeping only
  [A-Za-z0-9_-]. Present purely so an operator reading iptables -S can
  guess which container a chain belongs to. It carries no identity.
• hash — the first 10 bytes of SHA-256(container_name), base32-lowercase,
  16 characters, 80 bits. Computed over the original bytes, never the
  slug, so neither filtering nor truncation can cause a collision.

Identity lives entirely in the hash, so two names collide only on a hash
collision.

Threat model — stated, because it bounds the claim

This fixes accidental collision. It does not make chain names resistant to
an adversary who chooses container names: 80 bits gives a ~2^40 birthday bound,
and the 28-character ceiling means even spending the whole budget on hash
reaches only ~120 bits. Adversarial ownership needs a persisted, verified
ownership record — that is unresolved thread #19, and it is out of scope
here and called out as deferred rather than silently assumed away.

In scope

• src/backends/lxc/common/src/network_iptables.rs — chain-name construction,
  plus a public accessor so the behavior is testable from outside the module.
• src/backends/lxc/common/Cargo.toml and src/Cargo.toml — promote sha2 to
  a direct dependency.
• A new black-box spec test file owned by an uncontaminated sub-agent.
• Added after review: the four tests/scripts/run_lxc_network_*.sh scripts
  that hardcoded the old chain name. This is a scope increase over the frozen
  contract, taken because those scripts are broken by this change — see
  below. It is recorded here rather than made quietly.

Out of scope — deliberately

• Persisted/verified chain ownership (thread Bump minimatch from 10.2.2 to 10.2.4 in /sdk #19).
• INPUT-chain coverage for host-local traffic (thread Grant AppContainer access to NUL device before process creation #26).
• Fail-closed handling of unresolved blocked hosts (thread Bump minimatch from 3.1.2 to 3.1.5 in /cli #17).
• Teardown swallowing cleanup failures (thread Bump flatted from 3.3.3 to 3.4.1 in /cli #31).
• Cross-process lifecycle locking (thread Update to windows-rs 0.62, add arch-specific builds, and bundle wxc-exec in SDK #33).
• Everything state-aware: state_aware.rs, the Node SDK, PTY, signal cleanup.

Gates that broke

This section was wrong when the contract was frozen, and is corrected here
rather than quietly fixed. It predicted two failures. Seven tests failed.

Correctly predicted — these encode the defective contract, and updating them is
the point of the change:

• chain_name_sanitization — asserted MXC-my-container_123
• chain_name_truncation — asserted len() <= 24

Missed — the contract claimed the MXC-fresh / MXC-survivor teardown fixtures
"construct their expectations from the manager, so they follow automatically."
They do not. They hardcode chain-name literals in their flush/delete
expectations, so all five broke:

• teardown_flushes_and_deletes_the_chain
• teardown_is_idempotent_when_the_chain_is_absent
• teardown_reports_failure_when_delete_fails
• adopted_container_teardown_removes_only_its_own_chain
• chain_names_have_mxc_prefix_and_total_length_cap_of_twenty_four

Fixed with one flush_and_delete helper that derives the expected commands
from the manager, collapsing six duplicated literal pairs into one call site
each — rather than six separate hand-edits, which would have been churn for no
structural gain.

Dependency note

sha2 is already in Cargo.lock transitively (0.10.9 and 0.11.0), as are
digest, hex, and blake3. Promoting sha2 = "0.10" to a direct dependency
adds zero new packages to the supply chain.

Which invariant wins

When these conflict, in this order:

1. Working runtime — every emitted name must be accepted by iptables. A
   name the kernel rejects is worse than a collision.
2. Green build — clippy at CI strictness, no warnings.
3. Minimal review scope — no file outside the list above.
4. Readability of the slug — sacrificed first. It is a convenience.

A defect this PR introduced, found while addressing review

Changing the derivation broke four shell test scripts that hardcoded the old
chain name. None of it surfaced in CI, because all four skip (exit 77)
without root and LXC, so only a real LXC host would have caught it.

Script	Old literal	Failure mode
run_lxc_network_cidr_boundary_test.sh	MXC-CLI-LXC-Network-CIDR	fails loudly
run_lxc_network_dualstack_test.sh	MXC-CLI-LXC-Network-Dual	fails loudly
run_lxc_network_ipv6_cidr_test.sh	MXC-CLI-LXC-Network-IPv6	fails loudly
run_lxc_network_invalid_cidr_test.sh	MXC-CLI-LXC-Network-Inva	passes vacuously

The last one is the dangerous one. Its only chain assertion was a cleanup
check, iptables -S "MXC-CLI-LXC-Network-Inva", against a chain the new
derivation can never produce — so it would have gone on passing while asserting
nothing at all.

The fix does not reimplement sha256 and base32 in bash, which would be a
third implementation to keep in sync. Instead:

• The chain name is read back from the run's own --debug output, then
  asserted for shape (MXC-<slug>-<hash>) and for the 28-character ceiling, so
  a malformed name still fails.
• Cleanup is checked by diffing MXC--prefixed chains against a snapshot taken
  before the run, so a chain left behind by an earlier failed run is not
  blamed on this one.

An independent review of that fix then caught a hole in it, recorded here
rather than quietly patched. The sweep consumed the chain listing through a
process substitution, whose exit status is not the loop's, so a failed
enumeration read as zero chains and passed — the same vacuous-pass class this
section exists to remove, reintroduced by the fix for it. A control run
confirms it: the first version reported a clean result against a listing
command that does not exist. The listing is now captured first, and failing
to enumerate fails the test.

Verification — actual results

• cargo test -p lxc_common --lib — 115 passed (baseline parity with
  main).
• cargo test -p lxc_common --test chain_name_spec — 28 passed. Written
  by sub-agents that had not read the implementation, per the
  blackbox-unit-tests skill; I have read the file, so I could not author
  them.
• Four of those 28 came from a late corpus audit, and two of them close real
  holes. The suite was first written against the documented contract without
  consulting the testing corpus that governs how these suites are derived.
  Re-deriving it against that corpus added: _ retention in the slug, slug
  case-preservation (only the hash is lowercased), the {1,7} lower bound, and
  the full composed shape ^MXC-([A-Za-z0-9_-]{1,7}-)?[a-z2-7]{16}$ that the
  four bash scripts grep for — the suite had checked fragments of that shape
  but never the composed contract those scripts depend on. Mutants that drop
  _ from the slug alphabet or lowercase the slug are each killed by exactly
  one test, and in both cases it is one of the four added here, so both would
  have survived the previous 24-test suite.
• cargo clippy -p lxc_common --all-targets --all-features -- -D warnings —
  clean. cargo fmt --check — clean.
• Mutation testing: 17 mutations, 15 caught. Rounds of survivors were each
  investigated rather than assumed benign, and four turned out to be real holes
  that are now closed:
  • base32_narrow_mask — silently halved entropy 80 → 64 bits; only 16 of the
    32 alphabet characters could ever appear.
  • base32_shift_wrong_way — collapsed entropy 80 → 30 bits, with 5 of 16
    positions entirely constant. The original injectivity test passed only by
    luck (~19% collision probability at 20k samples). Missed because alphabet
    coverage was asserted pooled across positions, and pooling hides a
    constant position.
  • hash_lowercased_name — container-A and container-a share the 7-char
    slug, so lowercasing before hashing gave them the same chain: exactly the
    fail-open collision this change exists to prevent.
  • hash_reversed_name — an earlier revision of this description claimed
    this mutant was uncatchable in principle. That was wrong, and the claim is
    withdrawn. The stated reason was that catching it needs a pinned literal
    digest, which the black-box rule forbids. The rule forbids me writing
    such a test, having read the implementation — not the test existing. An
    uncontaminated sub-agent wrote three known-answer tests, and a mutation run
    confirms the catch: seeding hash_reversed_name now fails three tests
    where it previously survived. The pinned digests agree three ways — an
    independent Python oracle, a second oracle written by an agent barred from
    reading the implementation, and the shipped Rust.
• The 2 surviving mutants are provably equivalent, not gaps:
  • base32_off_by_one_bits (>=5 → >5) — byte-identical across 3,000
    inputs; bit boundaries are data-independent at a fixed 10-byte width, so
    identity on one input implies it on all.
  • base32_drop_tail_emit — 80 mod 5 = 0, so pending_bits is always 0 after
    the loop and the tail branch is dead at this width.
• Runtime invariant checked against real iptables. Seven generated name
  shapes, including the 28-character maximum MXC-abcdefg-qrstuvwxyz234567,
  were created and deleted with both iptables -N and ip6tables -N in WSL.
  All accepted, zero residue.
• The shell helpers were extracted from the shipped script and exercised in
  WSL as root against real iptables — 16 of 16. That includes rejecting
  the old MXC-CLI-LXC-Network-CIDR format, detecting a deliberately leaked
  chain, and correctly not blaming a pre-existing one. Two of those 16 are a
  control for the silent-pass defect described above: run against a nonexistent
  enumeration command, the old process-substitution form prints
  PASSED-SILENTLY and the fixed form refuses. The scripts themselves still
  cannot run here; they need root and LXC.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Makes LXC/Bubblewrap firewall chain names ASCII-safe, length-bounded, and collision-resistant.

Changes:

• Adds SHA-256/Base32 chain identity with readable slugs.
• Exposes chain names for validation.
• Adds extensive black-box tests and updates dependencies.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Cargo.toml	Adds workspace SHA-256 dependency.
src/Cargo.lock	Records direct LXC dependency.
src/backends/lxc/common/Cargo.toml	Enables SHA-256 for LXC common.
src/backends/lxc/common/src/network_iptables.rs	Implements hashed chain naming and updates tests.
src/backends/lxc/common/tests/chain_name_spec.rs	Adds chain-name specification tests.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Darren Hoehna (dhoehna)]

Added, and you were right that this was a real gap rather than a cosmetic one.

The PR description had claimed the surviving reversed-input mutation was uncatchable in principle, on the grounds that pinning a literal digest is forbidden by the black-box rule. That was wrong and I have withdrawn it. The rule forbids me writing such a test, having read the implementation -- not the test existing. A sub-agent that had not read network_iptables.rs wrote three known-answer tests, and re-running the mutation confirms the catch: seeding hash_reversed_name now fails three tests where it previously survived. The suite goes 21 -> 24.

The pinned digests agree three ways -- an independent Python oracle, a second oracle written by the agent barred from reading the implementation, and the shipped Rust -- and a reviewer since reproduced all 14 literals independently in Python.

Writing them also surfaced a defect this PR introduces. Four tests/scripts/run_lxc_network_*.sh scripts hardcode the pre-hash chain name. Three would fail loudly on an LXC host; run_lxc_network_invalid_cidr_test.sh would have gone on passing while asserting nothing, because its only chain assertion was a cleanup check against a chain the new derivation can never produce. None of it surfaces in CI, since all four skip without root and LXC. All four now derive the name from the run's own debug output and diff MXC-prefixed chains against a pre-run snapshot. Fixed in 52a331c and 2d9875c.

[Darren Hoehna (dhoehna)]

Fixed, and then fixed again -- the second correction is the one that matters, so it is worth stating what was wrong with the first.

You were right about the arithmetic: 16 base32 characters carry 80 bits where hex carries 64, a 16-bit difference, not four. My first fix said that, but justified the choice by claiming 20 hex characters would not fit under the 28-byte ceiling. That is false. MXC- plus 20 hex is 24 characters and fits comfortably. An independent reviewer caught it before merge.

The real constraint is the slug. MXC-, the slug, and the slug's separator take 12 of the 28 bytes, leaving exactly 16 for the hash, so hex could carry 80 bits only by giving up the slug entirely. The comment now says that. Fixed in 2d9875c.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/backends/lxc/common/src/network_iptables.rs:240

• This new collision model leaves several comments in this file stale: lines 60–61, 1155–1156, and 1251–1253 still say names truncate at 20 characters and can collide because of sanitization/truncation. Update those explanations to the new hash-collision threat model so the ownership safeguards are documented accurately.

/// The hash is taken over the *original* container name, so container names
/// that differ only in characters the slug drops, or only past the slug's
/// length, still receive different chains. Two names collide only if their
/// SHA-256 digests collide in the leading 80 bits.

tests/scripts/run_lxc_network_ipv6_cidr_test.sh:69

• The explicit “In scope” list names only network_iptables.rs, the two Cargo manifests, and the new spec test, and the PR says no file outside that list changes. This file plus the other three LXC network scripts are outside that contract. Please either include these script updates in the declared scope and verification or remove them; as written, the frozen scope is inaccurate.

# List the MXC-owned chains a tool currently holds. The chain name is derived
# from a digest of the container name, so a hard-coded literal rots the moment
# that derivation changes, and a cleanup assertion naming a chain that can no
# longer exist passes while testing nothing. Matching the MXC- prefix stays
# correct across naming changes.

src/backends/lxc/common/src/network_iptables.rs:173

• “Unique” overstates this 80-bit truncated hash: the function is collision-resistant, not injective, and the new threat-model documentation explicitly allows hash collisions. Describe the field as collision-resistant so the API documentation matches the implemented guarantee.

This issue also appears on line 237 of the same file.

    /// Chain name unique to this container, as built by [`chain_name_for`].
    chain_name: String,

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.