feat(sandbox,podman): trust corporate CA for https:// proxies and intercepted TLS

[feloy]

Summary

Adds support for https:// corporate egress proxies and for trusting an operator-provided corporate CA bundle, so sandboxes can reach a forward proxy that terminates TLS with a private CA and can operate behind a TLS-intercepting proxy (mitmproxy, squid ssl-bump) that re-signs tunneled server certificates. The feature is delivered through the hardened, driver-supplied argument model — never environment variables — and is fail-closed.

Related Issue

Refs #1792

Changes

• Shared URL validator (openshell-core): parse_upstream_proxy_url now accepts https:// (recording the scheme via a new UpstreamProxyAddr.secure), keeping the explicit-port requirement; adds the PROXY_CA_MOUNT_PATH container mount constant.
• Supervisor (openshell-supervisor-network):
  • ProxyEndpoint gains a TLS client config; for an https:// proxy the connection to the proxy is wrapped in TLS (verifying the proxy certificate) before the CONNECT handshake.
  • PrefixedStream now wraps a Plain/Tls UpstreamStream enum so the relay paths consume either transport transparently.
  • The corporate CA bundle is read fail-closed (unreadable or certificate-free file is fatal) and reuses the existing build_upstream_client_config; tls_connect_upstream was already generic, so l7/tls.rs is unchanged.
  • run.rs folds the corporate CA into the sandbox combined trust bundle (write_ca_files) and the L7 upstream verification store, so intercepted upstream handshakes succeed and sandbox workloads trust the re-signed certificates.
• Config surface: new --upstream-proxy-ca-bundle supervisor argument (no env =); new Podman driver proxy_ca_bundle setting (TOML key, --sandbox-proxy-ca-bundle, OPENSHELL_SANDBOX_PROXY_CA_BUNDLE). The driver validates the pairing (a CA bundle requires a proxy URL), bind-mounts the host PEM read-only into the sandbox (a CA certificate is not secret, so a plain bind mount rather than a driver secret), and performs a create-time readability check.
• Dev tooling: the standalone gateway task (tasks/scripts/gateway.sh) passes OPENSHELL_SANDBOX_PROXY_CA_BUNDLE through to the generated Podman config, so a local gateway can be pointed at a TLS-intercepting proxy without hand-editing the regenerated TOML.
• Docs: updated docs/reference/gateway-config.mdx, the Podman driver README.md, and the architecture/sandbox.md trust-model section.

Testing

• mise run pre-commit passes
• Unit tests added/updated — URL parsing (http/https, socks rejected), TLS-wrapped CONNECT against a fake TLS proxy (trusted-CA success and untrusted-cert rejection), fail-closed CA-bundle validation, and Podman driver config validation + bind-mount/argv assertions.
• E2E tests added/updated — new serialized podman_corporate_proxy case drives an https:// proxy end to end: the fake proxy self-signs, exposes its CA, and that CA is fed back via proxy_ca_bundle. (Runs only in the Podman e2e job.)
• Manually verified against a real TLS-intercepting proxy — mitmproxy on the Podman sandbox network, reached as an https:// proxy with its CA supplied via proxy_ca_bundle. This exercises both halves in one run: the TLS-wrapped CONNECT to the proxy listener, and the upstream certificate that mitmproxy re-signs with the same CA.

Checklist

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

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

[derekwaynecarr]

Rather than make a change for just podman, can you explore having parity across all compute drivers, or note why its not possible before we merge this?

[feloy]

Rather than make a change for just podman, can you explore having parity across all compute drivers, or note why its not possible before we merge this?

My idea would be to implement by pieces as small as possible. The first part (#2245) is connection to proxy with http only and Podman only. This PR is connection to proxy with https and certificate, for Podman only. The follow-up PRs would be the full stack (http+https) for each other driver. For Docker, it should be very similar, but I still didn't investigate what would be needed for others drivers.

[kevin-pedretti]

Just a quick note to say I tested this PR and it worked in my environment. This got things working with my proxy that does SSL interception.

It may be useful to separate the host path and gateway container paths so they don't need to match. For example, something like:

  [podman]
  proxy_ca_bundle = "/etc/openshell/certs/ca-bundle.pem"  # Path for gateway to validate
  proxy_ca_bundle_host_path = "/home/myuser/ca-bundle.pem"  # Path for host Podman

  # If host_path is unset, use proxy_ca_bundle (backwards compatible)

With the current setup, I had to be careful to make sure the host and container paths to ca-bundle.pem matched. Otherwise sandbox creation fails when the gateway tries to validate the (single) path specified by proxy_ca_bundle (a host path).

[feloy]

Just a quick note to say I tested this PR and it worked in my environment. This got things working with my proxy that does SSL interception.

It may be useful to separate the host path and gateway container paths so they don't need to match. For example, something like:

  [podman]
  proxy_ca_bundle = "/etc/openshell/certs/ca-bundle.pem"  # Path for gateway to validate
  proxy_ca_bundle_host_path = "/home/myuser/ca-bundle.pem"  # Path for host Podman

  # If host_path is unset, use proxy_ca_bundle (backwards compatible)

With the current setup, I had to be careful to make sure the host and container paths to ca-bundle.pem matched. Otherwise sandbox creation fails when the gateway tries to validate the (single) path specified by proxy_ca_bundle (a host path).

@kevin-pedretti thanks for testing this PR.

I don't think this change is necessary: proxy_ca_bundle is where the ca bundle is found in your host ("/home/myuser/ca-bundle.pem" in your case) , and the ca bundle will be mounted in an hardcoded path in the container ("/etc/openshell/tls/proxy/ca-bundle.pem").