Skip to main content
Secret injection keeps credentials out of the guest while allowing requests to trusted endpoints. This page explains the boundary of that protection. For the configuration surface like binding secrets, allow lists, and placeholders, see Secrets.

​
The idea

Instead of putting a real credential inside the VM, microsandbox puts a placeholder there. The real value stays in host memory. When the guest sends a request to a host you’ve allowed, the host-side network stack swaps the placeholder for the real value at the network boundary, on the way out. Anywhere else, the placeholder is just a meaningless string. So a workload can call an API with a credential it never actually holds.

​
The data flow

  1. You bind a secret to an environment variable and list the hosts it’s allowed for.
  2. The guest’s environment receives a placeholder ($MSB_<env_var> by default), never the real value.
  3. The workload uses the placeholder as if it were the credential, in a header, auth field, query string, or body.
  4. On egress to an allowed host, the host-side proxy decrypts the intercepted TLS, verifies the request is really going where it claims, substitutes the real value, and forwards it upstream.
  5. The upstream server receives the real credential. The guest never did.
A placeholder becomes the real secret only at an allowed host; any other host receives only the placeholder.A placeholder becomes the real secret only at an allowed host; any other host receives only the placeholder.

​
What gates a substitution

A placeholder only becomes a real value when every one of these holds. They use the same DNS and SNI machinery the network page describes:
  • Allowed-host match. The TLS SNI matches one of the secret’s allowed host patterns.
  • DNS pin. The destination IP was actually resolved for that host through the interceptor, so a hard-coded IP with a forged SNI doesn’t qualify.
  • TLS identity. By default a secret requires intercepted TLS, so it is never substituted over a connection the host can’t see into.
  • Authority alignment. For intercepted HTTP, the request’s Host or :authority must match the SNI, which closes domain-fronting.
If substitution is not eligible and microsandbox detects the placeholder, the default policy blocks the request and logs a warning. You can choose silent blocking, sandbox termination, or scoped passthrough of the unchanged placeholder. See Violation policy. Opaque, bypassed TLS cannot be inspected for placeholders.

​
What this protects

  • The credential cannot leak to a host you didn’t allow. Detected requests to disallowed hosts are blocked by default; explicitly permitted passthrough sends only the placeholder.
  • Secret bindings do not give the guest the credential. Guest code receives the placeholder. This does not protect credentials separately supplied to the guest or returned by an allowed endpoint.
  • Hard-coded-IP and SNI-spoof exfiltration attempts don’t receive the injection at all, because they fail the DNS pin or authority checks.

​
What this does not protect

Being candid about the edges matters more than the headline.
  • The allowed endpoint receives the real credential. This stops exfiltration to other hosts. It does not stop the host you explicitly allowed from misusing what you sent it. Keep allow lists narrow. An allowed endpoint that echoes a credential in its response can expose it to the guest.
  • It needs TLS inspection for that host. Over a bypassed-TLS domain, or plain HTTP with the default TLS-identity requirement on, no substitution happens. That’s by design, since the host can’t verify where opaque traffic is really going. You can opt a secret into plain-HTTP injection, but it’s weaker and not recommended.
  • A few content shapes aren’t rewritten. Body injection is opt-in and has format, encoding, and size limits. Encoded bodies are forwarded unchanged; detected placeholders in unsupported body formats are blocked. See SecretInjection.
  • Real values live in host process memory. The host must access real values to inject them. Anyone who can read the host process’s memory is already on the trusted side of the boundary, and host compromise is out of scope for the model.

​
Where the values live

Secret bindings put placeholders in the guest environment. Raw values supplied through an SDK are also persisted in the host-side sandbox configuration; stopping the sandbox does not remove that copy. Host environment references avoid storing the value in that configuration. See Secrets for storage and rotation guidance.

​
See also

  • Secrets: binding secrets, placeholders, and allow lists
  • TLS inspection: what interception sees and what bypass makes opaque
  • Network defenses: the DNS pin and SNI checks the gates share