Rust SDK Secrets reference

See Secrets for usage examples and security boundaries.

SecretBuilder

SecretBuilder::new()

fn new() -> SecretBuilder

Example

use microsandbox::sandbox::SecretBuilder;

let entry = SecretBuilder::new()
    .env("STRIPE_KEY")
    .value(stripe_key)
    .allow("api.stripe.com")
    .build();

Start building a secret with defaults: no env var, no value, no allowed hosts, the default SecretSubstitution (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.

Returns

SecretBuilder

A builder with default injection scopes.

Builder methods

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(), exactly one of value() or source(), and at least one allowed host are required; build() panics otherwise. Import path: microsandbox::sandbox::SecretBuilder. Adding any secret automatically enables TLS interception.

secret.env()

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.

Parameters

varimpl Into<String>

Environment variable name (non-empty, no = or NUL).

secret.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, but inline values are persisted verbatim in the durable sandbox configuration. Mutually exclusive with source(); prefer a source reference when available.

Parameters

valueimpl Into<String>

The actual credential or token.

secret.source()

fn source(self, source: SecretSource) -> Self

Resolve secret material from a host-side reference at spawn time. Exactly one of source() and value() must be set. The durable configuration stores only the reference, not the resolved plaintext.

use microsandbox::sandbox::{SecretBuilder, SecretSource};

let entry = SecretBuilder::new()
    .env("API_KEY")
    .source(SecretSource::Env { var: "API_KEY".into() })
    .allow("api.example.com")
    .build();

secret.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. Placeholders must be non-empty, at most 1024 bytes (MAX_SECRET_PLACEHOLDER_BYTES), and cannot contain NUL, CR, or LF.

Parameters

placeholderimpl Into<String>

Custom placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF.

secret.allow()

fn allow(self, host: impl AsRef<str>) -> Self

Example

.secret(|s| s
    .env("STRIPE_KEY")
    .value(stripe_key)
    .allow("api.stripe.com")
    .allow("files.stripe.com"))

Add an exact host or wildcard pattern allowed to receive the real secret value. A *.suffix pattern matches the suffix itself and its subdomains. 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.

Parameters

hostimpl AsRef<str>

Exact hostname or wildcard pattern, e.g. “api.example.com” or “*.example.com”. Parsed as a HostPattern.

secret.allow_any_host_dangerous()

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.

Parameters

i_understand_the_riskbool

Must be true to take effect.

secret.allow_placeholder_for()

fn allow_placeholder_for(self, host: impl AsRef<str>) -> Self

Allow an exact host, wildcard pattern, or * to receive the placeholder unchanged when it cannot be substituted. Repeated calls are additive. The old allow_passthrough_for() name remains available as a deprecated alias. This does not grant access to the real value: substitution still requires an allowed host and an enabled request location.

secret.violation_action()

fn violation_action(self, action: SecretViolationAction) -> Self

Override the sandbox-wide blocking action for this secret. With no override, the network’s secret_violation_action() applies; its default is SecretViolationAction::BlockAndLog. Passthrough is a separate per-secret host policy.

Example

use microsandbox::{Sandbox, SecretViolationAction};

let sb = Sandbox::builder("worker")
    .image("python")
    .secret(|s| s
        .env("API_KEY")
        .value(api_key)
        .allow("api.github.com")
        .allow_placeholder_for("api.anthropic.com")
        .substitute_in_body(true)
        .violation_action(SecretViolationAction::BlockAndTerminate))
    .secret_violation_action(SecretViolationAction::BlockAndLog)
    .create()
    .await?;

secret.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 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.

Parameters

enabledbool

Require verified TLS identity. Default: true.

secret.substitute_in_headers()

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

Control whether the placeholder is replaced anywhere in HTTP headers, including decoded and re-encoded Basic authentication credentials. This is the most common injection scope, covering Authorization: Bearer $MSB_... and similar patterns. Default: true.

Parameters

enabledbool

Substitute in headers. Default: true.

secret.substitute_in_query()

fn substitute_in_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.

Parameters

enabledbool

Substitute in query parameters. Default: false.

secret.substitute_in_body()

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

Control whether the placeholder is replaced in HTTP/1 request bodies. When enabled, 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.

Parameters

enabledbool

Substitute in request bodies. Default: false.

secret.build()

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>.

Returns

SecretEntry

The materialized secret entry.

Panics

Panics if env was not set, if neither or both of value and source were set, or if the allow list is empty. Use allow_any_host_dangerous(true) for an explicit any-host secret.

SandboxBuilder

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.

sandbox.secret_env()

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

Example

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(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).

Parameters

env_varimpl Into<String>

Environment variable name (non-empty, no = or NUL).

valueimpl Into<String>

Secret value.

allowed_hostimpl Into<String>

Allowed destination host (exact match).

sandbox.secret_entry()

fn secret_entry(self, entry: SecretEntry) -> Self

Example

use microsandbox::sandbox::SecretBuilder;

let entry = SecretBuilder::new()
    .env("STRIPE_KEY")
    .value(stripe_key)
    .allow("api.stripe.com")
    .build();

let sb = Sandbox::builder("billing")
    .image("python")
    .secret_entry(entry)
    .create()
    .await?;

Add a pre-built SecretEntry directly. Use this escape hatch when you already have a materialized entry. For example, the entry can be 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.

Parameters

entrySecretEntry

A materialized secret entry.

HostPattern

Used by SecretEntry · allow() · allow_placeholder_for()

Destination host pattern used by secret policies.

Variant	Builder methods	Matches
`Exact(String)`	`allow("api.example.com")`, `allow_placeholder_for("api.example.com")`	Exact hostname, ASCII case-insensitive
`Wildcard(String)`	`allow(".example.com")`, `allow_placeholder_for(".example.com")`	The suffix and its subdomains
`Any`	`allow_any_host_dangerous(true)`, `allow_placeholder_for("*")`	Every host

Use the explicit dangerous opt-in for any-host substitution; allow("*") panics.

pattern.matches()

fn matches(&self, hostname: &str) -> bool

Whether hostname matches this pattern (ASCII case-insensitive).

SecretEntry

returned by SecretBuilder::build() · used by secret_entry()

Materialized secret configuration produced by SecretBuilder.

Field	Type	Description
`env_var`	`String`	Environment variable holding the placeholder. Non-empty, no `=` or NUL.
`value`	`Zeroizing<String>`	The real secret value; never enters the guest. Inline values are persisted; source-backed durable entries carry an empty value until host-side resolution. Debug output redacts the value.
`source`	`Option<SecretSource>`	Host-side reference resolved at spawn time. Prefer the builder’s `source()` method rather than populating a resolved entry manually.
`placeholder`	`String`	What the guest sees. Non-empty, at most 1024 bytes, no NUL/CR/LF.
`allowed_hosts`	`Vec<HostPattern>`	Hosts allowed to receive the real value.
`substitution`	`SecretSubstitution`	Where in the request the value may be substituted.
`violation_action`	`Option<SecretViolationAction>`	Per-secret violation override. `None` falls back to the sandbox-wide action.
`passthrough_hosts`	`Vec<HostPattern>`	Destinations allowed to receive the unchanged placeholder. Empty by default.
`require_tls_identity`	`bool`	Require verified TLS identity before substituting. Default: `true`.

entry.validate()

fn validate(&self, secret_index: usize) -> Result<(), SecretConfigError>

Validate this entry’s env var, allowed hosts, enabled substitution locations, and placeholder.

Types

SecretSubstitution

Used by SecretEntry.substitution

Request locations enabled through the substitute_in_* methods. At least one must remain enabled. On credential-allowed hosts that pass the secret’s identity checks, disabled locations forward the placeholder unchanged. Other destinations must match the secret’s passthrough list or follow the violation action.

Field	Type	Default	Description
`headers`	`bool`	`true`	Substitute in headers, including Basic authentication.
`query`	`bool`	`false`	Substitute in the URL query string.
`body`	`bool`	`false`	Substitute in supported HTTP/1 bodies.

When body substitution is enabled, fixed-length HTTP/1 bodies up to 16 MiB update Content-Length; larger fixed-length bodies are blocked. Chunked HTTP/1 bodies are decoded and re-encoded with fresh chunk sizes. Encoded bodies pass through unchanged. HTTP/2 DATA-frame body substitution is unsupported, and matching body placeholders are blocked.

SecretViolationAction

Used by SecretEntry · violation_action() · NetworkBuilder::secret_violation_action()

Blocking action when a placeholder cannot be substituted or passed through. A per-secret action overrides the network default. Passthrough is a host policy, not an enum variant.

Variant	Description
`Block`	Block the request without logging.
`BlockAndLog`	Block and emit a warning on the host. This is the default.
`BlockAndTerminate`	Block, log an error, and shut down the sandbox.

SecretConfigError

returned by SecretEntry::validate()

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.
`MissingSubstitutionLocation`	Headers, query, and body substitution were all disabled.
`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.

Getting Started

SDKs

CLI

Secrets

SecretBuilder

SecretBuilder::new()

secret.env()

secret.value()

secret.source()

secret.placeholder()

secret.allow()

secret.allow_any_host_dangerous()

secret.allow_placeholder_for()

secret.violation_action()

secret.require_tls_identity()

secret.substitute_in_headers()

secret.substitute_in_query()

secret.substitute_in_body()

secret.build()

SandboxBuilder

sandbox.secret_env()

sandbox.secret_entry()

HostPattern

pattern.matches()

SecretEntry

entry.validate()

Types

SecretSubstitution

SecretViolationAction

SecretConfigError

​SecretBuilder

​SecretBuilder::new()

​secret.env()

​secret.value()

​secret.source()

​secret.placeholder()

​secret.allow()

​secret.allow_any_host_dangerous()

​secret.allow_placeholder_for()

​secret.violation_action()

​secret.require_tls_identity()

​secret.substitute_in_headers()

​secret.substitute_in_query()

​secret.substitute_in_body()

​secret.build()

​SandboxBuilder

​sandbox.secret_env()

​sandbox.secret_entry()

​HostPattern

​pattern.matches()

​SecretEntry

​entry.validate()

​Types

​SecretSubstitution

​SecretViolationAction

​SecretConfigError

SecretBuilder

SecretBuilder::new()

secret.env()

secret.value()

secret.source()

secret.placeholder()

secret.allow()

secret.allow_any_host_dangerous()

secret.allow_placeholder_for()

secret.violation_action()

secret.require_tls_identity()

secret.substitute_in_headers()

secret.substitute_in_query()

secret.substitute_in_body()

secret.build()

SandboxBuilder

sandbox.secret_env()

sandbox.secret_entry()

HostPattern

pattern.matches()

SecretEntry

entry.validate()

Types

SecretSubstitution

SecretViolationAction

SecretConfigError