fix(security): prevent PATH hijack of supervisor helpers

[drew]

Summary

Hardens Docker sandbox supervisor startup against user-controlled PATH overrides and routes local Docker sandbox callbacks over a managed Docker bridge network instead of host-based routing. Docker now reasserts a driver-owned PATH after merging template/spec env, resolves Linux namespace helpers only from fixed absolute system paths, and advertises host.openshell.internal:<gateway-port> inside Docker containers.

The Docker driver informs the gateway when native Linux Docker needs an extra bridge-gateway listener on the normal gateway port. Docker Desktop is different: its bridge gateway IP belongs to Docker Desktop's VM, not the macOS/Windows host, so Docker sandboxes use Docker's host-gateway alias for host.openshell.internal and do not request an extra listener. The gateway listener also now defaults to 127.0.0.1; container deployments pass --bind-address 0.0.0.0 explicitly.

Related Issue

Fixes #1113
Linear: https://linear.app/nvidia/issue/OSGH-151/bug-path-override-can-hijack-privileged-ip-and-nsenter-helpers

Changes

• Keep Docker supervisor PATH driver-owned after user environment merge.
• Resolve privileged ip and nsenter helpers from fixed absolute path allowlists instead of process PATH.
• Add a managed Docker bridge network for local Docker sandboxes, configurable with --docker-network-name / OPENSHELL_DOCKER_NETWORK_NAME.
• Have the Docker driver report the Docker bridge gateway IP as an extra gateway listener address on native Linux Docker.
• Use Docker Desktop's host-gateway mapping for host.openshell.internal instead of overriding it to the VM bridge gateway IP.
• Point Docker sandbox OPENSHELL_ENDPOINT at host.openshell.internal:<gateway-port>.
• Add --bind-address / OPENSHELL_BIND_ADDRESS, defaulting to loopback, with Docker/Helm deployments explicitly binding 0.0.0.0.
• Add regression coverage for Docker PATH override attempts, helper-path lookup behavior, Docker bridge gateway parsing, Docker Desktop routing, loopback bind defaults, and multi-listener gateway binding.
• Update gateway architecture docs for Docker bridge/Desktop callback routing and explicit wildcard deployment binds.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable) N/A, no e2e path changed

Additional targeted checks:

• cargo test -p openshell-driver-docker
• cargo test -p openshell-server gateway_listener_addresses
• cargo check -p openshell-server -p openshell-driver-docker
• openshell sandbox create --name desktop-routing-final --no-keep --no-tty -- true against Docker Desktop gateway
• docker inspect confirmed Docker Desktop containers use ExtraHosts=["host.openshell.internal:host-gateway"]
• lsof -nP -iTCP:18080 -sTCP:LISTEN confirmed the local Docker gateway listens on 127.0.0.1:18080
• cargo test -p openshell-sandbox find_trusted_binary (macOS host compiles crate but Linux-only tests are filtered)
• cargo zigbuild -p openshell-sandbox --target aarch64-unknown-linux-gnu
• cargo zigbuild -p openshell-sandbox --target aarch64-unknown-linux-gnu --tests

Checklist

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

[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.