feat(network): enable Docker and Podman policy DNS and transparent TCP

[johntmyers]

Summary

Enables policy-gated DNS and transparent native TCP egress for Docker and Podman sandboxes using the resolved-endpoint primitives introduced by #2713. Existing proxy behavior remains unchanged when protocol is omitted; explicit protocol: tcp selects the native TCP path and fails closed on unsupported compute drivers.

This is PR 3 in the direct DNS + TCP stack and is intentionally based on #2713.

Related Issue

Part of #2712.

Stacked on #2713; review and merge that PR first.

Changes

Shared supervisor implementation

• Captures sandbox DNS and TCP inside the workload network namespace before releasing the workload.
• Answers only policy-eligible DNS names and publishes epoch-scoped synthetic IPv4 and IPv6 mappings.
• Redirects connections to synthetic addresses into the supervisor, correlates them with the DNS mapping, applies shared egress policy and process identity, pins the approved real address, and relays raw TCP.
• Preserves the existing CONNECT and forward-proxy paths for endpoints without explicit protocol: tcp.
• Fails closed for wrong ports, stale or expired mappings, direct real-IP bypass, unsupported runtimes, and uninspectable middleware requirements.
• Emits correlated OCSF events for DNS mappings and transparent TCP allow/deny decisions.
• Supports multiple length-prefixed DNS queries on one TCP connection, as used by libc for paired A and AAAA lookups.

Docker enablement

• Advertises the driver-owned policy-dns-transparent-tcp runtime capability and overwrites forged image or sandbox environment values.
• Reuses Docker's existing supervisor-owned nested network namespace, veth pair, nftables fence, and bridge DNS substrate.
• Runs the native TCP E2E scenario in the Docker lane, covering synthetic DNS, bidirectional TCP, wrong-port denial, direct real-IP denial, transparent-listener bypass denial, and OCSF decisions.

Podman enablement

• Advertises the same driver-owned runtime capability while preserving the non-forgeable driver boundary.
• Retains NET_BIND_SERVICE for the supervisor so policy DNS can bind TCP and UDP port 53; spawned workload processes still clear their capability bounding sets before exec.
• Disables Podman's implicit .dns.podman search suffix so policy evaluation uses the exact endpoint name requested by the workload.
• Configures libc to use the policy DNS TCP listener, avoiding rootless Podman's nested UDP REDIRECT return-path limitation.
• Runs the same native TCP E2E scenario in the rootless Podman lane on Ubuntu 26.04 with Podman 5.x and pasta.

Unsupported runtimes

• Kubernetes and VM drivers do not advertise the runtime capability in this PR. An explicit protocol: tcp policy therefore fails closed before workload startup on those drivers.

Documentation

• Updates the canonical policy schema and sandbox policy guide with the completed native DNS and TCP behavior.
• Documents the fail-closed DNS correlation boundary, Docker and Podman support, unsupported-runtime behavior, and the explicit-proxy compatibility path.
• Updates architecture, Docker and Podman driver documentation, and related agent skills to describe the driver/runtime contract.

Testing

• mise run pre-commit
• mise run docs
• mise run ci
• Policy DNS focused tests: 39 passed
• Podman driver tests: 145 passed
• Docker transparent TCP E2E
• Rootless Podman transparent TCP E2E
• Full Branch Checks and Branch E2E workflows

The implementation head passed the Docker, rootless Podman, VM, Kubernetes, Rust, Python, Go, and macOS lint lanes. Required checks are rerunning for the documentation update.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: d3192695290c85f5ec09fce8a2ee769f855e9aff
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: baebe64158d4bc837093dfc1b7ead924eccb1c25
Gator payload: 4
Review mode: initial
Previous reviewed SHA: none
Review budget exhausted: no
Maintainer decision required: no

I reviewed only the stage-3 author delta against PR #2713's head. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, or VM enablement deferred to stage 4.

Blocking findings:

• GATOR-d3192695-01 (Critical): A transparent TCP connection must consume a DNS mapping from the same policy generation as its authoritative process and endpoint authorization.
• GATOR-d3192695-02 (Critical): Only redirected synthetic-address traffic may bypass the terminal TCP reject; a reserved listener port must never become a general direct-egress allow rule.
• GATOR-d3192695-03 (Warning): Transparent TCP upstream dialing must remain bound to the real addresses validated and recorded by policy DNS; corporate-proxy configuration must not re-resolve the logical hostname.
• GATOR-d3192695-04 (Warning): Every accepted dynamic protocol: tcp policy must either have a ready transparent substrate on a capable runtime or be rejected explicitly without installing the candidate generation.

Carried findings:

• None

Non-blocking suggestions:

• None

Docs: Architecture and agent-skill guidance are updated; published release docs remain on the authoritative plan's separate stacked documentation branch.

Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 74f9fba16f09caa3f31b21bb3f920e3021ea5625
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 5151ae7e7bdf6418cc18d3447369ebf15e8ae8ac
Gator payload: 4
Review mode: follow_up
Previous reviewed SHA: d3192695290c85f5ec09fce8a2ee769f855e9aff
Review budget exhausted: no
Maintainer decision required: no

I reviewed the four unresolved obligations plus only the author delta since the previous review, within PR #2723's stage-3 boundary against PR #2713. The new commit adds Redis example coverage for blocked hostname, wrong-port, and direct-IP attempts; it does not change the implementation sites underlying the prior findings. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, or VM enablement deferred to stage 4.

Blocking findings:

• No new blocking findings in the follow-up delta.

Carried findings:

• GATOR-d3192695-01 (Critical): The transparent connection still needs a same-generation mapping and authoritative authorization check before connector construction.
• GATOR-d3192695-02 (Critical): The address-unscoped transparent-listener-port accept rule still bypasses the terminal direct-TCP reject for non-synthetic destinations.
• GATOR-d3192695-03 (Warning): Transparent TCP can still ask an upstream proxy to resolve the logical hostname instead of dialing only mapping-pinned addresses.
• GATOR-d3192695-04 (Warning): Transparent capability activation and rejection remain startup-only, so a later protocol: tcp policy update can install without a ready substrate or unsupported-runtime rejection.

Docs: The example-only delta improves negative-path documentation; architecture and agent-skill guidance remain present, while published release docs stay on the authoritative plan's separate stacked documentation branch.

Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 81e56497f9a6ef9a1806896d4eb0f24c829ded0c
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: fb1735d68a0b058353e2644edd2e0bfde7085043
Gator payload: 4
Review mode: follow_up
Previous reviewed SHA: 74f9fba16f09caa3f31b21bb3f920e3021ea5625
Review budget exhausted: yes — this is the third finding-bearing round; any later new-head review is critical-only
Maintainer decision required: no — this round adds no new finding or scope growth; the existing author obligations remain concrete

I reviewed the four unresolved obligations plus only the author delta since the previous review, within PR #2723's stage-3 boundary against PR #2713. The new commit narrows the Redis example's log output to relevant OCSF events; it does not change the implementation sites underlying the prior findings. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, VM, or other stage-4 enablement.

Blocking findings:

• No new blocking findings in the follow-up delta.

Carried findings:

• GATOR-d3192695-01 (Critical): The transparent connection still needs a same-generation mapping and authoritative authorization check before connector construction.
• GATOR-d3192695-02 (Critical): The address-unscoped transparent-listener-port accept rule still bypasses the terminal direct-TCP reject for non-synthetic destinations.
• GATOR-d3192695-03 (Warning): Transparent TCP can still ask an upstream proxy to resolve the logical hostname instead of dialing only mapping-pinned addresses.
• GATOR-d3192695-04 (Warning): Transparent capability activation and rejection remain startup-only, so a later protocol: tcp policy update can install without a ready substrate or unsupported-runtime rejection.

Docs: The example-only delta improves OCSF output focus; architecture and agent-skill guidance remain present, while published release docs stay on the authoritative plan's separate stacked documentation branch.

Next state: gator:in-review

[github-actions]

Label test:e2e applied for f232d7d. 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 and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: f232d7d0bcd6cb737e23dc4080b680c561cc03ae
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 7c93517daca3e85306c312ccf55aabf780f00015
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 81e56497f9a6ef9a1806896d4eb0f24c829ded0c
Review budget exhausted: yes
Maintainer decision required: no — the carried obligations are resolved, the remediation stays within stage 3, and the critical-only review found no new Critical defect

I reviewed only the latest author delta and the four carried obligations, within PR #2723's stage-3 boundary against PR #2713. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, VM, or other stage-4 enablement.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-d3192695-01 resolved: the adapter pins the authorization generation, reacquires the mapping for that exact generation, and keeps the guard through dialing and relay.
• GATOR-d3192695-02 resolved: the nftables exception now requires a mark set only on synthetic-destination redirects, so direct real-IP port-15001 traffic still reaches the terminal reject.
• GATOR-d3192695-03 resolved: transparent TCP ignores proxy hostname mode and sends only a mapping-validated IP to the corporate proxy.
• GATOR-d3192695-04 resolved: unsupported or startup-unprepared TCP policy expansion is rejected atomically while the previous policy remains active, with focused reload tests and operator diagnostics.

Docs: Architecture and Redis example guidance describe the startup substrate and atomic late-expansion rejection; agent-skill updates remain present. Published release docs remain on the authoritative plan's separate stacked documentation branch.

Tests: test:e2e is required and has been applied. The E2E Label Help workflow is determining the current-head dispatch action; pipeline monitoring begins only after the required workflow is queued.

Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 02d2e1beb056471c99def74c805f2c15025fb520
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 2ab7c805e2956e9548eee700df846816c3ed7af0
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: f232d7d0bcd6cb737e23dc4080b680c561cc03ae
Review budget exhausted: yes
Maintainer decision required: no — this latest-delta Critical has a proportionate author resolution; Podman can remain capability-gated for stage 4 or complete its stage-3 substrate contract

I reviewed only the latest author delta against the intentional PR #2713 stack base. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, VM, or other stage-4 enablement. The latest delta voluntarily enables Podman, so I checked only whether that newly advertised path is safe and operational.

Blocking findings:

• GATOR-02d2e1be-01 (Critical): Podman advertises policy DNS and transparent TCP while its container spec still drops the capability required to bind the UDP/TCP policy-DNS listeners on port 53.

Carried findings:

• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this delta does not invalidate those dispositions.

Docs: The Podman architecture and skill updates match the intended claim, but that claim cannot become active until the runtime substrate is complete. Published release docs remain on the plan's separate stacked documentation branch.

Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: c39e4324c9ae03a4c27d96252ac2f895ebf6f90b
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 1fc151be83ca981d4efb6f46939627fd00787552
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 02d2e1beb056471c99def74c805f2c15025fb520
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations are resolved, the remediation stays within stage 3, and the critical-only review found no new Critical defect

Thanks @johntmyers. I checked the latest Podman capability fix against the port-53 listener requirement: the generated container spec now retains NET_BIND_SERVICE, the capability test covers it, and the driver documentation matches the runtime contract. This resolves GATOR-02d2e1be-01.

I reviewed only the latest author delta against PR #2713's head. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, VM, or other stage-4 enablement.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 resolved: Podman now retains the capability required to bind policy DNS UDP/TCP listeners on port 53.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this delta does not invalidate those dispositions.

Docs: Architecture, driver, example, and agent-skill guidance cover the implementation contract; published release docs remain on the authoritative plan's separate stacked documentation branch.

Tests: test:e2e is applied, and current-head Branch Checks and E2E workflows are running.

Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 06abf90cdc52f2615c147342817a0f878004c54a
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 254b06036d1f5ac2c7cc6d4056409323a95fd5e7
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: c39e4324c9ae03a4c27d96252ac2f895ebf6f90b
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations remain resolved, the delta stays within stage 3, and the critical-only review found no new Critical defect

Thanks @johntmyers. I checked the latest qualified-hostname E2E change against the Docker/Podman network-alias and policy-DNS identity path. The fixture, policy endpoint, native lookup, and OCSF assertions now consistently use transparent-tcp-fixture.openshell.test, preventing runtime resolver search domains from rewriting the intended policy identity.

I reviewed only the latest author delta against PR #2713’s head. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, VM, or other stage-4 enablement.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 remains resolved.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this delta does not invalidate those dispositions.

Docs: No additional docs or skill changes are needed for this E2E-only hostname qualification; the existing stage-3 guidance remains applicable, and published release docs remain on the authoritative plan’s separate stacked documentation branch.

Tests: test:e2e is applied. Current-head Branch Checks and E2E are queued/running.

Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 39cb220e5bab58002699a6090f8d44da4173d2e0
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 8c2d64a6dfbf943a2ca4443f7660a61d6aefa32a
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 06abf90cdc52f2615c147342817a0f878004c54a
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations remain resolved, this delta does not cross the stage boundary, and the critical-only review found no new Critical defect

Thanks @johntmyers. I checked the latest Podman DNS-search fix against the exact policy-DNS name contract. The container spec now requests Podman’s documented . search list, its serialization is covered, and the driver documentation describes the behavior consistently.

I reviewed only the latest author delta against PR #2713’s head. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, Podman, VM, or other stage-4 enablement. Because this PR already voluntarily activates Podman, I checked only whether the latest Podman remediation introduced a new Critical defect.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 remains resolved.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this delta does not invalidate those dispositions.

Docs: The Podman runtime documentation now records the exact-name resolver behavior. Existing architecture, driver, example, and agent-skill guidance remain applicable; published release docs remain on the authoritative plan’s separate stacked documentation branch.

Tests: test:e2e is applied. Current-head Branch Checks, Helm Lint, and E2E workflow dispatch is being monitored.

Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 93a25073dd6e96ee2fee49d2df4bdb78d3b8cde3
Base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Merge base SHA: 17a43d8ce788eb2dd27b5a2910649864b5f72f1b
Patch ID: 6c3e9361fcfd0af165ccac983c16f5932cd13198
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 39cb220e5bab58002699a6090f8d44da4173d2e0
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations remain resolved, the delta stays within stage 3, and the critical-only review found no new Critical defect

I reviewed only the latest author delta against PR #2713’s head. I did not re-review inherited stage-1/stage-2 code or require Kubernetes sidecar, VM, or other stage-4 enablement. Because this PR already voluntarily activates Podman, I checked the new Podman TCP resolver routing and the DNS-over-TCP multi-query handling only for a newly introduced Critical defect.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 remains resolved.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this delta does not invalidate those dispositions.

Docs: Podman runtime guidance documents TCP policy-DNS resolver routing; existing architecture, driver, example, and agent-skill guidance remain applicable. Published release docs remain on the authoritative plan’s separate stacked documentation branch.

Tests: test:e2e remains applied. Current-head Branch Checks and E2E workflows are running; Helm Lint is green.

Next state: gator:watch-pipeline

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 379e6aeb921adc2e87919b215bb82933efae0500
Base SHA: 00bf8a97a457456a662d9fe73e11ad723384b6e0
Merge base SHA: 00bf8a97a457456a662d9fe73e11ad723384b6e0
Patch ID: a9c11a810f938f3c40f712263839e0be54d65457
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 93a25073dd6e96ee2fee49d2df4bdb78d3b8cde3
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations remain resolved, the rebase stays within stage 3, and the critical-only author-delta review found no new Critical defect

I compared the stage-3 author series against both the previous and current PR #2713 stack bases. The author commits are patch-equivalent; the only range-diff difference is upstream context in the VM environment function. That context change does not alter stage-3 capability gating or invalidate any prior finding disposition.

I did not review the cumulative main-branch diff, re-review inherited stage-1/stage-2 code, or require Kubernetes sidecar, VM, or other stage-4 enablement. Podman remains in scope only because this PR voluntarily enables it.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 remains resolved.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; the rebase does not invalidate those dispositions.

Docs: Existing architecture, Docker/Podman driver, example, and agent-skill guidance cover the stage-3 runtime contract. Published release docs remain on the authoritative plan's separate stacked documentation branch.

Tests: test:e2e remains applied. Current-head Branch Checks and E2E are dispatched; E2E is queued/running. Branch Checks currently has a TypeScript SDK job failure whose full log is unavailable until the workflow completes, so pipeline diagnosis remains pending.

Next state: gator:watch-pipeline

[github-actions]

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

[johntmyers]

gator-agent

PR Review Status

Validation: Project-valid stage 3 of issue #2712, intentionally stacked on stage-2 PR #2713.
Head SHA: 60de686118ca54518c4c2a7e4c29d95890eb2533
Base SHA: 170de834d0c521c7eca3fea9aa4ec2bcca918d3f
Merge base SHA: 170de834d0c521c7eca3fea9aa4ec2bcca918d3f
Patch ID: d36b86a3c3390aab60894068cccd62f8c919ad3b
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 379e6aeb921adc2e87919b215bb82933efae0500
Review budget exhausted: yes
Maintainer decision required: no — all carried obligations remain resolved, the documentation synchronization stays within stage 3, and the critical-only author-delta review found no new Critical defect

I reviewed only the latest author delta against PR #2713's current stack base. The delta synchronizes the policy schema and sandbox policy guide with the implemented native DNS and transparent TCP contract; it does not change runtime code or invalidate prior finding resolutions.

I did not review the cumulative main-branch diff, re-review inherited stage-1/stage-2 code, or require Kubernetes sidecar, Podman, VM, or other stage-4 enablement.

Blocking findings:

• No blocking findings remain.

Carried findings:

• GATOR-02d2e1be-01 remains resolved.
• GATOR-d3192695-01 through GATOR-d3192695-04 remain resolved; this documentation delta does not invalidate those dispositions.

Docs: The canonical policy schema and sandbox policy guide now describe explicit protocol: tcp, synthetic DNS correlation, pinned dialing, Docker/Podman runtime support, fail-closed unsupported runtimes, and the explicit-proxy compatibility path. Published release docs remain governed by the authoritative plan's separate stacked documentation branch.

Tests: test:e2e remains applied. Current-head Branch Checks are running and E2E is queued.

Next state: gator:watch-pipeline