Rust SDK Networking reference

See Networking for network policies, DNS, TLS, and port publishing.

NetworkPolicy

NetworkPolicy::builder()

fn builder() -> NetworkPolicyBuilder

Example

use microsandbox::NetworkPolicy;

let policy = NetworkPolicy::builder()
    .default_deny()
    .egress(|e| e.tcp().port(443).allow_public().allow_private())
    .build()?;

Create a NetworkPolicyBuilder to configure rules and per-direction defaults. The first matching rule wins in each direction. build() validates string inputs (.ip, .cidr, .domain, .domain_suffix) and returns a BuildError for invalid input.

Returns

NetworkPolicyBuilder

Empty builder.

NetworkPolicy::none()

fn none() -> NetworkPolicy

No network access: deny everything in both directions, no rules. This is the policy set by SandboxBuilder::disable_network().

NetworkPolicy::allow_all()

fn allow_all() -> NetworkPolicy

Unrestricted network access: allow everything in both directions, no rules.

NetworkPolicy::from_profiles()

fn from_profiles<I: IntoIterator<Item = NetworkProfile>>(profiles: I) -> NetworkPolicy

Build a deny-by-default policy from composable NetworkProfile values. Duplicate profiles are ignored, the generated rules use canonical Public, Private, Host order, and every non-empty profile set receives exactly one narrow gateway DNS rule. An empty profile set permits no egress and adds no DNS. Ingress defaults to allow, preserving published-port behavior.

Example

use microsandbox::{NetworkPolicy, NetworkProfile};

let policy = NetworkPolicy::from_profiles([
    NetworkProfile::Public,
    NetworkProfile::Private,
]);

Instance methods

These methods consume self and return a modified policy, so they chain off a profile or a built policy. Each prepends its rules, so a later deny outranks a catch-all allow like allow public under first-match-wins. All return Result<NetworkPolicy, DomainNameError> because the names are parsed eagerly.

policy.allow_domain()

fn allow_domain<S: AsRef<str>>(self, name: S) -> Result<NetworkPolicy, DomainNameError>

Example

let policy = NetworkPolicy::default().allow_domain("api.openai.com")?;

Prepend a single allow-Domain egress rule. Single-name sugar over allow_domains().

policy.deny_domain()

fn deny_domain<S: AsRef<str>>(self, name: S) -> Result<NetworkPolicy, DomainNameError>

Prepend a single deny-Domain egress rule. Single-name sugar over deny_domains().

policy.allow_domains()

fn allow_domains<I, S>(self, names: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Example

let policy = NetworkPolicy::default()
    .allow_domains(["pypi.org", "files.pythonhosted.org"])?;

Prepend one allow-Domain egress rule per name.

Parameters

namesIntoIterator<Item = AsRef<str>>

Exact domain names.

policy.deny_domains()

fn deny_domains<I, S>(self, names: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Example

let policy = NetworkPolicy::allow_all()
    .deny_domains(["evil.com", "tracker.example"])?;

Prepend one deny-Domain egress rule per name. Prepending lets the denies outrank catch-all allows.

policy.allow_domain_suffix()

fn allow_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<NetworkPolicy, DomainNameError>

Prepend a single allow-DomainSuffix egress rule. Single-suffix sugar over allow_domain_suffixes().

policy.deny_domain_suffix()

fn deny_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<NetworkPolicy, DomainNameError>

Prepend a single deny-DomainSuffix egress rule. Single-suffix sugar over deny_domain_suffixes().

policy.allow_domain_suffixes()

fn allow_domain_suffixes<I, S>(self, suffixes: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Prepend one allow-DomainSuffix egress rule per suffix. Suffixes match the apex domain and every subdomain (label-aligned).

policy.deny_domain_suffixes()

fn deny_domain_suffixes<I, S>(self, suffixes: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Example

let policy = NetworkPolicy::allow_all()
    .deny_domain_suffixes([".ads.example", ".doubleclick.net"])?;

Prepend one deny-DomainSuffix egress rule per suffix.

NetworkPolicyBuilder

Fluent builder for NetworkPolicy.

policy.default_deny()

fn default_deny(self) -> Self

Set both default_egress and default_ingress to Deny.

policy.default_allow()

fn default_allow(self) -> Self

Set both default_egress and default_ingress to Allow.

policy.default_egress()

fn default_egress(self, action: Action) -> Self

Set the action when no egress rule matches.

Parameters

actionAction

Default action for egress.

policy.default_ingress()

fn default_ingress(self, action: Action) -> Self

Set the action when no ingress rule matches.

Parameters

actionAction

Default action for ingress.

policy.egress()

fn egress<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder

Example

NetworkPolicy::builder()
    .default_deny()
    .egress(|e| e.tcp().port(443).allow_public())
    .build()?;

Sugar for rule() with direction pre-set to Egress.

policy.ingress()

fn ingress<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder

Sugar for rule() with direction pre-set to Ingress.

policy.any()

fn any<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder

Sugar for rule() with direction pre-set to Any. Rules committed inside apply in both directions.

policy.rule()

fn rule<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder

Example

NetworkPolicy::builder()
    .rule(|r| r.egress().tcp().port(443).allow().domain("api.example.com"))
    .build()?;

Open a multi-rule batch closure. Direction must be set inside via .egress(), .ingress(), or .any() before any rule-adder, otherwise build() returns BuildError::DirectionNotSet.

policy.build()

fn build(self) -> Result<NetworkPolicy, BuildError>

Consume the builder and produce a NetworkPolicy. Lazy-parses every .ip() / .cidr() / .domain() / .domain_suffix() input and validates the direction-set and ICMP-egress-only invariants. It also emits a tracing::warn! for each shadowed rule pair, meaning a rule fully covered by an earlier one in the same direction. The shadow check covers only Ip / Cidr / Group destinations. Builds still succeed when a shadow is detected. Returns the first BuildError encountered.

Returns

NetworkPolicy

Validated policy.

RuleBuilder

Builder for one policy-rule batch.

rule.egress()

fn egress(&mut self) -> &mut Self

Set direction to Egress for subsequent rule-adders. Last-write-wins.

rule.ingress()

fn ingress(&mut self) -> &mut Self

Set direction to Ingress for subsequent rule-adders. Last-write-wins.

rule.any()

fn any(&mut self) -> &mut Self

Set direction to Any for subsequent rule-adders. Rules committed after this apply in both directions. Last-write-wins.

rule.tcp()

fn tcp(&mut self) -> &mut Self

Add Tcp to the protocols set.

rule.udp()

fn udp(&mut self) -> &mut Self

Add Udp to the protocols set.

rule.icmpv4()

fn icmpv4(&mut self) -> &mut Self

Add Icmpv4 to the protocols set. Egress-only: an ICMP protocol on an Ingress or Any rule fails build with BuildError::IngressDoesNotSupportIcmp.

rule.icmpv6()

fn icmpv6(&mut self) -> &mut Self

Add Icmpv6 to the protocols set. Egress-only; same rule as icmpv4().

rule.port()

fn port(&mut self, port: u16) -> &mut Self

Add a single port to the ports set. Always guest-side (egress destination port / ingress listening port).

Parameters

portu16

Port number.

rule.port_range()

fn port_range(&mut self, lo: u16, hi: u16) -> &mut Self

Add an inclusive port range.

Parameters

lou16

Lower bound (inclusive).

hiu16

Upper bound (inclusive). lo > hi records BuildError::InvalidPortRange.

rule.ports()

fn ports<I: IntoIterator<Item = u16>>(&mut self, ports: I) -> &mut Self

Add multiple single ports. Equivalent to calling port() once per element.

rule.allow_public()

fn allow_public(&mut self) -> &mut Self

Commit an allow rule for the Public group: every IP not in another named category. A matching deny_public() exists for each allow_* group adder below.

rule.allow_private()

fn allow_private(&mut self) -> &mut Self

Allow the Private group (RFC1918 + ULA + CGN).

rule.allow_loopback()

fn allow_loopback(&mut self) -> &mut Self

Allow the Loopback group (127.0.0.0/8, ::1): the guest’s own loopback, not the host. To reach a service on the host’s localhost use allow_host() instead. See the loopback-vs-host watch-out.

rule.allow_link_local()

fn allow_link_local(&mut self) -> &mut Self

Allow the LinkLocal group (169.254.0.0/16, fe80::/10). Excludes the metadata IP 169.254.169.254.

rule.allow_meta()

fn allow_meta(&mut self) -> &mut Self

Allow the Metadata group (169.254.169.254). Dangerous on cloud hosts: exposes IAM credentials.

rule.allow_multicast()

fn allow_multicast(&mut self) -> &mut Self

Allow the Multicast group (224.0.0.0/4, ff00::/8).

rule.allow_host()

fn allow_host(&mut self) -> &mut Self

Allow the Host group: per-sandbox gateway IPs that back host.microsandbox.internal. This is the right shortcut for “let the sandbox reach my host’s localhost”, not allow_loopback().

rule.deny_public()

fn deny_public(&mut self) -> &mut Self

Deny the Public group. Per-group deny_* adders mirror the allow_* set: deny_private(), deny_loopback(), deny_link_local(), deny_meta(), deny_multicast(), and deny_host().

rule.allow_local()

fn allow_local(&mut self) -> &mut Self

Commit three allow rules atomically: Loopback + LinkLocal + Host. Each uses the closure’s current state. Metadata is intentionally not included; opt in via allow_meta() separately.

rule.deny_local()

fn deny_local(&mut self) -> &mut Self

Commit three deny rules atomically: Loopback + LinkLocal + Host. Metadata is intentionally not included.

rule.allow_domains()

fn allow_domains<I, S>(&mut self, names: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>

Example

NetworkPolicy::builder()
    .default_allow()
    .egress(|e| e
        .deny_domains(["evil.com", "tracker.example"])
        .deny_domain_suffixes([".ads.example", ".doubleclick.net"]))
    .build()?;

Add one allow-Domain rule per name, inheriting the closure’s current direction / protocol / port state. Lazy-parse: invalid names surface as BuildError::InvalidDomain from build().

rule.deny_domains()

fn deny_domains<I, S>(&mut self, names: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>

Add one deny-Domain rule per name.

rule.allow_domain_suffixes()

fn allow_domain_suffixes<I, S>(&mut self, suffixes: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>

Add one allow-DomainSuffix rule per suffix.

rule.deny_domain_suffixes()

fn deny_domain_suffixes<I, S>(&mut self, suffixes: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>

Add one deny-DomainSuffix rule per suffix.

rule.allow()

fn allow(&mut self) -> RuleDestinationBuilder<'_>

Example

NetworkPolicy::builder()
    .egress(|e| e.tcp().port(443).allow().domain("api.example.com"))
    .any(|a| a.deny().cidr("198.51.100.0/24"))
    .build()?;

Begin an explicit-destination rule with action Allow. The returned RuleDestinationBuilder requires exactly one destination call to commit; dropping it without one adds no rule.

rule.deny()

fn deny(&mut self) -> RuleDestinationBuilder<'_>

Begin an explicit-destination rule with action Deny.

RuleDestinationBuilder

Builder for a rule destination.

destination.ip()

fn ip(self, ip: impl Into<String>) -> &'a mut RuleBuilder

Commit with Destination::Cidr of the IP as /32 (v4) or /128 (v6). The string is parsed at build(); invalid values surface as BuildError::InvalidIp.

destination.cidr()

fn cidr(self, cidr: impl Into<String>) -> &'a mut RuleBuilder

Commit with Destination::Cidr. Invalid values surface as BuildError::InvalidCidr.

destination.domain()

fn domain(self, domain: impl Into<String>) -> &'a mut RuleBuilder

Commit with Destination::Domain. Matches only when a cached hostname for the remote IP equals this name (after canonicalization).

destination.domain_suffix()

fn domain_suffix(self, suffix: impl Into<String>) -> &'a mut RuleBuilder

Commit with Destination::DomainSuffix. Matches the apex domain itself and any subdomain. A single-label suffix (e.g. com) is rejected at build as BuildError::InvalidDomain.

destination.group()

fn group(self, group: DestinationGroup) -> &'a mut RuleBuilder

Commit with Destination::Group for callers who already hold a DestinationGroup value.

destination.any()

fn any(self) -> &'a mut RuleBuilder

Commit with Destination::Any: matches every remote.

NetworkBuilder

Builder for the sandbox’s network stack, used in SandboxBuilder::network(|n| n...). Every setter returns Self, so calls chain. Errors accumulated by nested builders cascade up: the outermost SandboxBuilder::build() surfaces them as MicrosandboxError::NetworkBuilder(BuildError).

network.policy()

fn policy(self, policy: NetworkPolicy) -> Self

Example

.network(|n| n.policy(NetworkPolicy::builder().default_deny().build()?))

Set the network access policy. Pass a profile-composed or builder-constructed NetworkPolicy.

Parameters

policyNetworkPolicy

Access policy.

network.port()

fn port(self, host_port: u16, guest_port: u16) -> Self

Publish a TCP port from the sandbox to the host. The default host bind address is 127.0.0.1. Equivalent to SandboxBuilder::port().

Parameters

host_portu16

Port on the host.

guest_portu16

Port inside the sandbox.

network.port_udp()

fn port_udp(self, host_port: u16, guest_port: u16) -> Self

Publish a UDP port. The default host bind address is 127.0.0.1.

network.port_bind()

fn port_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self

Publish a TCP port on a specific host bind address, such as 0.0.0.0.

Parameters

host_bindIpAddr

Host bind address.

host_portu16

Port on the host.

guest_portu16

Port inside the sandbox.

network.port_udp_bind()

fn port_udp_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self

Publish a UDP port on a specific host bind address.

network.dns()

fn dns(self, f: impl FnOnce(DnsBuilder) -> DnsBuilder) -> Self

Example

use microsandbox_network::dns::Nameserver;

.network(|n| n
    .dns(|d| d
        .nameservers(["1.1.1.1".parse::<Nameserver>()?])
        .query_timeout_ms(3000)))

Configure DNS interception. See DnsBuilder.

network.tls()

fn tls(self, f: impl FnOnce(TlsBuilder) -> TlsBuilder) -> Self

Configure TLS interception. See TlsBuilder.

network.trust_host_cas()

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

Whether to ship the host’s trusted root CAs into the guest at boot. Default: false. Opt in when egress HTTPS inside the sandbox needs to work behind corporate MITM proxies (Cloudflare Warp Zero Trust, Zscaler, Netskope, etc.). Those proxies install a gateway CA on the host that’s unknown to the guest’s stock Mozilla bundle.

network.http()

fn http(self, configure: impl FnOnce(HttpBuilder) -> HttpBuilder) -> Self

// Within the callback:
fn deny_response(self, enabled: bool) -> Self
fn deny_message(self, message: impl Into<String>) -> Self

Denial responses are disabled by default. Call deny_response(true) to return 403 Forbidden for supported HTTP requests, including HTTPS on intercepted ports. Optionally set deny_message to customize the body; {host} names the blocked hostname. Setting a message alone does not enable responses. Enabling requires a supporting local runtime; cloud rejects it. See What a denied HTTP request sees. HttpBuilder::build() returns HttpConfig, stored in NetworkConfig.http:

pub struct HttpConfig {
    pub deny_response: bool,
    pub deny_message: Option<String>,
}

When enabled, None uses the built-in message; Some(String::new()) sends an empty body.

network.strict()

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

Require hostname-based policy allows to use an inspectable request authority. Default: true. Plain HTTP exposes that authority in Host; HTTPS only exposes it when TLS interception is enabled and not bypassed. Without that visibility, strict mode denies HTTPS that would otherwise be allowed only by a hostname rule.

network.tcp_accept_queue_size()

fn tcp_accept_queue_size(self, size: u32) -> Self

Set how many not-yet-accepted connections each published TCP port’s host listener queues. Default: 1024. Accepts 1..=i32::MAX; other values record BuildError::InvalidTcpAcceptQueueSize. Connections arriving while the queue is full never reach the sandbox, so raise this when a burst of parallel connections, such as a reverse proxy fanning out one page load, exceeds it. The host kernel caps the effective depth at net.core.somaxconn on Linux (4,096 by default) or kern.ipc.somaxconn on macOS (128 by default). Runtimes that predate the setting are refused with an upgrade-required error rather than silently ignoring it. RestoreBuilder, ForkBuilder, and ForkManyBuilder expose the same tcp_accept_queue_size() for the listeners a child publishes.

network.nat64_prefix()

fn nat64_prefix(self, prefix: Ipv6Network) -> Self

Add a NAT64 /96 prefix for policy classification. Destinations inside NAT64 prefixes are evaluated against both their IPv6 address and the embedded IPv4 address, so translated private, loopback, link-local, and metadata IPv4 addresses retain their normal policy groups. The well-known 64:ff9b::/96 prefix is configured by default.

Parameters

prefixIpv6Network

NAT64 prefix. Must be an IPv6 /96.

network.max_udp_connections()

fn max_udp_connections(self, max: usize) -> Self

Set the runtime UDP relay session limit. Omission is unlimited in single-tenant mode and defaults to 1,024 in multi-tenant mode; zero explicitly selects unlimited. At a finite limit, a new session evicts the least recently active session. Sessions expire after 60 seconds of inactivity. Historical runtime launch contracts reject explicit UDP limits, including zero, with an upgrade-required error.

network.max_tcp_connections()

max_connections remains a deprecated alias for this builder method. The last call sets the TCP limit. Either method can be combined with the UDP limit.

fn max_tcp_connections(self, max: usize) -> Self

Limit the maximum number of concurrent TCP connections from the sandbox. When omitted, single-tenant mode is unlimited and multi-tenant mode defaults to 1,024. A positive value overrides the default; passing zero explicitly selects unlimited in either mode. Hosting services are responsible for restricting tenant overrides. See deployment profiles for historical TCP limits and defaults. For dedicated snapshot restore, RestoreBuilder::max_tcp_connections and RestoreBuilder::max_udp_connections set the destination limits. RestoreBuilder::max_connections remains a deprecated TCP alias; the last TCP setter call wins.

Parameters

maxusize

Maximum concurrent TCP connections.

network.rate_limiter()

fn rate_limiter(self, f: impl FnOnce(NetworkRateLimiterBuilder) -> NetworkRateLimiterBuilder) -> Self

Example

use std::time::Duration;
use microsandbox::size::SizeExt;

.network(|n| n.rate_limiter(|r| r
    .egress(|r| r
        .bandwidth(1.mib(), Duration::from_secs(1))
        .bandwidth_burst(512.kib())
        .ops(1_000, Duration::from_secs(1)))
    .ingress(|r| r.ops(1_000, Duration::from_secs(1)))))

Configure network rate limits. Egress and ingress are independently optional; an omitted direction is unlimited. The limit applies on the next sandbox start.

network.ipv4_pool()

fn ipv4_pool(self, pool: Ipv4Network) -> Self

Set the IPv4 pool used to derive per-sandbox /30 guest subnets. Defaults to 172.16.0.0/12. A pool with a prefix longer than /30 records BuildError::InvalidIpv4Pool.

Parameters

poolIpv4Network

IPv4 pool, prefix /30 or shorter.

network.ipv6_pool()

fn ipv6_pool(self, pool: Ipv6Network) -> Self

Set the IPv6 pool used to derive per-sandbox /64 guest prefixes. Defaults to fd42:6d73:62::/48. A pool with a prefix longer than /64 records BuildError::InvalidIpv6Pool.

network.interface()

fn interface(self, overrides: InterfaceOverrides) -> Self

Override the guest interface settings wholesale: MAC, MTU, IPv4/IPv6 addresses, and the derivation pools. A low-level escape hatch. For the common case of changing only the address pools, prefer ipv4_pool() and ipv6_pool(), which validate the prefix. Unset fields fall back to values derived deterministically from the sandbox slot. See InterfaceOverrides.

Parameters

overridesInterfaceOverrides

Guest interface overrides.

network.enabled()

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

Enable or disable networking. Default: true. To fully turn networking off, prefer SandboxBuilder::disable_network(), which also sets the policy to NetworkPolicy::none().

network.secret_violation_action()

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

Set the sandbox-wide blocking action. Passthrough hosts are configured per secret with allow_placeholder_for().

network.secret()

fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self

Add a secret via a closure builder. Mirrors SandboxBuilder::secret(). See SecretBuilder for the full API. A companion secret_env(env_var, value, placeholder, allowed_host) shorthand and secret_entry(SecretEntry) are also available on NetworkBuilder.

Parameters

fSecretBuilder

Configure the secret.

DnsBuilder

Builder for DNS interception, used in NetworkBuilder::dns(|d| d...). Owns rebind protection, nameserver pinning, and the per-query timeout. Every setter returns Self.

dns.nameservers()

fn nameservers<I>(self, nameservers: I) -> Self
where
    I: IntoIterator,
    I::Item: Into<Nameserver>

Set the upstream nameservers to forward DNS queries to. Replaces any previously-set nameservers. When empty, the interceptor falls back to the host’s /etc/resolv.conf (or, on macOS, the SystemConfiguration dynamic store). Each element converts into Nameserver: a SocketAddr, an IpAddr, or a parsed string via "dns.google:53".parse::<Nameserver>()?.

Parameters

nameserversIntoIterator<Item = Into<Nameserver>>

Upstream resolvers.

dns.query_timeout_ms()

fn query_timeout_ms(self, ms: u64) -> Self

Set the per-DNS-query timeout in milliseconds. Default: 5000.

dns.rebind_protection()

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

When enabled, the interceptor blocks DNS responses that resolve to private IP addresses, preventing DNS rebinding attacks. Default: true.

TlsBuilder

Builder for TLS interception, used in NetworkBuilder::tls(|t| t...). Creating it enables interception. Every setter returns Self.

tls.bypass()

fn bypass(self, pattern: impl Into<String>) -> Self

Skip TLS interception for hosts matching this glob (e.g. "*.internal.corp"). Use for domains with certificate pinning. Can be called multiple times.

Parameters

patternimpl Into<String>

Host glob. Supports exact match and *.suffix wildcards.

tls.intercepted_ports()

fn intercepted_ports(self, ports: Vec<u16>) -> Self

TCP ports where TLS interception is active. Default: [443].

tls.verify_upstream()

fn verify_upstream(self, verify: bool) -> Self

Whether the proxy verifies upstream server certificates. Default: true. Set to false only for self-signed servers.

tls.block_quic()

fn block_quic(self, block: bool) -> Self

Block QUIC/HTTP3 on intercepted ports, forcing TCP/TLS fallback. Default: true.

tls.intercept_ca_cert()

fn intercept_ca_cert(self, path: impl Into<PathBuf>) -> Self

PEM file used as the intercepting CA’s certificate. Pair with intercept_ca_key() to provide a stable CA across sandbox restarts. If unset, a CA is auto-generated and persisted.

tls.intercept_ca_key()

fn intercept_ca_key(self, path: impl Into<PathBuf>) -> Self

PEM file used as the intercepting CA’s private key.

tls.upstream_ca_cert()

fn upstream_ca_cert(self, path: impl Into<PathBuf>) -> Self

PEM file with extra root CAs the proxy should trust when verifying every upstream server. Useful for self-signed or private upstream CAs. Can be called multiple times.

tls.upstream_ca_cert_for()

fn upstream_ca_cert_for(
    self,
    pattern: impl Into<String>,
    path: impl Into<PathBuf>,
) -> Self

PEM file with extra root CAs the proxy should trust only when the upstream SNI matches pattern. Pattern syntax matches bypass(): exact hosts and *.suffix wildcards are supported.

tls.verify_upstream_for()

fn verify_upstream_for(
    self,
    pattern: impl Into<String>,
    verify: bool,
) -> Self

Whether the proxy verifies upstream server certificates only when the upstream SNI matches pattern. Pattern syntax matches bypass(): exact hosts and *.suffix wildcards are supported. Setting verify to false is the proxy-side equivalent of curl -k for matching hosts; TLS interception still runs.

NetworkRateLimiterBuilder

Groups local rate limits by traffic direction. Supplied to NetworkBuilder::rate_limiter().

.egress()

fn egress(self, f: impl FnOnce(RateLimiterBuilder) -> RateLimiterBuilder) -> Self

Configure the guest-to-runtime direction.

.ingress()

fn ingress(self, f: impl FnOnce(RateLimiterBuilder) -> RateLimiterBuilder) -> Self

Configure the runtime-to-guest direction.

RateLimiterBuilder

Builder for one direction’s rate limiter, supplied to NetworkRateLimiterBuilder::egress() or ingress(). A limiter caps bandwidth (bytes) and packet rate (frames) independently; leaving a bucket unset leaves that dimension unlimited. Buckets start full plus their one-time burst and refill continuously. Every setter returns Self. Validation runs at NetworkBuilder::build(). Each of these surfaces as BuildError: a limiter with neither bucket, a zero bucket size or refill interval, a burst without its bucket, or a refill interval that does not fit in u64 milliseconds.

.bandwidth()

fn bandwidth(self, size: impl Into<Bytes>, refill_time: Duration) -> Self

Cap bandwidth at size bytes per refill_time. Size accepts a bare u64 byte count or the unit helpers from microsandbox::size::SizeExt (1.mib(), 512.kib()).

Parameters

sizeimpl Into<Bytes>

Bucket capacity in bytes.

refill_timeDuration

Time to refill the full bucket.

.bandwidth_burst()

fn bandwidth_burst(self, burst: impl Into<Bytes>) -> Self

Grant a one-time startup burst of extra bytes on top of the bandwidth bucket. The burst is spent before the regular budget and never refills. Requires bandwidth().

.ops()

fn ops(self, count: u64, refill_time: Duration) -> Self

Cap packet rate at count frames per refill_time.

.ops_burst()

fn ops_burst(self, count: u64) -> Self

Grant a one-time startup burst of extra frames on top of the ops bucket. Requires ops().

Rule

Held by NetworkPolicy

A single policy rule. The destination interpretation is direction-dependent: egress destination, or ingress peer/source. ports is always the guest-side port (egress destination port / ingress listening port).

Field	Type	Description
`direction`	`Direction`	Which evaluator considers this rule
`destination`	`Destination`	Target filter
`protocols`	`Vec<Protocol>`	Set semantics; empty = any protocol
`ports`	`Vec<PortRange>`	Set semantics; empty = any port
`action`	`Action`	What to do on match

Convenience constructors build any-protocol, any-port rules:

Rule::allow_egress()

Rule::allow_egress(destination)

Allow rule, direction Egress

Rule::deny_egress()

Rule::deny_egress(destination)

Deny rule, direction Egress

Rule::allow_ingress()

Rule::allow_ingress(destination)

Allow rule, direction Ingress

Rule::deny_ingress()

Rule::deny_ingress(destination)

Deny rule, direction Ingress

Rule::allow_any()

Rule::allow_any(destination)

Allow rule, direction Any

Rule::deny_any()

Rule::deny_any(destination)

Deny rule, direction Any

Rule::allow_dns()

Rule::allow_dns()

Allow plain DNS (UDP/53 + TCP/53) to the gateway forwarder (Group::Host); the one-liner for opening DNS under deny-by-default. See DNS as egress.

Rule::deny_dns()

Rule::deny_dns()

Deny plain DNS (UDP/53 + TCP/53) to the gateway forwarder; place before profile-generated rules to override automatic DNS.

PortRange

Held by Rule · added by port() · port_range()

An inclusive port range.

Field	Type	Description
`start`	`u16`	Start port (inclusive)
`end`	`u16`	End port (inclusive)

PortRange::single()

PortRange::single(port)

Match a single port

PortRange::range()

PortRange::range(start, end)

Match an inclusive range

PortRange::contains()

contains(port)

Whether port falls within the range

DomainName

Held by Destination::Domain / DomainSuffix

A validated, canonical DNS name.

name.as_str()

as_str()

Borrow the canonical string form

name.try_into_suffix()

try_into_suffix()

Validate for use as a DomainSuffix; single-label names (e.g. com) are rejected

Types

NetworkProfile

Composable high-level access category accepted by NetworkPolicy::from_profiles().

Variant	Access
`Public`	Public internet addresses
`Private`	Private/LAN ranges (RFC 1918, RFC 4193 ULA, and CGN)
`Host`	The sandbox host via its gateway addresses

Action

Used by Rule · NetworkPolicy · default_egress()

Value	Wire format	Description
`Allow`	`"allow"`	Permit the traffic
`Deny`	`"deny"`	Drop the traffic silently

Direction

Used by Rule

Value	Wire format	Description
`Egress`	`"egress"`	Traffic leaving the sandbox
`Ingress`	`"ingress"`	Traffic entering the sandbox (via published ports)
`Any`	`"any"`	Rule applies in either direction

Destination

Held by Rule · committed by RuleDestinationBuilder

Variant	Description
`Any`	Match any address
`Cidr(IpNetwork)`	Match a CIDR range (e.g. `10.0.0.0/8`); single IPs are stored as `/32` or `/128`
`Domain(DomainName)`	Match an exact domain (e.g. `example.com`) when a cached hostname for the remote IP equals it
`DomainSuffix(DomainName)`	Match the apex domain and every subdomain (e.g. `example.com` and `api.example.com`)
`Group(DestinationGroup)`	Match a predefined address group

DestinationGroup

Held by Destination · committed by RuleBuilder group adders

Groups are disjoint with one carve-out: Metadata takes precedence over LinkLocal for 169.254.169.254, and Host over Private when the gateway IPs sit in CGN/ULA ranges.

Value	Wire format	Matches
`Public`	`"public"`	Complement of the other categories: every address not in any other group
`Loopback`	`"loopback"`	`127.0.0.0/8`, `::1` (the guest’s own loopback, not the host)
`Private`	`"private"`	RFC1918 (`10/8`, `172.16/12`, `192.168/16`) + CGN (`100.64/10`) + ULA (`fc00::/7`)
`LinkLocal`	`"link_local"`	`169.254.0.0/16`, `fe80::/10` (excludes metadata)
`Metadata`	`"metadata"`	Cloud metadata endpoint (`169.254.169.254`)
`Multicast`	`"multicast"`	`224.0.0.0/4`, `ff00::/8`
`Host`	`"host"`	Per-sandbox gateway IPs that back `host.microsandbox.internal`

Protocol

Held by Rule · set by RuleBuilder protocol setters

Value	Wire format
`Tcp`	`"tcp"`
`Udp`	`"udp"`
`Icmpv4`	`"icmpv4"`
`Icmpv6`	`"icmpv6"`

ICMP protocols are egress-only. A rule with direction Ingress or Any carrying an ICMP protocol fails build with BuildError::IngressDoesNotSupportIcmp.

Nameserver

Used by nameservers()

An upstream DNS server, either a literal address or a hostname resolved at interceptor startup via the host’s OS resolver. Serializes as a single string. Construct via From<SocketAddr>, From<IpAddr>, or str::parse (errors with ParseNameserverError).

Variant	Description
`Addr(SocketAddr)`	Literal socket address, ready to use
`Host { host: String, port: u16 }`	Hostname + port resolved at startup

Accepted parse forms: 1.1.1.1, 1.1.1.1:5353, 2606:4700:4700::1111, [2606:4700:4700::1111]:53, dns.google, dns.google:53. A bare IP or hostname defaults to port 53.

InterfaceOverrides

Used by interface()

Per-sandbox guest interface overrides. Every field is optional; an omitted field is derived deterministically from the sandbox slot. Most callers only touch the pools via ipv4_pool() / ipv6_pool() rather than constructing this directly.

Field	Type	Description
mac	`Option<[u8; 6]>`	Guest MAC address. Default: derived from slot
mtu	`Option<u16>`	Interface MTU. Default: `1500`
ipv4_address	`Option<Ipv4Addr>`	Guest IPv4 address. Default: derived from slot within `ipv4_pool`
ipv4_pool	`Option<Ipv4Network>`	IPv4 pool guest subnets are derived from. Default: `172.16.0.0/12`
ipv6_address	`Option<Ipv6Addr>`	Guest IPv6 address. Default: derived from slot within `ipv6_pool`
ipv6_pool	`Option<Ipv6Network>`	IPv6 pool guest prefixes are derived from. Default: `fd42:6d73:62::/48`

NetworkRateLimiterConfig

Built by NetworkRateLimiterBuilder · used by rate_limiter()

Network rate limits grouped by direction. An omitted direction is unlimited.

Field	Type	Description
egress	`Option<RateLimiterConfig>`	Guest-to-runtime limit
ingress	`Option<RateLimiterConfig>`	Runtime-to-guest limit

RateLimiterConfig

Built by RateLimiterBuilder · held by NetworkRateLimiterConfig

Rate limiter for one traffic direction. A missing bucket leaves that dimension unlimited.

Field	Type	Description
bandwidth	`Option<TokenBucketConfig>`	Byte budget; one token per byte of frame data
ops	`Option<TokenBucketConfig>`	Packet budget; one token per network frame

TokenBucketConfig

Held by RateLimiterConfig

One token bucket of a rate limiter. The bucket starts full and refills continuously at size tokens per refill_time_ms; the one-time burst is spent before the regular budget and never refills.

Field	Type	Description
size	`u64`	Bucket capacity in tokens; must be greater than zero
refill_time_ms	`u64`	Time to refill `size` tokens, in milliseconds; must be greater than zero
one_time_burst	`u64`	Extra startup-only tokens. Default: `0`

BuildError

Returned by NetworkPolicyBuilder::build() · wrapped by NetworkBuilder

Errors surfaced by the builders’ build() methods. The same enum covers NetworkPolicy::builder(), DnsBuilder, and NetworkBuilder; the network and DNS builders accumulate lazily, so the first failure surfaces from the outermost build() in the chain.

Variant	Cause
`DirectionNotSet { rule_index }`	A rule was committed without `.egress() / .ingress() / .any()`
`MissingDestination { rule_index }`	`.allow()` or `.deny()` was called but no destination method followed
`InvalidIp { rule_index, raw }`	`.ip(&str)` got an unparseable value
`InvalidCidr { rule_index, raw }`	`.cidr(&str)` got an unparseable value
`InvalidIpv4Pool { raw }`	`ipv4_pool()` got a pool that can’t hold a `/30` sandbox subnet
`InvalidIpv6Pool { raw }`	`ipv6_pool()` got a pool that can’t hold a `/64` sandbox prefix
`InvalidTcpAcceptQueueSize { source }`	`tcp_accept_queue_size()` got a value outside `1..=i32::MAX`
`InvalidNat64Prefix { raw }`	`nat64_prefix()` got a prefix that is not an IPv6 `/96`
`InvalidOutboundProxy { reason }`	`SandboxBuilder::proxy()` got an invalid proxy configuration
`InvalidDomain { rule_index, raw, source }`	`.domain` / `.domain_suffix` got a value that failed `DomainName` parse
`InvalidPortRange { rule_index, lo, hi }`	`.port_range(lo, hi)` had `lo > hi`
`IngressDoesNotSupportIcmp { rule_index }`	ICMP protocol on a non-egress rule
`InvalidSecretConfig { source }`	A secret entry failed validation
`InvalidRateLimitConfig { direction, source }`	A rate limiter had no buckets, a zero bucket size, or a zero refill interval
`EmptyNetworkRateLimiter`	`rate_limiter()` configured neither egress nor ingress
`RateLimitBurstWithoutBucket { direction, bucket }`	`bandwidth_burst()` / `ops_burst()` without the matching bucket
`RateLimitRefillTooLong { direction, bucket }`	A refill interval that does not fit in u64 milliseconds

Inside SandboxBuilder::build(), BuildError is wrapped as MicrosandboxError::NetworkBuilder(BuildError).

SecretViolationAction

Used by secret_violation_action()

Action taken when a secret placeholder is sent to a disallowed host. Also documented on the Secrets page, where it pairs with SecretBuilder.

Value	Wire format	Description
`Block`	`"block"`	Silently drop the request
`BlockAndLog`	`"block-and-log"`	Drop the request and emit a warning log (the default)
`BlockAndTerminate`	`"block-and-terminate"`	Drop the request, log an error, and shut down the sandbox

⌘I

​NetworkPolicy

​NetworkPolicy::builder()

​NetworkPolicy::none()

​NetworkPolicy::allow_all()

​NetworkPolicy::from_profiles()

​policy.allow_domain()

​policy.deny_domain()

​policy.allow_domains()

​policy.deny_domains()

​policy.allow_domain_suffix()

​policy.deny_domain_suffix()

​policy.allow_domain_suffixes()

​policy.deny_domain_suffixes()

​NetworkPolicyBuilder

​policy.default_deny()

​policy.default_allow()

​policy.default_egress()

​policy.default_ingress()

​policy.egress()

​policy.ingress()

​policy.any()

​policy.rule()

​policy.build()

​RuleBuilder

​rule.egress()

​rule.ingress()

​rule.any()

​rule.tcp()

​rule.udp()

​rule.icmpv4()

​rule.icmpv6()

​rule.port()

​rule.port_range()

​rule.ports()

​rule.allow_public()

​rule.allow_private()

​rule.allow_loopback()

​rule.allow_link_local()

​rule.allow_meta()

​rule.allow_multicast()

​rule.allow_host()

​rule.deny_public()

​rule.allow_local()

​rule.deny_local()

​rule.allow_domains()

​rule.deny_domains()

​rule.allow_domain_suffixes()

​rule.deny_domain_suffixes()

​rule.allow()

​rule.deny()

​RuleDestinationBuilder

​destination.ip()

​destination.cidr()

​destination.domain()

​destination.domain_suffix()

​destination.group()

​destination.any()

​NetworkBuilder

​network.policy()

​network.port()

​network.port_udp()

​network.port_bind()

​network.port_udp_bind()

​network.dns()

​network.tls()

​network.trust_host_cas()

​network.http()

​network.strict()

​network.tcp_accept_queue_size()

​network.nat64_prefix()

​network.max_udp_connections()

​network.max_tcp_connections()

​network.rate_limiter()

​network.ipv4_pool()

​network.ipv6_pool()

​network.interface()

​network.enabled()

​network.secret_violation_action()

​network.secret()

​DnsBuilder

NetworkPolicy

NetworkPolicy::builder()

NetworkPolicy::none()

NetworkPolicy::allow_all()

NetworkPolicy::from_profiles()

policy.allow_domain()

policy.deny_domain()

policy.allow_domains()

policy.deny_domains()

policy.allow_domain_suffix()

policy.deny_domain_suffix()

policy.allow_domain_suffixes()

policy.deny_domain_suffixes()

NetworkPolicyBuilder

policy.default_deny()

policy.default_allow()

policy.default_egress()

policy.default_ingress()

policy.egress()

policy.ingress()

policy.any()

policy.rule()

policy.build()

RuleBuilder

rule.egress()

rule.ingress()

rule.any()

rule.tcp()

rule.udp()

rule.icmpv4()

rule.icmpv6()

rule.port()

rule.port_range()

rule.ports()

rule.allow_public()

rule.allow_private()

rule.allow_loopback()

rule.allow_link_local()

rule.allow_meta()

rule.allow_multicast()

rule.allow_host()

rule.deny_public()

rule.allow_local()

rule.deny_local()

rule.allow_domains()

rule.deny_domains()

rule.allow_domain_suffixes()

rule.deny_domain_suffixes()

rule.allow()

rule.deny()

RuleDestinationBuilder

destination.ip()

destination.cidr()

destination.domain()

destination.domain_suffix()

destination.group()

destination.any()

NetworkBuilder

network.policy()

network.port()

network.port_udp()

network.port_bind()

network.port_udp_bind()

network.dns()

network.tls()

network.trust_host_cas()

network.http()

network.strict()

network.tcp_accept_queue_size()

network.nat64_prefix()

network.max_udp_connections()

network.max_tcp_connections()

network.rate_limiter()

network.ipv4_pool()

network.ipv6_pool()

network.interface()

network.enabled()

network.secret_violation_action()

network.secret()

DnsBuilder