SecretBuilder
SecretBuilder::new()
Example
Example
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
A builder with default injection scopes.
Builder methods
Builder for one secret’s placeholder, allowed hosts, and injection scopes. Obtained throughSandboxBuilder::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()
$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()
source(); prefer a source reference when available.
Parameters
valueimpl Into<String>The actual credential or token.
secret.source()
source() and value() must be set. The durable configuration stores only the reference, not the resolved plaintext.
secret.placeholder()
$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()
Example
Example
*.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()
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_riskboolMust be
true to take effect.secret.allow_placeholder_for()
* 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()
secret_violation_action() applies; its default is SecretViolationAction::BlockAndLog. Passthrough is a separate per-secret host policy.
Example
Example
secret.require_tls_identity()
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
enabledboolRequire verified TLS identity. Default:
true.secret.substitute_in_headers()
Authorization: Bearer $MSB_... and similar patterns. Default: true.
Parameters
enabledboolSubstitute in headers. Default:
true.secret.substitute_in_header_fields()
Authorization. A placeholder found in any other header field is treated as a disabled location: on a verified allowed destination it is forwarded unchanged, while other destinations follow the violation policy. Passing an empty list restores the default of substituting in every header field. A non-empty list with header substitution disabled is rejected. Names must be valid HTTP field names.
Restricting this list matters for confidentiality, not just correctness: with every header substitutable, an untrusted guest can place the placeholder in a header the upstream host reflects back in its response and read the real secret from that response. Allow only the intended credential header.
Parameters
fieldsIntoIterator<Item = impl Into<String>>Header field names allowed to receive the substitution. Empty restores all headers.
secret.substitute_in_query()
?key=value portion of the request line). Default: false.
Parameters
enabledboolSubstitute in query parameters. Default:
false.secret.substitute_in_body()
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
enabledboolSubstitute in request bodies. Default:
false.secret.build()
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
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 onSandboxBuilder for the common cases, so you don’t have to spell out a SecretBuilder closure. Both automatically enable TLS interception.
sandbox.secret_env()
Example
Example
.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()
Example
Example
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
entrySecretEntryA materialized secret entry.
HostPattern
Used by SecretEntry · allow() · allow_placeholder_for()
Destination host pattern used by secret policies.
Use the explicit dangerous opt-in for any-host substitution;
allow("*") panics.
pattern.matches()
hostname matches this pattern (ASCII case-insensitive).
SecretEntry
returned by SecretBuilder::build() · used by secret_entry()
Materialized secret configuration produced bySecretBuilder.
entry.env_var
String
Environment variable holding the placeholder. Non-empty, no = or NUL.
entry.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.
entry.source
Option<SecretSource>
Host-side reference resolved at spawn time. Prefer the builder’s source() method rather than populating a resolved entry manually.
entry.placeholder
String
What the guest sees. Non-empty, at most 1024 bytes, no NUL/CR/LF.
entry.allowed_hosts
Vec<HostPattern>
Hosts allowed to receive the real value.
entry.substitution
SecretSubstitution
Where in the request the value may be substituted.
entry.violation_action
Option<SecretViolationAction>
Per-secret violation override. None falls back to the sandbox-wide action.
entry.passthrough_hosts
Vec<HostPattern>
Destinations allowed to receive the unchanged placeholder. Empty by default.
entry.require_tls_identity
bool
Require verified TLS identity before substituting. Default: true.
entry.validate()
Types
SecretSubstitution
Used by SecretEntry.substitution
Request locations enabled through thesubstitute_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.
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.SecretConfigError
returned by SecretEntry::validate()
Why a secret entry failed validation. Each variant carries the offendingsecret_index. The placeholder ceiling is the public constant MAX_SECRET_PLACEHOLDER_BYTES = 1024.