LanternDocs

Egress and credentials

A sandbox is only as safe as its way out. Lantern ships two egress modes. The default mode enforces the allowlist inside the guest via an iptables-redirected CONNECT proxy. The optional broker mode (LANTERN_EGRESS_MODE=broker, Firecracker only) removes the network device entirely: every outbound request crosses a vsock to a broker in the runtime-manager on the host, which checks the sandbox's allowlist and adds the credential there. In broker mode the workload never holds the token it is using.

In plain termsThink of the VM as a room with no windows and one mail slot. The code inside can write a letter to any address, but the clerk on the other side of the slot only forwards letters to addresses on the list, and signs them with your name on the way out. The letter writer never learns your signature.

The path out

Credentials are added at the host, never inside the VM Egress through the host broker (opt-in broker mode, LANTERN_EGRESS_MODE=broker, Firecracker only). In this mode the microVM has no network device. The agent workload sends its HTTP request to the harness forwarder on 127.0.0.1:3128 through the injected proxy variables. The forwarder carries it over vsock to the host egress broker running inside the runtime-manager on the data plane host. The broker checks the VM's egress allowlist. A request to a host that is not allowlisted is refused and logged as an audit event. An allowed request gets its credential injected on the host, resolved from lantern.secret references by the secret resolver (today's production resolver is the control-plane relay, ADR 0008), and is then sent to the upstream API. The credential never enters the VM. In the default mode the allowlist is enforced in-guest via an iptables-redirected CONNECT proxy instead. Credentials are added at the host, never inside the VM Opt-in broker mode (LANTERN_EGRESS_MODE=broker, Firecracker only). A guest request leaves only over vsock. The host broker checks the allowlist and attaches the secret on the way out. microVM no network device (broker mode, opt-in) Agent workload makes an ordinary HTTPS request holds no API credentials Harness forwarder 127.0.0.1:3128 the only way out of the VM HTTPS_PROXY The credential never enters the VM. Data plane host, inside runtime-manager Host egress broker ends the vsock stream Allowlist check the VM's egress rules Credential injection header added on the host side Secret resolver lantern.secret/... refs from the spec Prod resolver today (ADR 0008): control-plane relay, /v1/runtime/secrets/resolve Refused logged as an audit event Upstream API allowlisted host vsock allowed not allowlisted External Trusted host In-VM harness Untrusted guest microVM wall Trust boundary Denied
workload → 127.0.0.1:3128 → harness → vsock → host broker (allowlist, credential) → upstream
  1. The workload sends an ordinary HTTP(S) request through 127.0.0.1:3128. The harness injects HTTP_PROXY/HTTPS_PROXY, so most clients need no change.
  2. The harness (PID 1) forwards it over vsock, the VM's only channel to the host.
  3. The broker in the runtime-manager matches the destination against the sandbox's allowlist.
  4. If the rule has an inject entry (header + secret_uri), the broker resolves the secret on the host and sets that header, replacing any placeholder the workload sent.
  5. The request goes upstream. A denied request is refused and written to the audit stream.
Egress in broker modeThe workload's request leaves the VM over vsock; the host broker decides, dials, and adds the credential. The VM never holds it.Opt-in: LANTERN_EGRESS_MODE=broker · Firecracker only · ADR 0026

1. CONNECT api.github.com:443

The workload uses HTTPS_PROXY=http://127.0.0.1:3128 as usual.

src/egress_forwarder.rs:3 (broker branch)

Allowlist

Each spawn declares its egress rules (host pattern, HTTP methods, rate). Anything not listed is denied. The broker also refuses private and metadata IP ranges and allows only port 443 unless LANTERN_EGRESS_ALLOWED_PORTS says otherwise. In broker mode (LANTERN_EGRESS_MODE=broker) the VM has no network device, so a client that ignores proxy variables simply has no route. In the default mode iptables redirects all traffic to the in-guest proxy. Denials are security-critical audit events and are never dropped, even across a brief manager outage.

Credential injection

Specs reference secrets by secret_uri, never by value. The broker resolves the ref on the host and sets the header on the outbound request, so the secret exists only on the host side of the vsock. A compromised workload cannot exfiltrate a key it never received. For HTTPS, the broker terminates TLS only for hosts whose rule injects a credential, using a per-VM ephemeral CA that is name-constrained to those hosts. Every other host is an opaque CONNECT tunnel, end-to-end TLS.

Terminal recording, recorded on Lima nested KVM: the broker-mode e2e test passes — no TAP and no eth0, exec over vsock, the credential injected upstream while the guest saw only a placeholder, plain-HTTP to :443 refused, a mismatched Host refused, a non-allowlisted host denied, and the secret absent from the manager log.
infra/firecracker/broker-e2e.sh against real httpbin.org on Firecracker 1.15.1, recorded on Lima nested KVM (aarch64). Unedited output, filtered to PASS lines.

Related: Identity and secrets, Isolation classes, Security.