Skip to main content
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
NameTypeDescription
i_understand_the_riskboolMust be true to take effect

​
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
NameTypeDescription
hostimpl Into<String>Exact hostname (e.g. "api.openai.com")

​
allow_host_pattern()

fn allow_host_pattern(self, pattern: impl Into<String>) -> Self
Add a wildcard host pattern. The * matches any subdomain prefix. Parameters
NameTypeDescription
patternimpl Into<String>Wildcard pattern (e.g. "*.googleapis.com")

​
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
NameTypeDescription
varimpl Into<String>Environment variable name (e.g. "OPENAI_API_KEY")

​
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
NameTypeDescription
enabledboolDefault: true

​
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
NameTypeDescription
enabledboolDefault: false

​
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
NameTypeDescription
enabledboolDefault: true

​
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
NameTypeDescription
enabledboolDefault: false

​
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
NameTypeDescription
placeholderimpl Into<String>Custom placeholder string

​
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
NameTypeDescription
enabledboolDefault: true

​
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
NameTypeDescription
valueimpl Into<String>The actual credential or token

​
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
NameTypeDescription
env_varimpl Into<String>Environment variable name
valueimpl Into<String>Secret value
allowed_hostimpl Into<String>Allowed destination host

​
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.
ValueDescription
BlockSilently drop the request. The guest sees a connection reset. This is the default.
BlockAndLogDrop the request and emit a warning log on the host side.
BlockAndTerminateDrop the request, log an error, and shut down the entire sandbox.