Philippe Martin
857af42a16
* feat(vm): support corporate HTTP forward proxy egress for microVM sandboxes The corporate forward proxy machinery from #1792 is driver-agnostic and already merged: openshell-supervisor-network implements CONNECT chaining, NO_PROXY matching, credentials, https:// proxies and corporate CA trust, and openshell-sandbox exposes it as six argv-only flags. Podman gained the driver half in #2245/#2512 and Kubernetes in #2633; the VM driver had none of it, so VM sandboxes on proxy-only networks could not reach any destination requiring the proxy even when policy allowed it. The blocking piece was not proxy logic but delivery: the VM guest init script runs as PID 1 and execs a fixed supervisor command line, and libkrun's krun_set_exec receives an empty argv, so there was no channel for driver-owned supervisor arguments. The supervisor's proxy flags deliberately have no environment fallback, and build_guest_environment merges user-supplied environment, so the guest env is not a safe transport either. Add a driver-authored argument file, mirroring the existing init.d manifest: the driver writes /opt/openshell/supervisor-args into the overlay upperdir on every launch and the guest reads it verbatim, one argument per line, appending it to every supervisor exec. It is written even when empty, which is what makes the channel unforgeable -- the upperdir always shadows the read-only image layer, so an image can neither supply its own arguments nor disable the operator's by omitting the file. Because both launch backends exec the same init script, this covers libkrun and QEMU without touching either. A microVM has no bind mounts or container secrets, so the credential and CA bundle are staged into the per-sandbox overlay the way the gateway JWT already is: credential root-only at 0600, CA at 0644, both rewritten every launch so a removed setting clears prior material, and both deleted with the sandbox state directory. This places the credential at rest in the overlay image on the gateway host, which differs from the Podman secret model and is documented as an explicit security consideration. Validation is fail-closed and shared: a new openshell_core::driver_utils::validate_upstream_proxy_settings holds the pairing rules the Podman driver established, and both the gateway and the driver call it so an invalid table names the offending key instead of surfacing as an opaque driver-readiness timeout. Guest egress leaves through gvproxy, so a proxy on the gateway host's loopback is reachable only through host.openshell.internal; the guest to gateway callback is unaffected. Closes #3088 Signed-off-by: Philippe Martin <phmartin@redhat.com> * fix(vm): bound the proxy CA read and scope the host-loopback recipe Two review findings on the corporate forward proxy support for microVM sandboxes. The driver read the operator's proxy_ca_bundle with an unbounded fs::read and accepted it on a substring match for the PEM BEGIN CERTIFICATE marker. A special file such as /dev/zero therefore grew driver memory without bound on every authorized sandbox create, and a PEM block holding invalid DER passed the host check but contributes no trust anchor in the guest, so every supervisor would fail after boot with an error attributed to the sandbox rather than to the setting. Move the read into openshell-core as read_upstream_proxy_ca_bundle_file: it reuses the credential reader's bounded-read path (non-regular files rejected on fstat, size capped, read bounded even if the file grows), then requires at least one anchor that RootCertStore::add_parsable_certificates accepts. The supervisor's own reader now delegates to it, so host acceptance and guest acceptance are the same function and cannot drift. The published host-loopback recipe was written for libkrun only. gvproxy NATs host.openshell.internal to the gateway host's 127.0.0.1, but GPU sandboxes run on the QEMU/TAP backend where that name resolves to the TAP host address and the driver's own nftables input chain accepts only the gateway port from the guest — no proxy on the gateway host is reachable there at any bind address, so an operator following the generic recipe lost all proxy-required egress while configuration validation succeeded. Scope the recipe to libkrun in every reference and reject a gateway-host proxy URL when a launch plan resolves to QEMU, naming the reason, instead of booting a sandbox whose policy-approved CONNECTs all time out. Signed-off-by: Philippe Martin <phmartin@redhat.com> * fix(vm): match the QEMU proxy preflight to the selected TAP host The gateway-host proxy guard added for the QEMU/TAP backend classified the wrong set of addresses in both directions. It ran at the top of configure_qemu_launch_plan, before the subnet allocation that settles plan.host_ip, so it could not compare against the address the guest actually reaches the host on. An operator pointing https_proxy at the sandbox's own TAP host address, such as 10.0.128.1, passed the check, and the driver's nftables input chain — which accepts only the gateway port from the guest — then dropped every policy-approved CONNECT, which is exactly the silent timeout the guard exists to prevent. In the other direction it rejected 192.168.127.254 unconditionally. That address is special only to libkrun/gvproxy; on QEMU/TAP it is an ordinary address that may be routable through the guest's masqueraded egress, so the guard refused a working configuration. Run the check after the launch plan's network allocation, on both the freshly-allocated and already-complete paths, and compare IP literals with that sandbox's selected TAP host. Loopback literals, localhost, and the documented host aliases that write_host_gateway_aliases seeds to the TAP host still classify as the gateway host, and the failure names the address. The gvproxy host-loopback constant returns to being a documentation anchor. Signed-off-by: Philippe Martin <phmartin@redhat.com> --------- Signed-off-by: Philippe Martin <phmartin@redhat.com>
Governance Interceptor Example
This standalone example implements the
openshell.gateway_interceptor.v1.GatewayInterceptor service. It demonstrates
how an interceptor can vend provider profiles and make them the gateway's
authoritative profile source.
- provider profile YAML lives in
profiles/*.yaml provider list-profilesshows only the profiles vended by this interceptor- providers can only be created with a
typethat matches one of those vended profile IDs - every vended provider profile gets governance annotations for its hash, signature, and signing key ID
- every new sandbox receives
policy.yamlduringCreateSandbox - requested sandbox providers must match one of the vended profile IDs
- every new sandbox gets an
openshell.nvidia.com/policy-signaturemetadata annotation that is used to verify the policy - sandbox creation evaluations add a
correlation_idlog annotation for gateway audit logs, plus non-secret policy hash/signing key metadata - sandbox policy synchronization must carry the current signed governance policy; unsigned, stale, or modified policies are denied for every caller
- sandbox policy analysis may report telemetry, but sandbox-authored policy proposals are denied before they reach the gateway handler
proposal_approval_mode=autois blocked at both sandbox and global scope- users cannot import or update provider profiles outside the vended set
- provider profile deletion is blocked by the interceptor
Run the interceptor:
cargo run -- \
--listen 127.0.0.1:18081 \
--policy policy.yaml \
--profiles profiles \
--gateway-endpoint http://127.0.0.1:8080
At startup the example parses policy.yaml, converts it to the protobuf JSON
shape used by sandbox creation, computes a canonical SHA-256 digest, and signs
that digest as an EdDSA JWT. The interceptor adds that JWT to each governed
sandbox under metadata.annotations["openshell.nvidia.com/policy-signature"]
and verifies the JWT against the sandbox policy during the CreateSandbox
validate phase. The signing key is generated in memory on each interceptor
start. This keeps the example self-contained. Production governance services
should load managed signing keys, publish verifier keys, and define a rotation
process.
The example owns this digest contract independently of the gateway. It uses a
local reflected protobuf codec, recursively sorts ProtoJSON object keys, and
preserves repeated-field order. Policy and profile hashes use the
sha256:v2:<hex> format, and their JWTs require
hash_algorithm=openshell-governance-protojson-sha256-v2. The gateway's policy
hash is a separate operational revision identifier and is not expected to
match the signed governance hash.
The interceptor polls the policy file every second by default. When policy.yaml
changes and parses successfully, the interceptor re-signs it immediately. New
sandboxes receive the updated signed policy through CreateSandbox. If
--gateway-endpoint is set, the example also lists running sandboxes and calls
UpdateConfig for ready or provisioning sandboxes so dynamic policy changes
propagate through the normal sandbox config polling path. Static baseline
changes that the gateway rejects for existing sandboxes are logged and still
apply to newly created sandboxes.
The example also validates SubmitPolicyAnalysis. Requests without proposed
policy chunks remain available for denial and network-activity telemetry.
Requests containing proposed chunks are denied, so a sandbox cannot use the
gateway's optional auto-approval path to widen its governed policy. This rule
belongs to the example: gateways without this binding retain the standard
proposal workflow.
Provider profile YAML files are loaded by the interceptor from --profiles
(default: this example's profiles/ directory). The interceptor names each
profile from its filename without the extension: profiles/github.yaml becomes
profile ID github, and profiles/slack.yaml becomes profile ID slack. The
YAML files do not need an id field; if one is present, the filename still wins.
The interceptor advertises provider_profiles = true in its manifest and vends
the current profile set through SnapshotProviderProfiles. The gateway config
selects the interceptor as its only provider profile source, so
provider list-profiles shows only github and slack; built-in and user
sources are omitted. The example signs each profile's canonical protobuf payload
and exposes the JWT under
annotations["openshell.nvidia.com/profile-signature"]; the signed hash and key
ID are exposed beside it. These annotations demonstrate logic an interceptor
can own; the gateway treats them as opaque metadata and does not verify them.
Valid edits to files under profiles/ change the profile signature and snapshot
revision, so running sandboxes that use the edited provider profile reload their
effective provider-derived policy through the normal gateway config polling
path. Invalid edits keep the last valid snapshot active.
Gateway TOML snippet:
[openshell.gateway]
provider_profile_sources = [
{ type = "interceptor", name = "provider-governance" },
]
[[openshell.gateway.interceptors]]
name = "provider-governance"
grpc_endpoint = "http://127.0.0.1:18081"
order = 10
failure_policy = "fail_closed"
binding_policy = "allowlist"
timeout = "500ms"
max_response_bytes = 1048576
max_patches = 32
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/CreateSandbox"
phases = ["modify_operation", "validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/CreateProvider"
phases = ["validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/UpdateConfig"
phases = ["validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/SubmitPolicyAnalysis"
phases = ["validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/ImportProviderProfiles"
phases = ["validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/UpdateProviderProfiles"
phases = ["validate"]
[[openshell.gateway.interceptors.bindings]]
rpc = "openshell.v1.OpenShell/DeleteProviderProfile"
phases = ["validate"]
Run the launcher script to start a local gateway with the interceptor attached. The script prints the gateway endpoint and log paths, then keeps the gateway and interceptor running until you press Ctrl-C:
./smoke.sh
To run the governance smoke test suite and stop the gateway when it completes:
./smoke.sh --test-suite
The suite uses a gateway-signed JWT for the created sandbox identity to attempt an unsigned policy widening and a policy proposal. It verifies that both are denied, telemetry is accepted, and the active policy version and hash remain unchanged.