Networking

See Networking for conceptual overview and TLS Interception for TLS proxy details.

NetworkPolicy

A network access policy consisting of two per-direction defaults and an ordered list of rules evaluated first-match-wins per direction.

The default NetworkPolicy::default() is default_egress = Deny + implicit allow@public, default_ingress = Allow + no rules. This preserves today's public_only egress behavior plus today's unfiltered published-port behavior. See the defaults rationale for why the defaults are asymmetric.

Presets

Static methods that return pre-configured policies. Most callers should use the builder; presets exist as compat shims for the legacy API.

NetworkPolicy::allow_all()    // unrestricted
NetworkPolicy::none()         // deny both directions
NetworkPolicy::public_only()  // egress=Deny + allow Public; ingress=Allow (today's default)
NetworkPolicy::non_local()    // egress=Deny + allow Public+Private; ingress=Allow

NetworkPolicy::builder()

The fluent builder is the primary construction path. String inputs (.ip(&str), .cidr(&str), .domain(&str), .domain_suffix(&str)) are stored raw and parsed at .build() time; the chain stays clean. The first parse / validation failure surfaces as BuildError.

use microsandbox::NetworkPolicy;

let policy = NetworkPolicy::builder()
    .default_deny()
    .egress(|e| e.tcp().port(443).allow_public().allow_private())
    .rule(|r| r.any().deny().ip("198.51.100.5"))
    .build()?;

Top-level methods

The closure signature is FnOnce(&mut RuleBuilder) -> &mut RuleBuilder. A chain ending in any rule-adder (.allow_public(), .deny().ip(...), etc.) returns the builder reference and satisfies the bound. Multi-statement bodies end with an explicit r return.

Inside the closure: RuleBuilder

Inside .rule(|r| ...) (or any of the direction sub-builders), state setters and rule-adders interleave freely. State accumulates eagerly across the closure; each rule-adder commits a rule using the state at that point.

State setters:

Per-category rule-adders (each commits one rule using the current state):

Bulk-domain shortcuts (one rule per name, inheriting current direction/protocol/port state):

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

Composite sugar:

Explicit-rule sub-builder (.allow() / .deny() open it):

.rule(|r| r.egress().tcp().port(443).allow().domain("api.example.com"))
.rule(|r| r.any().deny().cidr("198.51.100.0/24"))

Returns an ExplicitRuleBuilder requiring a destination call (.ip / .cidr / .domain / .domain_suffix / .group / .any) to commit. Dropping without a destination call adds no rule (the type is #[must_use]).

State accumulation

State is not reset between rule-adders within a closure. Callers wanting different state per rule use separate .rule() calls or interleave state setters between adders:

.rule(|r| r.egress()
    .tcp().port(443).allow_public()    // rule 1: egress, TCP, 443, allow Public
    .udp().allow_private())            // rule 2: egress, [TCP, UDP], 443, allow Private
                                       //   (UDP added; TCP and 443 still in state)

Shadow detection

At .build() time, the builder walks the rules list and emits a tracing::warn! for any rule whose match set is fully contained in an earlier rule's match set in a compatible direction. Coverage is Ip / Cidr / Group destinations; domain shadowing is intentionally out of scope (depends on runtime DNS state).

NetworkBuilder

Builder for configuring the sandbox's network stack. Used in SandboxBuilder::network(|n| n...).

policy()

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

Set the network access policy. Override the default with a builder-constructed value:

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

dns()

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

Configure DNS interception. Errors accumulated by DnsBuilder cascade up; the outermost SandboxBuilder::build() surfaces them as MicrosandboxError::NetworkBuilder(BuildError).

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

max_connections()

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

Limit the maximum number of concurrent network connections from the sandbox.

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.) whose gateway CA is installed on the host but unknown to the guest's stock Mozilla bundle.

tls()

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

Configure TLS interception. See TlsBuilder.

on_secret_violation()

fn on_secret_violation(self, action: ViolationAction) -> Self

Set the action taken when a secret placeholder is detected in traffic destined for a host not in the secret's allow list.

DnsBuilder

Builder for DNS interception settings. Used in NetworkBuilder::dns(|d| d...). Owns rebind protection, nameserver pinning, and the per-query timeout.

rebind_protection()

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

When enabled, DNS responses that resolve to private IP addresses are blocked. This prevents DNS rebinding attacks. Default: true.

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. Each element is convertible into Nameserver (SocketAddr, IpAddr, or a parsed string via "dns.google:53".parse::<Nameserver>()?).

query_timeout_ms()

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

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

TlsBuilder

Builder for TLS interception settings. Used in NetworkBuilder::tls(|t| t...).

Types

Action

Wire format: "allow" / "deny".

Direction

Wire format: "egress" / "ingress" / "any".

Destination

DestinationGroup

DomainName

A validated DNS name. Construction goes through str::parse (or TryFrom<String>), which delegates to hickory_proto::rr::Name and canonicalizes the input (lowercased ASCII, leading and trailing dots stripped) so rule matching is a byte-wise compare against the DNS cache. Invalid inputs return a DomainNameError.

use microsandbox_network::policy::{Destination, DomainName};

let exact: DomainName = "PyPI.Org.".parse()?;     // -> "pypi.org"
let suffix: DomainName = ".example.com".parse()?;  // -> "example.com"

Labels follow the permissive DNS grammar (RFC 2181 §11), so underscore-prefixed names like _service._tcp.example.com are accepted.

The builder methods (.domain(&str), .domain_suffix(&str)) take strings and parse them lazily at .build() — callers don't need to construct DomainName directly.

Protocol

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

PortRange

Rule

A single network policy rule.

Convenience constructors:

ExplicitRuleBuilder

Returned by RuleBuilder::allow() / ::deny(). Requires exactly one destination method call to commit the rule. The type is #[must_use] — dropping without a call adds no rule.

BuildError

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

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

ViolationAction

Action taken when a secret placeholder is sent to a disallowed host.