Secrets

See Secrets for how placeholder substitution works and usage examples.

SecretBuilder

Builder for configuring a secret's placeholder, allowed hosts, and injection scopes. Obtained through SandboxBuilder::secret(|s| s...). Each secret maps an environment variable to a real value that is only revealed when traffic goes to an allowed host via the TLS proxy.

allow_any_host_dangerous()

fn allow_any_host_dangerous(self, i_understand_the_risk: bool) -> Self

Allow substitution on any host. This means any server the guest connects to will receive the real secret - effectively disabling host-based protection. Only use this when the secret is not sensitive or the sandbox network is fully locked down.

Parameters

allow_host()

fn allow_host(self, host: impl Into<String>) -> Self

Add a host that is allowed to receive the real secret value. The TLS proxy matches this against the SNI (Server Name Indication) in the TLS ClientHello. Can be called multiple times to allow multiple hosts.

Parameters

allow_host_pattern()

fn allow_host_pattern(self, pattern: impl Into<String>) -> Self

Add a wildcard host pattern. The * matches any subdomain prefix.

Parameters

env()

fn env(self, var: impl Into<String>) -> Self

Set the environment variable name that will hold the placeholder inside the guest. The guest sees $MSB_<var> (or a custom placeholder) - never the real value. Required.

Parameters

inject_basic_auth()

fn inject_basic_auth(self, enabled: bool) -> Self

Control whether the placeholder is replaced specifically in Authorization header lines. When inject_headers is true, this has no additional effect since all headers are already covered.

Parameters

inject_body()

fn inject_body(self, enabled: bool) -> Self

Control whether the placeholder is replaced in the HTTP request body. When enabled, the TLS proxy also updates the Content-Length header to match the new body size after substitution.

Parameters

inject_headers()

fn inject_headers(self, enabled: bool) -> Self

Control whether the placeholder is replaced anywhere in HTTP headers. This is the most common injection scope - covers Authorization: Bearer $MSB_... and similar patterns.

Parameters

inject_query()

fn inject_query(self, enabled: bool) -> Self

Control whether the placeholder is replaced in the URL query string (the ?key=value portion of the request line).

Parameters

placeholder()

fn placeholder(self, placeholder: impl Into<String>) -> Self

Override the auto-generated placeholder string. By default, microsandbox generates $MSB_<env_var>. Use this when you need a specific format or when the placeholder must match a particular byte length.

Parameters

require_tls_identity()

fn require_tls_identity(self, enabled: bool) -> Self

When true, the secret is only substituted on TLS-intercepted connections where the proxy has verified it is performing MITM. When false, substitution also happens on non-intercepted (bypass) connections. Disable only if you know the traffic is safe.

Parameters

value()

fn value(self, value: impl Into<String>) -> Self

Set the real secret value. This is the string that replaces the placeholder when a request reaches an allowed host. It never enters the guest VM. Required.

Parameters

Shorthand

secret_env()

fn secret_env(self, env_var: impl Into<String>, value: impl Into<String>, allowed_host: impl Into<String>) -> Self

Convenience method on SandboxBuilder. Equivalent to .secret(|s| s.env(env_var).value(value).allow_host(allowed_host)). Uses default injection scopes (headers enabled, body disabled).

Parameters

Types

ViolationAction

Configured via NetworkBuilder::on_secret_violation(). Determines what happens when the guest sends a request containing a secret placeholder to a host that is not in the secret's allow list.