Isolate the enclave delegation control listener from executor networks

[lpcox]

Summary

Make mcpg's dynamic-enclave delegation control listener unreachable from the primary agent and single-use enclave executor networks.

The controller bootstrap added by #59045 / PR #59046 publishes the control port on host loopback and documents that this prevents the enclave executor network from routing to it. That claim is incorrect when mcpg listens on 0.0.0.0 inside its container: Docker's -p 127.0.0.1:<host>:<container> limits access through the host-published port, but a peer sharing a Docker network with mcpg can address the container IP and control port directly without traversing host loopback.

The control API still requires the AWF-only 256-bit capability, so this is not an unauthenticated authorization bypass. It is a missing defense-in-depth/topology guarantee and conflicts with github/gh-aw-firewall#8195, which requires the dynamic executor to stay off the control listener.

Scope

• Separate the delegation control transport from the mcpg data-plane transport at the container/network boundary.
• Ensure the primary agent, enclave executor, model sidecar, and general MCP data-plane peers have no route to the control listener.
• Preserve host-side AWF access to the control API and keep the existing capability authentication on every request.
• Do not rely solely on -p 127.0.0.1:... publication scope when the same in-container listener is reachable through a shared bridge network.
• Correct the inaccurate reachability comment in pkg/workflow/enclaves.go and related documentation/tests.
• Add a topology test that attempts a TCP connection to the control port from the primary and enclave executor network namespaces and proves both fail, while an authenticated AWF host request succeeds.
• Preserve the executor-facing mcpg data plane and its invocation-scoped bearer behavior.
• Fail closed if the isolated control transport cannot be established; do not fall back to a shared listener reachable by executors.

Possible implementations

• Run the control plane in a separate sidecar/network namespace reachable only through an AWF-owned Unix socket or host-private network.
• Bind the control listener to an interface/address not attached to the executor-visible bridge while keeping the data listener on the existing mcpg container network.
• Use a host-owned authenticated relay with no executor-visible listener.

The implementation must demonstrate network separation rather than assuming host publication rules apply to container-to-container traffic.

Acceptance criteria

• From the enclave executor network namespace, connecting directly to mcpg's control port fails at the network layer.
• From the primary agent network namespace, connecting to the control port also fails.
• AWF can still perform authenticated create/status/reconcile/revoke operations.
• Possession of an executor bearer does not provide a route or credential for the control API.
• The control capability remains excluded from all agent environments, mounts, logs, and summaries.
• Automated tests verify both authorization and network isolation.

Dependencies and consumers

• Controller bootstrap: Wire dynamic enclave delegation controller into the workflow runtime #59045 / PR Wire dynamic enclave delegation controller into the workflow runtime #59046.
• AWF runtime implementation: github/gh-aw-firewall#8195 / PR github/gh-aw-firewall#8276.
• Separate TTL units blocker: Encode dynamic enclave identity TTL in nanoseconds #59258.
• mcpg delegation contract: github/gh-aw-mcpg#12604, released in v0.4.17.

[lpcox]

Some findings from implementing the AWF side (github/gh-aw-firewall#8276) that may narrow the implementation choice.

The exposure is specific to network-isolation/bridge mode. generateMCPGatewaySetup sets controlListenHost := "127.0.0.1" and only widens it to 0.0.0.0 when isAWFNetworkIsolationEnabled(workflowData). In --network host mode the listener is already loopback-bound and the container shares the host namespace, so there is no container-to-container exposure. Only the bridge path (mcp_setup_gateway.go ~line 449) is affected.

mcpg is multi-homed only after startup, which suggests a cheaper fix than a sidecar or Unix socket. gh-aw starts the gateway with --network bridge, so at start it has exactly one interface, on the default bridge, and that is what -p 127.0.0.1:<port>:<port> publishes from. AWF then attaches it to two more networks afterwards, at runtime:

• awf-net via connectTopologyContainers (so the primary agent can reach /mcp/awf-enclave);
• awf-enclave-agent at 172.31.0.40 via docker network connect --ip ... --alias ... in connectEnclaveGithubGateway (so the enclave can reach /mcp/github).

Because those attachments happen after the process is listening, binding the control listener to the container's default-bridge address — rather than 0.0.0.0 — would leave it unreachable from both later-attached networks while keeping the host publication intact. The data-plane listener stays on 0.0.0.0 and is unaffected. That achieves the "network separation rather than assuming host publication rules apply" requirement without a second container, a Unix-socket contract change in mcpg, or a host relay.

The catch is that the container's bridge IP is assigned by Docker at start, so MCP_GATEWAY_DELEGATION_CONTROL_LISTEN cannot carry a literal address the way it does today. It would need either a resolved-at-entrypoint value or an mcpg-side "bind to my primary interface" mode. I have not prototyped this, and whether Docker's published-port DNAT survives the narrower bind should be verified before committing to it — that is the one assumption I would not take on trust.

On the acceptance criteria, the negative tests are worth writing at the network layer rather than the application layer: a TCP connect from the executor namespace should fail to establish, not merely return 403 delegation_access_denied. AWF now asserts steady-state membership of awf-enclave-agent is exactly {enclave-agent-api-proxy, mcpg} (src/enclave/github-gateway.ts), so a test can rely on that topology being fixed.

For completeness: the inaccurate comment this issue cites (enclaves.go ~line 56) was mirrored into AWF's own docs, and github/gh-aw-firewall#8276 corrected it there — AWF's documentation now states that the control plane is protected by capability authentication rather than by unreachability, so the two repositories will not disagree while this is open.

[lpcox]

Decision: accept capability authentication as the control here

Maintainer call — we are not adding a second, topological control for the delegation control listener. The 256-bit capability is the enforced control, and the remaining work is to stop documenting a routing guarantee that doesn't hold.

Doc/comment correction is up in #59310.

Why this is defensible

I read the implementation end to end before endorsing the simplification, since the capability becomes the sole control:

Property	Location
256-bit CSPRNG secret (openssl rand -hex 32), ::add-mask::-ed	mcp_setup_gateway.go:315-316
Excluded from the agent env via --exclude-env	awf_env.go:108 (capability), :174 (endpoint)
Exclusion condition is broader than the setting condition	capability excluded on enclavesEnabled, set only on enclaveDynamicRepositoryPolicyEnabled
Stored only as a SHA-256 digest — a memory dump can't recover it	mcpg internal/delegation/capability.go
subtle.ConstantTimeCompare over fixed-size digests — no length or content timing leak	same
32-byte floor rejects empty/trivial values	minControlCapabilityBytes
Verified before any control routing, plus a POST requirement	mcpg internal/proxy/delegation.go:49
Separate handler from the executor data plane	ControlHandler() vs Handler()

That last row matters most for this issue's threat model: a valid executor bearer cannot reach control operations even with a route, because control is a different handler on a different listener that only accepts the capability.

Coverage for the properties we now depend on already exists at enclaves_test.go:671-680 (minting, masking, GITHUB_ENV handoff, and exclusion of both capability and control endpoint). I verified these rather than adding duplicates.

Residual risk is capability leakage, not brute force. Network isolation would only have added depth against leakage — real defense-in-depth value, but not worth the complexity of a separate namespace/socket/relay given the above.

What stays true from the original report

The reachability claim was wrong and is worth correcting regardless of this decision, because a comment asserting "cannot route to it" invites a future change to lean on a guarantee that isn't there. AWF asserts mcpg is a member of the enclave-agent network at 172.31.0.40 on every dynamic run — that co-attachment is how the enclave reaches the GitHub data plane, and it necessarily also exposes control at data-port + 10.

Effect on github/gh-aw-firewall#8195

#8195's criterion "the dynamic executor has no route to the control listener" is intentionally waived, superseded by "the dynamic executor holds no credential for the control listener," which is implemented and tested. AWF's docs/enclaves-architecture.md already describes the model this way (corrected in gh-aw-firewall PR #8276, commit 4783af78).

Leaving this open until #59310 merges, then closing as resolved-by-documentation rather than not-planned.

[lpcox]

Closing as not planned — deliberately, not as completed.

The documentation scope is done (#59310, merged as e42a43e9), but the issue's primary scope — network-layer isolation of the control listener — was consciously waived in favour of relying on the 256-bit capability alone. Marking that "completed" would leave a false record for anyone later asking "did we isolate the control listener?" The answer is no, by choice.

Against the acceptance criteria

Criterion	Outcome
Executor namespace cannot reach the control port at the network layer	Waived
Primary-agent namespace cannot reach it	Waived
AWF can still perform authenticated create/status/reconcile/revoke	Met
Executor bearer grants no route or credential	Credential: met. Route: waived
Capability excluded from all agent envs, mounts, logs, summaries	Met — awf_env.go:108, :174, tested at enclaves_test.go:677-680
Tests verify authorization and network isolation	Authorization: met. Isolation: N/A

Three of six waived. That's the honest tally.

What actually shipped

Both inaccurate comments are corrected on main:

• mcp_setup_gateway.go — the -p publish comment asserting the agent/executor networks "cannot route to it"
• enclaves.go — the port-offset comment asserting the control port is published "so neither the primary agent nor the enclave executor network can route to it"

Worth recording: I found and fixed only the first. My search pattern (cannot route|can not route|no route to) missed the second, which phrases the same false claim as "neither … nor … can route to it". A Copilot agent caught it and pushed 1e5ec4b0 onto the branch before merge. The issue named pkg/workflow/enclaves.go explicitly, so that was my miss, and it's exactly the sort of near-duplicate claim that motivated filing this in the first place.

Why the simplification holds

Capability auth is the enforced control, and it's implemented tightly: 256-bit CSPRNG secret, ::add-mask::-ed, excluded from every agent environment (on a broader condition than it's set), stored only as a SHA-256 digest, compared with subtle.ConstantTimeCompare, 32-byte floor, verified before any control routing with a POST requirement, on a handler separate from the executor-facing data plane. A valid executor bearer cannot reach control operations even with a route.

Residual risk is capability leakage, not brute force — which is precisely the depth topological isolation would have added. If that trade is ever revisited (a leak path, a third-party mcpg peer, or a stricter compliance bar), reopen this rather than filing fresh: the analysis above is the starting point, and the three candidate designs in the original description still stand.

github/gh-aw-firewall#8195's "no route to the control listener" criterion is superseded by "holds no credential for the control listener," which is implemented and tested. AWF's docs/enclaves-architecture.md already documents the model this way.