# Access Egress Sidecar Runbook

This runbook covers the agent-managed Access egress sidecar used for transparent sandbox HTTP and HTTPS policy enforcement.

## Runtime Model

Access egress is transparent-only. The sandbox workload does not receive proxy settings, proxy credentials, or Access secret values used only for outbound headers. The agent starts an egress sidecar outside the sandbox workload, places the sandbox container in the sidecar network namespace, and routes outbound TCP HTTP(S) traffic through the sidecar.

The sandbox container remains locked down when Access is not attached:

- Docker network mode is `none`.
- Host port publishing is disabled.
- Runtime DNS settings are not passed into the sandbox.
- Shared control-plane services such as Postgres and Redis are not reachable through a default sandbox network path.

When Access egress is attached, the sidecar owns the network namespace used by the sandbox. The sidecar installs transparent redirection rules, evaluates broker rules from the control plane, expands allowed secret templates outside the sandbox, and injects configured safe headers into matching outbound requests.

## Required Privileges

The sidecar needs `NET_ADMIN` on Linux so it can install transparent redirection rules. If the host runtime cannot provide network namespace control, firewall or routing control, or the sidecar attachment model, Access egress is unsupported for that sandbox runtime.

Unsupported examples:

- rootless or restricted container engines without transparent redirection privileges
- non-Linux hosts until equivalent transparent interception is implemented
- host-networked sandboxes that bypass the managed sandbox namespace
- protocols outside the current TCP HTTP(S) egress path

There is no explicit proxy fallback.

## Files And Environment

The agent writes generated sidecar material under a per-deployment egress broker config directory in the host temp directory.

Sidecar bind mounts:

- `/etc/globalstacks/egress-rules.json`
- `/etc/globalstacks/access-egress-ca.crt`
- `/etc/globalstacks/access-egress-ca.key`

Sandbox bind mounts:

- `/etc/globalstacks/access-egress-ca-bundle.crt`

Sandbox environment variables set when a CA bundle is mounted:

- `GLOBALSTACKS_ACCESS_CA_BUNDLE`
- `NODE_EXTRA_CA_CERTS`
- `REQUESTS_CA_BUNDLE`
- `CURL_CA_BUNDLE`
- `SSL_CERT_FILE`

Production operators should set `GLOBALSTACKS_EGRESS_BROKER_IMAGE` to a digest-pinned image reference and enable `GLOBALSTACKS_REQUIRE_PINNED_EGRESS_BROKER_IMAGE=1`. With that switch enabled, the agent rejects mutable sidecar image tags before creating either the sidecar or sandbox container.

## HTTPS Interception

Opaque HTTPS policy can allow or deny traffic by destination only. Access can inject headers into HTTPS requests only when the policy requires HTTP inspection, the sandbox trusts the generated GlobalStacks Access CA bundle, and the sidecar terminates TLS for that eligible destination.

The sidecar does not silently intercept all TLS traffic. Interception is selected only for destinations with a matching policy that requires HTTP inspection through headers, methods, or path rules. Certificate-pinned clients may reject the generated certificate and the request will fail closed.

The Access interception CA rotates when it is invalid, not yet valid, not a CA, or within the configured rotation window before expiry. Generated CA private keys are mounted only into the sidecar.

## Debugging Denied Egress

Check the sidecar logs for `access_egress_decision` entries. Decision logs include action, protocol, host, method, path, and reason where available. They must not include injected header values or expanded secret values.

Common reasons:

- `no_matching_access_policy`: no enabled policy grant covers the host.
- `opaque_HTTPS_egress_can_only_enforce_destination_policy`: the rule needs headers, method, or path matching but the request was not eligible for inspected HTTPS.
- `TLS_client_did_not_trust_interception_certificate`: the sandbox client rejected the Access CA or uses certificate pinning.
- `upstream_request_failed` or `upstream_dial_failed`: the policy matched, but the destination connection failed.

Validation checklist:

- Confirm the sandbox has an Access policy grant directly or through its blueprint.
- Confirm any referenced Access secrets still exist and have current values.
- Confirm the policy host, path prefix, and methods match the actual request.
- Confirm the sandbox process trusts `/etc/globalstacks/access-egress-ca-bundle.crt` for HTTPS header injection.
- Confirm production hosts run with `GLOBALSTACKS_REQUIRE_PINNED_EGRESS_BROKER_IMAGE=1` and a `@sha256:` sidecar image reference.