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, publishes epoch-scoped synthetic IPv4 mappings, and returns NOERROR/NODATA for AAAA until a runtime proves usable IPv6 egress.
• 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, resolver/publication failures, pool high-water state, and transparent TCP allow/deny decisions.
• Redirects workload DNS port 53 to an unprivileged supervisor listener on port 15053.
• Handles UDP DNS queries concurrently with a fixed bound and supports multiple length-prefixed queries on one TCP connection.
• Expands both synthetic family pools to 512 identities with a shared 1,024-allocation lifetime cap while preserving no-reassignment within an epoch.

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.
• Uses the unprivileged policy-DNS listener without granting NET_BIND_SERVICE.
• Preserves Podman's existing search-domain and resolver-option behavior for sandboxes that do not use native TCP.
• Supports UDP DNS through the nested REDIRECT path without forcing libc use-vc, including Alpine/musl coverage.
• 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
• Supervisor-network tests: 1,192 passed, 2 ignored; integrations passed
• Podman driver tests: 170 passed
• Sandbox library tests: 113 passed; binary and integration tests passed
• New Alpine/musl Podman E2E target compiles
• Existing Docker and rootless Podman transparent TCP E2E scenarios cover allowed TCP, wrong-port denial, direct-real-IP denial, listener-bypass denial, and OCSF decisions
• Required Branch Checks and Branch E2E workflows are rerunning for the current head

Local runtime E2E was not rerun for the review fixes because Podman is not installed and the local Docker daemon is stopped. The pushed stack exercises those paths in CI.

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, originally and intentionally stacked on stage-2 PR #2713. PR #2713 is now merged, and this review remains limited to the stage-3 author series rather than the cumulative main-branch diff.
Head SHA: bbffdb4d597da43811adcc436123a25d5f7ed241
Base SHA: 2c0adf4868a773db7d06d7d6be2e218fd1c46478
Merge base SHA: 2c0adf4868a773db7d06d7d6be2e218fd1c46478
Patch ID: 7e7edf71ecab825d28d8835a0c4328b8d21147fb
Gator payload: 4
Review mode: critical_only
Previous reviewed SHA: 2e919c0e5d69d138d09d18f7a84e8063178398d0
Review budget exhausted: yes
Maintainer decision required: no — all durable findings remain resolved, the rebased author series is range-diff matched, and the critical-only review found no newly introduced Critical defect

I compared the complete 32-commit stage-3 author series before and after the post-merge rebase. Every commit is matched. The only non-equals range-diff entry preserves the same Podman stage-3 changes while reconciling the inherited Extension-driver documentation row from current main. That upstream context does not materially break the stage-1 or stage-2 contract.

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

Blocking findings:

• No blocking findings remain.

Carried findings:

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

Docs: Canonical policy, sandbox, architecture, Docker/Podman, example, and agent-skill guidance cover the implemented stage-3 contract. The final stacked release-documentation branch remains governed by the authoritative series plan.

Tests: test:e2e remains applied. Current-head Branch Checks and Branch E2E are queued/running; DCO, docs preview, Helm Lint, GPU gate publication, and completed required-gate publication are green.

Next state: gator:watch-pipeline

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Head SHA: bbffdb4d597da43811adcc436123a25d5f7ed241
Gator payload: 4

Final status: the PR merged from gator:watch-pipeline after the stage-3 author delta had no remaining blocking findings and test:e2e was applied.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.