Repository navigation
Description
Summary
Implement a gRPC-based policy server that integrates with the OpenShell Gateway to enforce enterprise governance policies across the Secure Agent Workspace. This closes the Phase II policy distribution gap identified in the architecture alignment analysis — specifically: signed policy bundles, an in-VM policy agent, and centralized governance enforcement.
OpenShell already provides two gRPC extensibility mechanisms designed for exactly this purpose:
| Mechanism | Plane | Proto | Purpose |
|---|---|---|---|
| Gateway Interceptor | Control-plane | gateway_interceptor.proto |
Evaluate/mutate/reject gateway API operations (e.g., CreateSandbox, UpdateConfig, CreateProvider) |
| Supervisor Middleware | Data-plane | supervisor_middleware.proto |
Inspect/transform/deny sandbox HTTP egress before credentials are injected |
The upstream repo ships working reference implementations: examples/governance-interceptor/ (policy signing, provider profile governance, policy reload propagation) and examples/supervisor-middleware-content-guard/ (content filtering on egress).
This issue covers deploying, configuring, and extending these mechanisms as a unified policy server for the SAW OpenShift Virtualization environment.
Motivation
The NVIDIA Secure Agent Workspace Reference Design requires:
- Signed policy bundles mounted or fetched read-only by the workspace
- An in-VM policy agent that validates signatures and applies policy via the OpenShell API
- GitOps-driven policy distribution where Git is the source of truth for policy intent
- Centralized audit of governance decisions (OCSF-compatible)
Currently (Phase I), the SAW deployment relies on perimeter controls (VM isolation, OIDC, network). There is no runtime policy enforcement, no policy signing, and no centralized governance server.
Architecture & Implementation Flow
End-to-End Policy Flow
The complete flow follows the GitOps Policy Model diagram in docs/images/gitops-policy-model.png:
┌─────────────────────┐ ┌──────────────────────────────────────────┐ ┌──────────────────────────────┐
│ AUTHORING & CI │ │ RED HAT OPENSHIFT CLUSTER │ │ SINGLE-USER WORKSPACE VM │
│ │ │ │ │ │
│ 1. Git policy repo │────▶│ 3. ArgoCD reconciles │ │ 6. In-VM policy agent │
│ (policy.yaml, │ │ PolicyRelease ConfigMap │ │ watches ConfigMap/NFS, │
│ profiles/*.yml)│ │ │ │ verifies signature, │
│ │ │ 4. PolicyRelease metadata │ │ calls `openshell policy │
│ 2. CI validates, │ │ (channel, version, hash) │ │ set` via gRPC API │
│ signs, releases │ │ │ │ │
│ │ │ 5. Signed policy bundle on NFS/ConfigMap│────▶│ 7. OpenShell runtime │
│ │ │ (policy.yaml + manifest.json + │ │ confirms loaded revision │
│ │ │ signature.sig) │ │ via ReportPolicyStatus │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────┐ │ │ │
│ │ │ │ gRPC POLICY SERVER (new) │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ Gateway Interceptor: │ │ │ │
│ │ │ │ - Signs & injects policy │ │ │ │
│ │ │ │ - Validates CreateSandbox │ │ │ │
│ │ │ │ - Governs provider profiles │ │ │ │
│ │ │ │ - Blocks unauthorized │ │ │ │
│ │ │ │ policy changes │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ Supervisor Middleware: │ │ │ │
│ │ │ │ - Content filtering │ │ │ │
│ │ │ │ - Egress inspection │ │ │ │
│ │ │ └──────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ OpenShell Gateway ◄─── gRPC ───────────│─────│── Supervisor │
│ │ │ (stores & distributes policy) │ │ (enforces policy) │
└─────────────────────┘ └──────────────────────────────────────────┘ └──────────────────────────────┘
Component Breakdown
Component 1: Gateway Interceptor (Control-Plane Governance)
What it does: Evaluates gateway API operations after authentication and before handler dispatch. Implements the GatewayInterceptor gRPC service defined in proto/gateway_interceptor.proto.
gRPC Interface:
service GatewayInterceptor {
rpc Describe(DescribeRequest) returns (InterceptorManifest);
rpc SnapshotProviderProfiles(ProviderProfileSnapshotRequest) returns (ProviderProfileSnapshot);
rpc Evaluate(InterceptorEvaluation) returns (InterceptorResult);
}Bindings to implement:
| Binding ID | RPC Method | Phases | Behavior |
|---|---|---|---|
govern-create-sandbox |
CreateSandbox |
modify_operation, validate |
Inject signed baseline policy into every sandbox; reject if policy doesn't match governance baseline |
govern-create-provider |
CreateProvider |
validate |
Only allow providers using vended (governed) provider profiles |
govern-update-config |
UpdateConfig |
validate |
Block unauthorized sandbox policy changes; validate policy signature on updates |
govern-submit-policy-analysis |
SubmitPolicyAnalysis |
validate |
Block sandbox-authored policy proposals when governance is active |
govern-import-provider-profiles |
ImportProviderProfiles |
validate |
Only allow managed profile imports |
govern-update-provider-profiles |
UpdateProviderProfiles |
validate |
Only allow managed profile updates |
govern-delete-provider-profile |
DeleteProviderProfile |
validate |
Block all profile deletes under governance |
Key behaviors:
- Policy signing: Generate Ed25519 keypair at startup; sign policy hash as JWT (EdDSA); attach
openshell.nvidia.com/policy-signatureannotation to every sandbox - Policy hot-reload: Watch
policy.yamlon disk; on change, re-sign and propagate to all running sandboxes viaUpdateConfigRPC with governance annotations - Provider profile governance: Vend signed provider profiles via
SnapshotProviderProfiles; only allow sandboxes and providers to use governed profiles - Failure policy:
fail_closed— if the policy server is unreachable, all governed operations are denied
Component 2: Supervisor Middleware (Data-Plane Content Filtering)
What it does: Inspects and transforms HTTP egress requests from sandboxes before credentials are injected. Implements the SupervisorMiddleware gRPC service defined in proto/supervisor_middleware.proto.
gRPC Interface:
service SupervisorMiddleware {
rpc Describe(google.protobuf.Empty) returns (MiddlewareManifest);
rpc ValidateConfig(ValidateConfigRequest) returns (ValidateConfigResponse);
rpc EvaluateHttpRequest(HttpRequestEvaluation) returns (HttpRequestResult);
}Enforcement capabilities:
- Content guard: redact or deny requests containing sensitive terms
- API scope enforcement: restrict which API paths/methods an agent can call per endpoint
- Request body inspection: scan outbound payloads for policy violations
Evaluation context available per request:
RequestContext: request ID, sandbox ID, originating process binary + PID + ancestor chainHttpRequestTarget: scheme, host, port, HTTP method, path, query- Request headers (before credential injection, max 128 lines / 64 KiB)
- Buffered request body (up to 4 MiB)
Component 3: In-VM Policy Agent (Policy Distribution)
What it does: Runs inside the workspace VM, watches for policy bundle updates from the cluster (via NFS mount or ConfigMap), verifies bundle signatures, and applies policy via the OpenShell CLI/API.
Flow:
- Watch for PolicyRelease metadata changes (ConfigMap with channel, version, hash)
- Read the signed policy bundle from NFS/ConfigMap mount
- Verify the bundle signature against the governance interceptor's public key
- Apply policy via
openshell policy set --file policy.yaml - Report loaded revision to the gateway via
ReportPolicyStatusgRPC call
Gateway Configuration
TOML Configuration
The Gateway must be configured to connect to both the interceptor and middleware services:
[openshell.gateway]
# Gateway interceptor configuration
[[openshell.gateway.interceptors]]
name = "governance"
grpc_endpoint = "http://policy-server.saw-system.svc.cluster.local:18081"
binding_policy = "exact" # declared and configured bindings must match
failure_policy = "fail_closed"
# Optional: use interceptor as provider profile source
provider_profile_source = true
# Supervisor middleware configuration
[[openshell.supervisor.middleware]]
name = "content-guard"
grpc_endpoint = "http://policy-server.saw-system.svc.cluster.local:50051"
max_body_bytes = 262144 # 256 KiB
timeout = "500ms"Sandbox Policy Attachment
Middleware is attached to sandbox policy via network_middlewares:
network_middlewares:
content-filter:
name: content-filter
middleware: content-guard # matches operator registration name
config:
mode: redact
terms: ["SECRET_KEY", "password", "credential"]
on_error: fail_closed
endpoints:
include: ["*.openai.com", "*.anthropic.com"]
order: 1Implementation Plan
Phase 1: Deploy Governance Interceptor (Control-Plane)
- Build the governance interceptor binary from
examples/governance-interceptor/as a container image - Create Helm chart under
charts/policy-server/for deploying the interceptor as a Kubernetes Deployment + Service - Create governance
policy.yamldefining the baseline sandbox policy (network endpoints, filesystem, process rules) - Create provider profile YAML files under
profiles/for each governed provider (anthropic, openai, nvidia, etc.) - Configure Gateway TOML to register the interceptor with
binding_policy: exactandfailure_policy: fail_closed - Mount the governance signing key as a Kubernetes Secret
- Add ArgoCD Application to deploy the policy server via GitOps
Phase 2: Deploy Supervisor Middleware (Data-Plane)
- Build or extend the content-guard middleware as a container image
- Add middleware Deployment + Service to the policy-server Helm chart
- Register the middleware in Gateway TOML under
[[openshell.supervisor.middleware]] - Define default content filtering rules in the governance policy
- Test middleware evaluation against sandbox HTTP egress (verify redaction/denial)
Phase 3: Policy Distribution Pipeline
- Create a
policy-bundles/directory in the Git repo for authored policy YAML - Implement CI validation pipeline: parse policy YAML, run
openshell-proverfor formal verification, sign bundle - Create PolicyRelease ConfigMap template (channel, version, hash pointer)
- Deploy NFS storage (or use ConfigMap volume) for signed bundle distribution to workspace VMs
- Implement in-VM policy agent (shell script or Go binary) that watches bundle mount and applies via
openshell policy set - Wire
ReportPolicyStatusto confirm loaded revision back to gateway
Phase 4: Audit & Observability
- Enable OCSF structured logging for governance decisions at the interceptor
- Forward interceptor
log_annotations(correlation IDs, policy hashes, signature KIDs) to the cluster logging pipeline - Add Grafana dashboard for policy decision metrics: allowed/denied/error counts per binding
- Surface policy reload propagation events in the audit trail
Expected Results
Functional Outcomes
-
Every sandbox gets a signed baseline policy: The governance interceptor injects the organization's policy into
CreateSandboxduring themodify_operationphase and validates the signature in thevalidatephase. Sandboxes cannot be created without a valid governance-signed policy. -
Unauthorized policy changes are blocked: Sandbox-scoped policy updates via
UpdateConfigmust carry a valid governance signature. Merge operations and sandbox-authored policy proposals are rejected. Only the governance server can author policy. -
Provider profiles are governed: Only provider types matching the governance interceptor's vended profiles can be used. Ad-hoc provider creation is blocked. Profile imports, updates, and deletes are restricted.
-
Egress content is filtered: HTTP requests from sandboxes to configured endpoints pass through the supervisor middleware before credentials are injected. Sensitive content is redacted or requests are denied based on policy.
-
Policy updates propagate to running sandboxes: When
policy.yamlchanges on disk, the interceptor re-signs the policy and callsUpdateConfigon all running sandboxes with governance annotations and a correlation ID. -
GitOps-driven policy lifecycle: Policy changes flow through Git → CI validation/signing → ArgoCD → cluster → workspace VMs, with signature verification at each boundary.
Non-Functional Outcomes
- Fail-closed posture: If the policy server is unreachable, all governed gateway operations are denied
- Audit trail: Every governance decision is logged with correlation IDs and policy hashes
- No credential exposure: Protobuf fields marked with
(openshell.options.v1.secret)are recursively omitted from interceptor evaluations; middleware evaluates requests before credential injection
gRPC Communication Diagram
┌─────────────────────────┐
│ gRPC Policy Server │
│ │
Describe ────────▶│ GatewayInterceptor │
Evaluate ────────▶│ :18081 │
SnapshotProfiles ─────────▶│ │
│ │
Describe ────────────▶│ SupervisorMiddleware │
ValidateConfig ───────────▶│ :50051 │
EvaluateHttpRequest ───────────▶│ │
└─────────────────────────┘
▲ ▲
│ │
┌───────────┘ └────────────┐
│ │
┌─────────┴─────────┐ ┌───────────┴──────────┐
│ OpenShell │ │ Sandbox Supervisor │
│ Gateway │ │ (in-VM) │
│ │ │ │
│ Control-plane │ │ Data-plane │
│ gRPC routing: │ │ HTTP egress: │
│ - CreateSandbox │ │ - EvaluateHttpReq │
│ - UpdateConfig │ │ before credential │
│ - CreateProvider │ │ injection │
│ etc. │ │ │
└───────────────────┘ └───────────────────────┘
Reference Materials
- Gateway Interceptor RFC:
tmp-upstream-openshell/rfc/0010-gateway-interceptors/README.md - Supervisor Middleware RFC:
tmp-upstream-openshell/rfc/0009-supervisor-middleware/README.md - Gateway architecture:
tmp-upstream-openshell/architecture/gateway.md - Security policy architecture:
tmp-upstream-openshell/architecture/security-policy.md - Proto definitions:
tmp-upstream-openshell/proto/gateway_interceptor.proto,tmp-upstream-openshell/proto/supervisor_middleware.proto - Governance interceptor example:
tmp-upstream-openshell/examples/governance-interceptor/ - Content guard middleware example:
tmp-upstream-openshell/examples/supervisor-middleware-content-guard/ - Architecture alignment (gap analysis):
docs/architecture-alignment.md - GitOps policy model diagram:
docs/images/gitops-policy-model.png
Activity
fix: drop offline_access from dashboard oauth2-proxy scope
sauagarwa commentedon Sep 29, 2026
Completed