Access

Access is the GlobalStacks surface for controlled sandbox egress. It combines write-only secrets, outbound policies, and grants to blueprints or sandboxes so workloads can reach approved services without storing long-lived credentials in sandbox definitions.

Access is separate from runtime networks. Runtime networks connect sandboxes to each other through GlobalStacks DNS aliases and policy checks. Access controls outbound HTTP or HTTPS traffic from a sandbox to external destinations.

Model

Access has four user-facing records:

• Access secrets store reusable credential values encrypted by the control plane. Secret values are write-only after creation.
• Access policies match outbound destinations by host, optional path prefixes, and optional HTTP methods.
• Access policy grants attach policies to blueprints or sandboxes. Blueprint grants are inherited by sandboxes created from that blueprint, and sandbox grants apply directly to one sandbox.
• Access secret grants deliver selected secrets as explicit sandbox environment variables when that workflow is required.

Policy evaluation, secret expansion, and header injection run outside the sandbox workload in an agent-managed egress component. Sandbox application code should not receive proxy credentials, Access secret values used only for egress headers, or GlobalStacks control material.

Transparent egress

Access egress is transparent-only. Supported runtimes route sandbox outbound traffic through the agent-managed Access egress path without requiring application code changes, proxy environment variables, or application-level proxy configuration.

There is no explicit proxy fallback for Access. If the agent cannot enforce transparent interception for a sandbox runtime, Access egress is unavailable for that runtime and should be reported as unsupported.

Unsupported runtime constraints include:

• no agent control over the sandbox network namespace, firewall, or routing rules
• rootless or restricted container mode without privileges for transparent redirection
• non-Linux hosts until equivalent transparent interception is implemented
• host-networked sandboxes that bypass the managed sandbox namespace
• protocols outside the Access egress path, such as UDP, QUIC, or raw sockets when only TCP HTTP(S) is supported
• sandbox engines where the agent cannot attach the Access egress component

Headers

Access policy headers are generic outbound request headers, not provider-specific authentication helpers. A policy can inject authentication headers, tenant or routing headers, beta or feature flags, and other API-specific headers.

Use one --header Name=Value flag for each injected header:

gstacks access policy create api-example \
  --host api.example.com \
  --method POST \
  --path /v1/* \
  --header 'Authorization=Bearer {{secret:example-token}}' \
  --header 'X-Tenant=customer-123' \
  --header 'X-Feature-Flag=agent-runtime'

Header values may reference Access secrets through secret templates such as {{secret:example-token}}.

Access controls safe outbound headers. Hop-by-hop or proxy-controlled headers are not appropriate policy data because the proxy or HTTP stack must own them. Examples include Connection, Content-Length, Host, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding, and Upgrade.

When a sandbox request already includes a header that an Access policy injects, the Access policy value is the intended authority for that governed destination. Do not rely on sandbox-provided values for headers managed by Access.

HTTPS behavior

HTTPS egress has two distinct modes:

• Opaque HTTPS egress can allow or deny traffic by destination, but it cannot inspect encrypted HTTP requests or inject HTTP headers.
• Intercepted HTTPS egress can inject headers only when the sandbox trusts a GlobalStacks-controlled interception CA and the Access proxy terminates TLS for an explicitly eligible destination.

Access must not silently intercept all TLS traffic. Interception eligibility, CA bootstrap, certificate lifecycle, tenant isolation, and operational debugging are still behavior that must settle before the HTTPS interception contract is published.

If a policy requires header injection for an HTTPS destination that is not eligible for interception, the safe behavior is to deny by default rather than send the request without the required headers. Certificate-pinned clients and some SDKs may reject intercepted HTTPS even when the sandbox has been configured to trust the GlobalStacks CA.

The agent-generated Access CA is scoped to the sandbox egress path. The CA private key is mounted into the sidecar, while the sandbox receives a CA bundle at /etc/globalstacks/access-egress-ca-bundle.crt with common trust environment variables such as NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, and SSL_CERT_FILE. The sidecar rotates an invalid or near-expiry CA and emits access_egress_decision log lines for allow, deny, intercept, and upstream error decisions without logging injected header values or expanded secrets.

Operations

The Access egress sidecar requires Linux transparent redirection privileges. On Docker hosts that means the sidecar runs with NET_ADMIN, mounts the generated broker rules and interception CA files, and the sandbox container shares the sidecar network namespace. A sandbox without Access egress remains in Docker network mode none.

Production hosts should pin the sidecar image by digest:

export GLOBALSTACKS_EGRESS_BROKER_IMAGE='registry.example.com/globalstacks/agent@sha256:<digest>'
export GLOBALSTACKS_REQUIRE_PINNED_EGRESS_BROKER_IMAGE=1

With pinning enforcement enabled, the agent rejects mutable sidecar tags before creating the Access sidecar or sandbox container.

Operator runbook: deploy/runbooks/access-egress-sidecar.md.

CLI workflow

Create a write-only secret:

gstacks access secret create example-token --value-env EXAMPLE_TOKEN

Create an outbound policy:

gstacks access policy create api-example \
  --host api.example.com \
  --header 'Authorization=Bearer {{secret:example-token}}'

Attach the policy to a blueprint so new sandboxes inherit it:

gstacks blueprint access attach dev-ready api-example

Attach the policy directly to a sandbox:

gstacks sandbox access attach gssbx_123 api-example

Grant a secret as an environment variable only when the workload needs to read the value directly:

gstacks access secret grant --target-kind sandbox gssbx_123 example-token EXAMPLE_TOKEN

Inspect effective sandbox egress policies:

gstacks sandbox egress gssbx_123

Public contract status

Access HTTP endpoints exist in the control plane, but the public OpenAPI contract is intentionally deferred until the generic header model, transparent-only runtime behavior, and HTTPS interception model settle. Treat the CLI and console as the supported user-facing surfaces for this slice.