[FrostGod]

Summary

A transparent TCP connection allowed for an IPv4 destination was denied when a dual-stack client used its ::ffff: form. Canonicalize the destination before routing, policy DNS lookup, policy evaluation, and denial reporting, while preserving native IPv6 scope and flow information.

Related Issue

Closes #5093

Changes

• Normalize the staged destination IP with to_canonical().
• Add five regression tests covering allowed endpoints, DNS hostname recovery and pinned addresses, denial hosts, metadata blocking, and native IPv6 preservation.
• Exercise the reserved relay with both IPv4 and IPv4-mapped IPv6 destinations.
• Extend the existing Docker/Podman TCP E2E probe with an actual IPv4-mapped AF_INET6 connection, and document equivalent IPv4 policy matching.

Release Notes

Transparent TCP connections now evaluate IPv4-mapped IPv6 destinations as IPv4. If an endpoint rule uses host: "::ffff:203.0.113.7", change it to host: "203.0.113.7".

Testing

• Scoped formatting, Clippy, and documentation navigation checks pass.
• Unit tests added: 5 new regressions and 23 existing staged-open/reserved-routing checks pass, including both address forms for the reserved relay.
• Existing E2E test extended; local execution did not reach the tests.

Commands passed:

• cargo test --offline -p openshell-supervisor-network --lib proxy::tests::ipv4_mapped
• cargo test --offline -p openshell-supervisor-network --lib -- proxy::tests::ipv4_mapped staged_ reserved_ metadata_staging --test-threads=1
• cargo clippy --offline -p openshell-supervisor-network --lib --tests -- -D warnings
• cargo fmt --check -p openshell-supervisor-network -p openshell-isolation-interface
• rustfmt --check --edition 2024 e2e/rust/tests/transparent_tcp.rs
• mise run --skip-tools docs:nav

The focused Docker E2E run was canceled after stalling on base-image metadata from ghcr.io/astral-sh/uv and nvcr.io/nvidia/base/ubuntu, before sandbox tests started. The repository-wide commit hook also failed in unrelated local Python tooling; the commit uses the completed scoped checks above.

Checklist

• Follows Conventional Commits.
• Commit signed off (DCO).
• Relevant network-policy documentation updated.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5101.docs.buildwithfern.com/openshell

[EmilienM]

Another iteration needed: 1 major, 3 minor (inline, 1 below)

The core fix is right and the new unit tests pass locally. The major is about verification, not the code: the new e2e probe has never executed, and the V6-family relay establishment it covers only runs on that path.

Outside the diff:

• Minor: crates/openshell-isolation-interface/src/contract.rs:585, PendingTcpOpen.destination is documented as the original destination the backend captured, but preauthorize_transparent_open now rewrites it in place; a one-line doc note (or canonicalizing at capture) keeps the contract accurate.

How this was reviewed

• Commit dedaee7a, round 1
• Deep review, because the change routes supervisor network policy (crates/openshell-supervisor-network/src/proxy.rs), sandbox socket mediation (crates/openshell-sandbox/src/network_broker.rs), and the transparent TCP e2e (e2e/rust/tests/transparent_tcp.rs)
• Passes: architecture, performance, security, scalability, rust, then correctness
• Independent skeptics checked each candidate finding (1); 1 of 2 held up
• Repo rules read from origin/main: AGENTS.md, CLAUDE.md, CONTRIBUTING.md
• Not covered: the Docker/Podman E2E suite (CI shows test:e2e not applied; see the major finding)

[FrostGod]

/ok to test 48ac0ec

[github-actions]

Label test:e2e applied for 48ac0ec. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[pimlock]

/ok to test d2a2283

[FrostGod]

/ok to test bd0ec39

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. policy — No explicit risk acceptance found

Transparent TCP destinations previously retained their mapped IPv6 identity but now become IPv4, preventing mapped host and allowed_ips entries from matching.

• Impact: Existing policies with protocol omitted and entries such as host: "::ffff:203.0.113.7" or hostless allowed_ips: ["::ffff:203.0.113.7/128"] now reject formerly permitted connections.
• Action: Preserve mapped host and allowed_ips matching in v0.1.8; defer mandatory conversion to a minor release with migration guidance for both fields.
• PR: fix(network): normalize IPv4-mapped transparent TCP destinations #5101

Review details

• Execution: complete
• Candidate: PR #5101 (884052bb8c9a8f2a132f7aae7e2fd42fc217debd)
• Baseline: f56b12e0c08cc1fc213f1c9adab5b23e31796c6d (f56b12e0c08cc1fc213f1c9adab5b23e31796c6d)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run