Document and Harden Raw TCP Allowlists for HPC services

Problem Statement

Summary

Document and validate a supported OpenShell pattern for allowing sandboxed workloads to reach specific internal TCP endpoints without granting broad network egress.

This is important for HPC-style workloads that need narrow access to internal services such as license servers, model gateways, databases, artifact services, source-control gateways, or scheduler-adjacent infrastructure.

Background

OpenShell already supports dynamic network_policies where each policy block declares:

• endpoints,
• binaries allowed to use those endpoints,
• protocol-specific handling for REST / WebSocket / GraphQL,
• raw TCP passthrough when protocol is omitted.

Relevant docs:

• https://docs.nvidia.com/openshell/latest/sandboxes/policies
• https://docs.nvidia.com/openshell/latest/reference/policy-schema

The docs indicate that network_policies are dynamic / hot-reloadable and that endpoints without protocol allow TCP streams through without payload inspection.

Problem

Many HPC workloads do not need broad internet access, but they do need narrowly scoped access to internal TCP services.

Examples: license servers, internal model or inference gateways, package mirrors, artifact stores, metadata services, source-control gateways, experiment tracking systems, internal APIs exposed over non-HTTP protocols.

For production HPC use, this should be an explicit, supported, documented pattern.

Proposed Design

Requested behavior

Provide a documented and validated raw TCP allowlist pattern like:

network_policies:
  license_server:
    name: license-server
    endpoints:
      - host: license-server.example.org
        port: 5280
        enforcement: enforce
        access: full
    binaries:
      - path: /hpc/tools/bin/tool-a
      - path: /hpc/tools/bin/tool-b

  model_gateway:
    name: model-gateway
    endpoints:
      - host: model-gateway.example.org
        port: 443
        enforcement: enforce
        access: full
    binaries:
      - path: /opt/agent/bin/agent

For non-HTTP services, raw TCP passthrough should be supported by omitting protocol.

Requirements

• Support explicit host:port and/or ip:port raw TCP allowlists.
• Support private/internal IP ranges only when explicitly allowed.
• Scope access by binary path where possible, not only by whole sandbox.
• Log denied connections with: destination host/IP, port, binary path, and policy name / reason.
• Clarify hot-reload behavior for raw TCP streams: new connections should use updated policy; existing raw streams may remain connection-scoped if that is current behavior.
• Provide examples for: internal license server, internal model gateway, no-default-internet cluster posture.

Acceptance criteria

• A sandboxed binary can connect to an explicitly allowed internal TCP service.
• The same binary cannot connect to an unlisted host or port.
• A non-listed binary cannot connect to the service, even if the destination is allowlisted for another binary.
• Denials are visible in OpenShell logs or terminal output.
• Policy update behavior is documented and test-covered for raw TCP.

Why this matters

HPC deployments often operate in restricted network environments. OpenShell should support least-privilege internal connectivity: narrow, auditable, policy-controlled access to required services, without requiring broad egress.

Alternatives Considered

N/A

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

Start with the linked OpenShell network policy and policy-schema documentation, then trace the current network_policies handling for raw TCP endpoints, binary scoping, denials, and hot reload. Done means documented license-server, model-gateway, and restricted-egress patterns plus validation covering allowed and denied destinations, binary restrictions, denial visibility, and policy updates.