docs/sdk/rust/secrets.mdx
Configure secret substitution for outbound requests. See Secrets for usage and security concepts.
fn new() -> SecretBuilder
use microsandbox::sandbox::SecretBuilder;
let entry = SecretBuilder::new()
.env("STRIPE_KEY")
.value(stripe_key)
.allow_host("api.stripe.com")
.build();
Start building a secret with defaults: no env var, no value, no allowed hosts, the default SecretInjection (headers and Basic Auth on, query and body off), no per-secret violation override, and require_tls_identity = true. You rarely call this yourself: SandboxBuilder::secret(|s| s...) hands you a fresh builder and calls build() for you. SecretBuilder::default() is equivalent.
Builder for one secret's placeholder, allowed hosts, and injection scopes. Obtained through SandboxBuilder::secret(|s| s...) or SecretBuilder::new(); each secret maps an environment variable to a real value that is only revealed when traffic reaches an allowed host through the TLS proxy. Every setter returns Self, so calls chain. env(), value(), and at least one allowed host are required; build() panics otherwise.
Import path: microsandbox::sandbox::SecretBuilder. Adding any secret automatically enables TLS interception.
fn env(self, var: impl Into<String>) -> Self
Set the environment variable name that holds the placeholder inside the guest. The guest sees $MSB_<var> (or a custom placeholder), never the real value. Names must be non-empty and cannot contain = or NUL; shell-identifier syntax is not required since Linux only requires a NAME=value shape. Required.
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>value</code><span className="msb-type">impl Into<String></span></div> <div className="msb-param-desc">The actual credential or token.</div> </div> </div>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. Placeholders must be non-empty, at most 1024 bytes (MAX_SECRET_PLACEHOLDER_BYTES), and cannot contain NUL, CR, or LF.
fn allow_host(self, host: impl Into<String>) -> Self
.secret(|s| s
.env("STRIPE_KEY")
.value(stripe_key)
.allow_host("api.stripe.com")
.allow_host("files.stripe.com"))
Add an exact host allowed to receive the real secret value. The proxy checks the host against the connection's verified TLS identity and observed DNS history. Can be called multiple times to allow several hosts. At least one allowed host (exact, pattern, or any) is required.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>host</code><span className="msb-type">impl Into<String></span></div> <div className="msb-param-desc">Exact hostname, e.g. <code>"api.example.com"</code>. Becomes a <a className="msb-type" href="#hostpattern">HostPattern::Exact</a>.</div> </div> </div>fn allow_host_pattern(self, pattern: impl Into<String>) -> Self
Add a wildcard host pattern. A *.suffix pattern matches the suffix itself and any single- or multi-label subdomain of it.
fn allow_any_host_dangerous(self, i_understand_the_risk: bool) -> Self
Allow substitution on any host. Every server the guest connects to can then receive the real secret, which effectively disables host-based protection. The call is a no-op unless i_understand_the_risk is true. Only use this when the secret is not sensitive or the sandbox network is fully locked down. Adds a HostPattern::Any to the allow list, the one pattern that skips DNS and TLS-identity pinning.
fn on_violation(
self,
f: impl FnOnce(ViolationActionBuilder) -> ViolationActionBuilder,
) -> Self
.secret(|s| s
.env("API_KEY")
.value(api_key)
.allow_host("api.github.com")
.on_violation(|v| v
.block_and_log()
.passthrough_host("api.anthropic.com")))
Configure violation behavior for this secret. Overrides the sandbox-wide secret violation policy and can let selected hosts receive the placeholder unchanged. See ViolationActionBuilder for the full set of block_* and passthrough_* methods.
Passthrough hosts do not receive the real secret value; substitution still only happens for hosts configured with allow_host() or allow_host_pattern(). When a per-secret passthrough policy does not match the request host, microsandbox falls back to the sandbox-wide secret violation action.
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 and the SNI matches an allowed host. Bypassed TLS is opaque and never receives substitution. Disable only when you know the traffic path is safe and explicitly supports non-TLS substitution. Default: true.
fn inject_headers(self, enabled: bool) -> Self
Control whether the placeholder is replaced anywhere in HTTP headers. This is the most common injection scope, covering Authorization: Bearer $MSB_... and similar patterns. Default: true.
fn inject_basic_auth(self, enabled: bool) -> Self
Control whether Authorization: Basic <base64> credentials are decoded, substituted in the decoded user:password, then re-encoded. Orthogonal to inject_headers: this flag handles the encoded-credentials case for the Basic scheme; inject_headers handles literal substitution in any header line, including non-Basic Authorization schemes (Bearer, Digest). Default: true.
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). Default: false.
fn inject_body(self, enabled: bool) -> Self
Control whether the placeholder is replaced in HTTP/1 request bodies. Fixed-length bodies up to 16 MiB are substituted and their Content-Length updated; larger fixed-length bodies are blocked. Chunked bodies are decoded and re-encoded with fresh chunk sizes. Encoded bodies pass through unchanged. HTTP/2 DATA-frame substitution is not supported, so matching body placeholders are blocked rather than leaked. Default: false.
fn build(self) -> SecretEntry
Materialize the SecretEntry. Called for you by SandboxBuilder::secret, so you rarely call it directly. If placeholder was not set, it defaults to $MSB_<env_var>.
Two convenience methods on SandboxBuilder for the common cases, so you don't have to spell out a SecretBuilder closure. Both automatically enable TLS interception.
fn secret_env(
self,
env_var: impl Into<String>,
value: impl Into<String>,
allowed_host: impl Into<String>,
) -> Self
let sb = Sandbox::builder("agent")
.image("python")
.secret_env("OPENAI_API_KEY", api_key, "api.openai.com")
.create()
.await?;
Equivalent to .secret(|s| s.env(env_var).value(value).allow_host(allowed_host)). The placeholder is auto-generated as $MSB_<env_var> and the default injection scopes apply (headers and Basic Auth enabled, query and body disabled).
fn secret_entry(self, entry: SecretEntry) -> Self
use microsandbox::sandbox::SecretBuilder;
let entry = SecretBuilder::new()
.env("STRIPE_KEY")
.value(stripe_key)
.allow_host("api.stripe.com")
.build();
let sb = Sandbox::builder("billing")
.image("python")
.secret_entry(entry)
.create()
.await?;
Add a pre-built SecretEntry directly. This is the escape hatch when you already have a materialized entry, for example one produced by SecretBuilder::build(), loaded from configuration, or constructed by hand for full control over the serialized shape. Both secret() and secret_env() funnel through this method. The entry is validated when the sandbox is built; an invalid one surfaces as a config error rather than a panic.
Destination host pattern used by secret policies.
| Variant | Builder methods | Matches |
|---|---|---|
Exact(String) | allow_host(), passthrough_host() | That exact host, ASCII case-insensitive |
Wildcard(String) | allow_host_pattern(), passthrough_host_pattern() | The suffix and its subdomains, e.g. *.example.com |
Any | allow_any_host_dangerous(true), passthrough_all_hosts(true) | Every host |
fn matches(&self, hostname: &str) -> bool
Whether hostname matches this pattern (ASCII case-insensitive).
Materialized secret configuration produced by SecretBuilder.
String
Environment variable holding the placeholder. Non-empty, no = or NUL.
String
The real secret value (never enters the guest).
String
What the guest sees. Non-empty, at most 1024 bytes, no NUL/CR/LF.
Vec<HostPattern>
Hosts allowed to receive the real value.
Where in the request the value may be substituted.
Option<ViolationAction>
Per-secret violation override. None falls back to the sandbox-wide action.
bool
Require verified TLS identity before substituting. Default: true.
fn validate(&self, secret_index: usize) -> Result<(), SecretConfigError>
Validate this entry's env var, allowed hosts, and placeholder.
Which parts of an outbound HTTP request the placeholder may be substituted in. Set through the inject_* methods on SecretBuilder.
| Field | Type | Default | Description |
|---|---|---|---|
headers | bool | true | Substitute anywhere in HTTP headers. |
basic_auth | bool | true | Substitute inside decoded Authorization: Basic credentials. |
query_params | bool | false | Substitute in the URL query string. |
body | bool | false | Substitute in HTTP/1 request bodies (see inject_body() for limits). |
What happens when the guest sends a request containing a secret placeholder to a host that is not in the secret's substitution allow list. Built through ViolationActionBuilder, set globally via NetworkBuilder::on_secret_violation() or per secret via SecretBuilder::on_violation(). Also documented on the Networking page.
| Variant | Description |
|---|---|
Block | Silently drop the request. The guest sees a connection reset. |
BlockAndLog | Drop the request and emit a warning log on the host side. This is the default. |
BlockAndTerminate | Drop the request, log an error, and shut down the entire sandbox. |
Passthrough(Vec<HostPattern>) | Forward matching hosts with the placeholder unchanged. Non-matching hosts fall back to the default secret violation action. |
Why a secret entry failed validation. Each variant carries the offending secret_index. The placeholder ceiling is the public constant MAX_SECRET_PLACEHOLDER_BYTES = 1024.
| Variant | Description |
|---|---|
EmptyEnvVar | The environment variable name is empty. |
EnvVarContainsEquals | The environment variable name contains =. |
EnvVarContainsNul | The environment variable name contains NUL. |
MissingAllowedHosts | No allowed hosts were configured. |
EmptyPlaceholder | The placeholder is empty. |
PlaceholderTooLong | The placeholder exceeds MAX_SECRET_PLACEHOLDER_BYTES (carries actual_bytes, max_bytes). |
PlaceholderContainsNul | The placeholder contains NUL. |
PlaceholderContainsLineBreak | The placeholder contains CR or LF. |