Secrets

Rust SDK - Secret injection API reference

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

Name	Type	Description
i_understand_the_risk	bool	Must 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

Name	Type	Description
host	impl 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

Name	Type	Description
pattern	impl 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

Name	Type	Description
var	impl 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

Name	Type	Description
enabled	bool	Default: 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

Name	Type	Description
enabled	bool	Default: 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

Name	Type	Description
enabled	bool	Default: 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

Name	Type	Description
enabled	bool	Default: 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

Name	Type	Description
placeholder	impl 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

Name	Type	Description
enabled	bool	Default: 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

Name	Type	Description
value	impl 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

Name	Type	Description
env_var	impl Into<String>	Environment variable name
value	impl Into<String>	Secret value
allowed_host	impl 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.

Value	Description
Block	Silently drop the request. The guest sees a connection reset. This is the default.
BlockAndLog	Drop the request and emit a warning log on the host side.
BlockAndTerminate	Drop the request, log an error, and shut down the entire sandbox.