> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking

> Rust SDK - Network API reference

Configure a sandbox's network stack: a first-match-wins egress/ingress policy, published ports, DNS interception, TLS interception, and secret-violation handling. See [Networking](/networking/overview) for the conceptual overview and [TLS Interception](/networking/tls) for proxy details.

<p className="msb-label" id="typical-flow">Typical flow</p>

```rust theme={null}
use microsandbox::{NetworkPolicy, Sandbox};

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

let sb = Sandbox::builder("api")
    .image("python")
    .network(|n| n                          // 2. wire it into the sandbox
        .policy(policy)
        .port(8080, 80)
        .dns(|d| d.rebind_protection(true)))
    .create()
    .await?;
```

The default policy denies egress except for an implicit allow-public rule (plus DNS), and allows ingress with no rules. See the [defaults rationale](/networking/overview#defaults) for the asymmetry. `NetworkPolicy` and the builders live in `microsandbox_network`; `NetworkPolicy` is also re-exported from the crate root as `microsandbox::NetworkPolicy`.

## NetworkPolicy static methods

A [`NetworkPolicy`](#networkpolicy) is an ordered rule list plus two per-direction defaults, evaluated first-match-wins. The presets below construct common shapes directly; for anything custom, start from [`builder()`](#networkpolicybuilder).

#### <span className="msb-recv">NetworkPolicy::</span><span className="msb-hn">builder()</span>

```rust theme={null}
fn builder() -> NetworkPolicyBuilder
```

<Accordion title="Example">
  ```rust theme={null}
  use microsandbox::NetworkPolicy;

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

Start the fluent [`NetworkPolicyBuilder`](#networkpolicybuilder). The primary construction path: string inputs (`.ip`, `.cidr`, `.domain`, `.domain_suffix`) are stored raw and parsed at [`build()`](#build), so the chain stays clean and the first parse or validation failure surfaces as [`BuildError`](#builderror).

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#networkpolicybuilder">NetworkPolicyBuilder</a></div>
    <div className="msb-param-desc">Empty builder.</div>
  </div>
</div>

#### <span className="msb-recv">NetworkPolicy::</span><span className="msb-hn">none()</span>

```rust theme={null}
fn none() -> NetworkPolicy
```

No network access: deny everything in both directions, no rules. This is the policy set by [`SandboxBuilder::disable_network()`](/sdk/rust/sandbox#disable_network).

#### <span className="msb-recv">NetworkPolicy::</span><span className="msb-hn">allow\_all()</span>

```rust theme={null}
fn allow_all() -> NetworkPolicy
```

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

#### <span className="msb-recv">NetworkPolicy::</span><span className="msb-hn">public\_only()</span>

```rust theme={null}
fn public_only() -> NetworkPolicy
```

Public internet only, and the [`Default`](#networkpolicy) policy. Egress defaults to deny but allows DNS to the gateway forwarder and any [`Public`](#destinationgroup) destination; private, loopback, link-local, and metadata are denied. Ingress defaults to allow, preserving unfiltered published-port behavior.

#### <span className="msb-recv">NetworkPolicy::</span><span className="msb-hn">non\_local()</span>

```rust theme={null}
fn non_local() -> NetworkPolicy
```

Non-local access: like [`public_only()`](#networkpolicypublic_only) but also allows egress to [`Private`](#destinationgroup) / LAN ranges. Loopback, link-local, and metadata stay denied; ingress defaults to allow.

## NetworkPolicy instance methods

These methods consume `self` and return a modified policy, so they chain off a preset 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>`](#domainname) because the names are parsed eagerly.

#### <span className="msb-recv">policy.</span><span className="msb-hn">allow\_domain()</span>

```rust theme={null}
fn allow_domain<S: AsRef<str>>(self, name: S) -> Result<NetworkPolicy, DomainNameError>
```

<Accordion title="Example">
  ```rust theme={null}
  let policy = NetworkPolicy::public_only().allow_domain("api.openai.com")?;
  ```
</Accordion>

Prepend a single allow-[`Domain`](#destination) egress rule. Single-name sugar over [`allow_domains()`](#policy-allow_domains).

#### <span className="msb-recv">policy.</span><span className="msb-hn">deny\_domain()</span>

```rust theme={null}
fn deny_domain<S: AsRef<str>>(self, name: S) -> Result<NetworkPolicy, DomainNameError>
```

Prepend a single deny-[`Domain`](#destination) egress rule. Single-name sugar over [`deny_domains()`](#policy-deny_domains).

#### <span className="msb-recv">policy.</span><span className="msb-hn">allow\_domains()</span>

```rust theme={null}
fn allow_domains<I, S>(self, names: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
```

<Accordion title="Example">
  ```rust theme={null}
  let policy = NetworkPolicy::default()
      .allow_domains(["pypi.org", "files.pythonhosted.org"])?;
  ```
</Accordion>

Prepend one allow-[`Domain`](#destination) egress rule per name.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>names</code><span className="msb-type">IntoIterator\<Item = AsRef\<str>></span></div>
    <div className="msb-param-desc">Exact domain names.</div>
  </div>
</div>

#### <span className="msb-recv">policy.</span><span className="msb-hn">deny\_domains()</span>

```rust theme={null}
fn deny_domains<I, S>(self, names: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
```

<Accordion title="Example">
  ```rust theme={null}
  let policy = NetworkPolicy::allow_all()
      .deny_domains(["evil.com", "tracker.example"])?;
  ```
</Accordion>

Prepend one deny-[`Domain`](#destination) egress rule per name. Prepending lets the denies outrank catch-all allows.

#### <span className="msb-recv">policy.</span><span className="msb-hn">allow\_domain\_suffix()</span>

```rust theme={null}
fn allow_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<NetworkPolicy, DomainNameError>
```

Prepend a single allow-[`DomainSuffix`](#destination) egress rule. Single-suffix sugar over [`allow_domain_suffixes()`](#policy-allow_domain_suffixes).

#### <span className="msb-recv">policy.</span><span className="msb-hn">deny\_domain\_suffix()</span>

```rust theme={null}
fn deny_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<NetworkPolicy, DomainNameError>
```

Prepend a single deny-[`DomainSuffix`](#destination) egress rule. Single-suffix sugar over [`deny_domain_suffixes()`](#policy-deny_domain_suffixes).

#### <span className="msb-recv">policy.</span><span className="msb-hn">allow\_domain\_suffixes()</span>

```rust theme={null}
fn allow_domain_suffixes<I, S>(self, suffixes: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
```

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

#### <span className="msb-recv">policy.</span><span className="msb-hn">deny\_domain\_suffixes()</span>

```rust theme={null}
fn deny_domain_suffixes<I, S>(self, suffixes: I) -> Result<NetworkPolicy, DomainNameError>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
```

<Accordion title="Example">
  ```rust theme={null}
  let policy = NetworkPolicy::allow_all()
      .deny_domain_suffixes([".ads.example", ".doubleclick.net"])?;
  ```
</Accordion>

Prepend one deny-[`DomainSuffix`](#destination) egress rule per suffix.

## NetworkPolicyBuilder

Fluent builder for [`NetworkPolicy`](#networkpolicy), obtained via [`NetworkPolicy::builder()`](#networkpolicybuilder). Defaults and rule-batch closures interleave; the build is deferred. The closure signature for [`rule()`](#rule) / [`egress()`](#egress) / [`ingress()`](#ingress) / [`any()`](#any) 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.

State setters inside a closure (`.tcp()`, `.port()`) accumulate eagerly and are **not reset** between rule-adders, so a single closure can fan one state into several rules. Use separate closures for rules that need different state. See [State accumulation](/networking/overview) for the rationale.

#### <span className="msb-recv">.</span><span className="msb-hn">default\_deny()</span>

```rust theme={null}
fn default_deny(self) -> Self
```

Set both `default_egress` and `default_ingress` to [`Deny`](#action).

#### <span className="msb-recv">.</span><span className="msb-hn">default\_allow()</span>

```rust theme={null}
fn default_allow(self) -> Self
```

Set both `default_egress` and `default_ingress` to [`Allow`](#action).

#### <span className="msb-recv">.</span><span className="msb-hn">default\_egress()</span>

```rust theme={null}
fn default_egress(self, action: Action) -> Self
```

Per-direction override for the egress default action.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>action</code><a className="msb-type" href="#action">Action</a></div>
    <div className="msb-param-desc">Default action for egress.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">default\_ingress()</span>

```rust theme={null}
fn default_ingress(self, action: Action) -> Self
```

Per-direction override for the ingress default action.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>action</code><a className="msb-type" href="#action">Action</a></div>
    <div className="msb-param-desc">Default action for ingress.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">egress()</span>

```rust theme={null}
fn egress<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder
```

<Accordion title="Example">
  ```rust theme={null}
  NetworkPolicy::builder()
      .default_deny()
      .egress(|e| e.tcp().port(443).allow_public())
      .build()?;
  ```
</Accordion>

Sugar for [`rule()`](#rule) with direction pre-set to [`Egress`](#direction).

#### <span className="msb-recv">.</span><span className="msb-hn">ingress()</span>

```rust theme={null}
fn ingress<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder
```

Sugar for [`rule()`](#rule) with direction pre-set to [`Ingress`](#direction).

#### <span className="msb-recv">.</span><span className="msb-hn">any()</span>

```rust theme={null}
fn any<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">rule()</span>

```rust theme={null}
fn rule<F>(self, f: F) -> Self
where
    F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder
```

<Accordion title="Example">
  ```rust theme={null}
  NetworkPolicy::builder()
      .rule(|r| r.egress().tcp().port(443).allow().domain("api.example.com"))
      .build()?;
  ```
</Accordion>

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

#### <span className="msb-recv">.</span><span className="msb-hn">build()</span>

```rust theme={null}
fn build(self) -> Result<NetworkPolicy, BuildError>
```

Consume the builder and produce a [`NetworkPolicy`](#networkpolicy). Lazy-parses every `.ip()` / `.cidr()` / `.domain()` / `.domain_suffix()` input, and validates the direction-set and ICMP-egress-only invariants. Emits a `tracing::warn!` for each shadowed rule pair (a rule fully covered by an earlier one in the same direction; only `Ip` / `Cidr` / `Group` destinations are checked). Builds still succeed when a shadow is detected. Returns the first [`BuildError`](#builderror) encountered.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#networkpolicy">NetworkPolicy</a></div>
    <div className="msb-param-desc">Validated policy.</div>
  </div>
</div>

## RuleBuilder

The mutable builder handed to a [`NetworkPolicyBuilder`](#networkpolicybuilder) rule-batch closure. Direction, protocol, and port setters return `&mut Self` and accumulate eagerly; rule-adders commit one rule each using the current state. Protocols and ports have set semantics, so duplicates dedupe.

#### <span className="msb-recv">.</span><span className="msb-hn">egress()</span>

<a id="rb-egress" />

```rust theme={null}
fn egress(&mut self) -> &mut Self
```

Set direction to [`Egress`](#direction) for subsequent rule-adders. Last-write-wins.

#### <span className="msb-recv">.</span><span className="msb-hn">ingress()</span>

<a id="rb-ingress" />

```rust theme={null}
fn ingress(&mut self) -> &mut Self
```

Set direction to [`Ingress`](#direction) for subsequent rule-adders. Last-write-wins.

#### <span className="msb-recv">.</span><span className="msb-hn">any()</span>

<a id="rb-any" />

```rust theme={null}
fn any(&mut self) -> &mut Self
```

Set direction to [`Any`](#direction) for subsequent rule-adders. Rules committed after this apply in both directions. Last-write-wins.

#### <span className="msb-recv">.</span><span className="msb-hn">tcp()</span>

```rust theme={null}
fn tcp(&mut self) -> &mut Self
```

Add [`Tcp`](#protocol) to the protocols set.

#### <span className="msb-recv">.</span><span className="msb-hn">udp()</span>

```rust theme={null}
fn udp(&mut self) -> &mut Self
```

Add [`Udp`](#protocol) to the protocols set.

#### <span className="msb-recv">.</span><span className="msb-hn">icmpv4()</span>

```rust theme={null}
fn icmpv4(&mut self) -> &mut Self
```

Add [`Icmpv4`](#protocol) to the protocols set. Egress-only: an ICMP protocol on an `Ingress` or `Any` rule fails build with [`BuildError::IngressDoesNotSupportIcmp`](#builderror).

#### <span className="msb-recv">.</span><span className="msb-hn">icmpv6()</span>

```rust theme={null}
fn icmpv6(&mut self) -> &mut Self
```

Add [`Icmpv6`](#protocol) to the protocols set. Egress-only; same rule as [`icmpv4()`](#icmpv4).

#### <span className="msb-recv">.</span><span className="msb-hn">port()</span>

<a id="port-1" />

```rust theme={null}
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).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>port</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Port number.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">port\_range()</span>

```rust theme={null}
fn port_range(&mut self, lo: u16, hi: u16) -> &mut Self
```

Add an inclusive port range.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>lo</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Lower bound (inclusive).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>hi</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Upper bound (inclusive). <code>lo > hi</code> records <a href="#builderror">BuildError::InvalidPortRange</a>.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ports()</span>

```rust theme={null}
fn ports<I: IntoIterator<Item = u16>>(&mut self, ports: I) -> &mut Self
```

Add multiple single ports. Equivalent to calling [`port()`](#port-1) once per element.

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_public()</span>

```rust theme={null}
fn allow_public(&mut self) -> &mut Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_private()</span>

```rust theme={null}
fn allow_private(&mut self) -> &mut Self
```

Allow the [`Private`](#destinationgroup) group (RFC1918 + ULA + CGN).

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_loopback()</span>

```rust theme={null}
fn allow_loopback(&mut self) -> &mut Self
```

Allow the [`Loopback`](#destinationgroup) 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()`](#allow_host) instead. See the [loopback-vs-host trap](/networking/overview#loopback-vs-host-a-common-trap).

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_link\_local()</span>

```rust theme={null}
fn allow_link_local(&mut self) -> &mut Self
```

Allow the [`LinkLocal`](#destinationgroup) group (`169.254.0.0/16`, `fe80::/10`). Excludes the metadata IP `169.254.169.254`.

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_meta()</span>

```rust theme={null}
fn allow_meta(&mut self) -> &mut Self
```

Allow the [`Metadata`](#destinationgroup) group (`169.254.169.254`). **Dangerous on cloud hosts**: exposes IAM credentials.

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_multicast()</span>

```rust theme={null}
fn allow_multicast(&mut self) -> &mut Self
```

Allow the [`Multicast`](#destinationgroup) group (`224.0.0.0/4`, `ff00::/8`).

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_host()</span>

```rust theme={null}
fn allow_host(&mut self) -> &mut Self
```

Allow the [`Host`](#destinationgroup) 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()`](#allow_loopback).

#### <span className="msb-recv">.</span><span className="msb-hn">deny\_public()</span>

```rust theme={null}
fn deny_public(&mut self) -> &mut Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_local()</span>

```rust theme={null}
fn allow_local(&mut self) -> &mut Self
```

Commit **three** allow rules atomically: [`Loopback`](#destinationgroup) + `LinkLocal` + `Host`. Each uses the closure's current state. `Metadata` is intentionally excluded; opt in via [`allow_meta()`](#allow_meta) separately.

#### <span className="msb-recv">.</span><span className="msb-hn">deny\_local()</span>

```rust theme={null}
fn deny_local(&mut self) -> &mut Self
```

Commit three deny rules atomically: `Loopback` + `LinkLocal` + `Host`. `Metadata` is intentionally excluded.

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_domains()</span>

<a id="allow_domains-1" />

```rust theme={null}
fn allow_domains<I, S>(&mut self, names: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>
```

<Accordion title="Example">
  ```rust theme={null}
  NetworkPolicy::builder()
      .default_allow()
      .egress(|e| e
          .deny_domains(["evil.com", "tracker.example"])
          .deny_domain_suffixes([".ads.example", ".doubleclick.net"]))
      .build()?;
  ```
</Accordion>

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

#### <span className="msb-recv">.</span><span className="msb-hn">deny\_domains()</span>

```rust theme={null}
fn deny_domains<I, S>(&mut self, names: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>
```

Add one deny-[`Domain`](#destination) rule per name.

#### <span className="msb-recv">.</span><span className="msb-hn">allow\_domain\_suffixes()</span>

```rust theme={null}
fn allow_domain_suffixes<I, S>(&mut self, suffixes: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>
```

Add one allow-[`DomainSuffix`](#destination) rule per suffix.

#### <span className="msb-recv">.</span><span className="msb-hn">deny\_domain\_suffixes()</span>

```rust theme={null}
fn deny_domain_suffixes<I, S>(&mut self, suffixes: I) -> &mut Self
where
    I: IntoIterator<Item = S>,
    S: Into<String>
```

Add one deny-[`DomainSuffix`](#destination) rule per suffix.

#### <span className="msb-recv">.</span><span className="msb-hn">allow()</span>

<a id="rb-allow" />

```rust theme={null}
fn allow(&mut self) -> RuleDestinationBuilder<'_>
```

<Accordion title="Example">
  ```rust theme={null}
  NetworkPolicy::builder()
      .egress(|e| e.tcp().port(443).allow().domain("api.example.com"))
      .any(|a| a.deny().cidr("198.51.100.0/24"))
      .build()?;
  ```
</Accordion>

Begin an explicit-destination rule with action [`Allow`](#action). The returned [`RuleDestinationBuilder`](#ruledestinationbuilder) requires exactly one destination call to commit; dropping it without one adds no rule.

#### <span className="msb-recv">.</span><span className="msb-hn">deny()</span>

<a id="rb-deny" />

```rust theme={null}
fn deny(&mut self) -> RuleDestinationBuilder<'_>
```

Begin an explicit-destination rule with action [`Deny`](#action).

## RuleDestinationBuilder

Returned by [`RuleBuilder::allow()`](#rb-allow) / [`RuleBuilder::deny()`](#rb-deny). Requires exactly one destination method call to commit the rule, then returns the `&mut RuleBuilder` so the chain continues. The type is `#[must_use]`: dropping it without a destination call adds no rule.

#### <span className="msb-recv">.</span><span className="msb-hn">ip()</span>

<a id="rd-ip" />

```rust theme={null}
fn ip(self, ip: impl Into<String>) -> &'a mut RuleBuilder
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">cidr()</span>

<a id="rd-cidr" />

```rust theme={null}
fn cidr(self, cidr: impl Into<String>) -> &'a mut RuleBuilder
```

Commit with [`Destination::Cidr`](#destination). Invalid values surface as [`BuildError::InvalidCidr`](#builderror).

#### <span className="msb-recv">.</span><span className="msb-hn">domain()</span>

<a id="rd-domain" />

```rust theme={null}
fn domain(self, domain: impl Into<String>) -> &'a mut RuleBuilder
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">domain\_suffix()</span>

<a id="rd-domain_suffix" />

```rust theme={null}
fn domain_suffix(self, suffix: impl Into<String>) -> &'a mut RuleBuilder
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">group()</span>

<a id="rd-group" />

```rust theme={null}
fn group(self, group: DestinationGroup) -> &'a mut RuleBuilder
```

Commit with [`Destination::Group`](#destination) for callers who already hold a [`DestinationGroup`](#destinationgroup) value.

#### <span className="msb-recv">.</span><span className="msb-hn">any()</span>

<a id="rd-any" />

```rust theme={null}
fn any(self) -> &'a mut RuleBuilder
```

Commit with [`Destination::Any`](#destination): matches every remote.

## NetworkBuilder

Builder for the sandbox's network stack, used in [`SandboxBuilder::network(|n| n...)`](/sdk/rust/sandbox#network). Every setter returns `Self`, so calls chain. Errors accumulated by nested builders cascade up: the outermost `SandboxBuilder::build()` surfaces them as [`MicrosandboxError::NetworkBuilder(BuildError)`](#builderror).

#### <span className="msb-recv">.</span><span className="msb-hn">policy()</span>

```rust theme={null}
fn policy(self, policy: NetworkPolicy) -> Self
```

<Accordion title="Example">
  ```rust theme={null}
  .network(|n| n.policy(NetworkPolicy::builder().default_deny().build()?))
  ```
</Accordion>

Set the network access policy. Pass a preset or a builder-constructed [`NetworkPolicy`](#networkpolicy).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>policy</code><a className="msb-type" href="#networkpolicy">NetworkPolicy</a></div>
    <div className="msb-param-desc">Access policy.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">port()</span>

<a id="nb-port" />

```rust theme={null}
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()`](/sdk/rust/sandbox#port).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host\_port</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_port</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">port\_udp()</span>

```rust theme={null}
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`.

#### <span className="msb-recv">.</span><span className="msb-hn">port\_bind()</span>

```rust theme={null}
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`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host\_bind</code><span className="msb-type">IpAddr</span></div>
    <div className="msb-param-desc">Host bind address.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>host\_port</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_port</code><span className="msb-type">u16</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">port\_udp\_bind()</span>

```rust theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">dns()</span>

```rust theme={null}
fn dns(self, f: impl FnOnce(DnsBuilder) -> DnsBuilder) -> Self
```

<Accordion title="Example">
  ```rust theme={null}
  use microsandbox_network::dns::Nameserver;

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

Configure DNS interception. See [`DnsBuilder`](#dnsbuilder).

#### <span className="msb-recv">.</span><span className="msb-hn">tls()</span>

```rust theme={null}
fn tls(self, f: impl FnOnce(TlsBuilder) -> TlsBuilder) -> Self
```

Configure TLS interception. See [`TlsBuilder`](#tlsbuilder).

#### <span className="msb-recv">.</span><span className="msb-hn">trust\_host\_cas()</span>

```rust theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">max\_connections()</span>

```rust theme={null}
fn max_connections(self, max: usize) -> Self
```

Limit the maximum number of concurrent network connections from the sandbox. Default: `256`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>max</code><span className="msb-type">usize</span></div>
    <div className="msb-param-desc">Maximum concurrent connections.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ipv4\_pool()</span>

```rust theme={null}
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`](#builderror).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pool</code><span className="msb-type">Ipv4Network</span></div>
    <div className="msb-param-desc">IPv4 pool, prefix <code>/30</code> or shorter.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ipv6\_pool()</span>

```rust theme={null}
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`](#builderror).

#### <span className="msb-recv">.</span><span className="msb-hn">interface()</span>

```rust theme={null}
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()`](#ipv4_pool) and [`ipv6_pool()`](#ipv6_pool), which validate the prefix. Unset fields fall back to values derived deterministically from the sandbox slot. See [`InterfaceOverrides`](#interfaceoverrides).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>overrides</code><a className="msb-type" href="#interfaceoverrides">InterfaceOverrides</a></div>
    <div className="msb-param-desc">Guest interface overrides.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">enabled()</span>

```rust theme={null}
fn enabled(self, enabled: bool) -> Self
```

Enable or disable networking. Default: `true`. To fully turn networking off, prefer [`SandboxBuilder::disable_network()`](/sdk/rust/sandbox#disable_network), which also sets the policy to [`NetworkPolicy::none()`](#networkpolicynone).

#### <span className="msb-recv">.</span><span className="msb-hn">on\_secret\_violation()</span>

```rust theme={null}
fn on_secret_violation(
    self,
    f: impl FnOnce(ViolationActionBuilder) -> ViolationActionBuilder,
) -> Self
```

<Accordion title="Example">
  ```rust theme={null}
  .network(|n| n.on_secret_violation(|v| v
      .block_and_log()
      .passthrough_host("api.anthropic.com")
      .passthrough_host_pattern("*.example.com")))
  ```
</Accordion>

Set the sandbox-wide action taken when a secret placeholder is detected in traffic to a host not in the secret's allow list. See [`ViolationActionBuilder`](#violationactionbuilder).

Passthrough hosts receive the placeholder unchanged. They do **not** receive real secret values.

#### <span className="msb-recv">.</span><span className="msb-hn">secret()</span>

```rust theme={null}
fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self
```

Add a secret via a closure builder. Mirrors [`SandboxBuilder::secret()`](/sdk/rust/sandbox#secret). See [`SecretBuilder`](/sdk/rust/secrets#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`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>f</code><a className="msb-type" href="/sdk/rust/secrets#secretbuilder">SecretBuilder</a></div>
    <div className="msb-param-desc">Configure the secret.</div>
  </div>
</div>

## DnsBuilder

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

#### <span className="msb-recv">.</span><span className="msb-hn">nameservers()</span>

```rust theme={null}
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`](#nameserver): a `SocketAddr`, an `IpAddr`, or a parsed string via `"dns.google:53".parse::<Nameserver>()?`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>nameservers</code><span className="msb-type">IntoIterator\<Item = Into\<Nameserver>></span></div>
    <div className="msb-param-desc">Upstream resolvers.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">query\_timeout\_ms()</span>

```rust theme={null}
fn query_timeout_ms(self, ms: u64) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">rebind\_protection()</span>

```rust theme={null}
fn rebind_protection(self, enabled: bool) -> Self
```

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

## TlsBuilder

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

#### <span className="msb-recv">.</span><span className="msb-hn">bypass()</span>

```rust theme={null}
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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pattern</code><span className="msb-type">impl Into\<String></span></div>
    <div className="msb-param-desc">Host glob. Supports exact match and <code>\*.suffix</code> wildcards.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">intercepted\_ports()</span>

```rust theme={null}
fn intercepted_ports(self, ports: Vec<u16>) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">verify\_upstream()</span>

```rust theme={null}
fn verify_upstream(self, verify: bool) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">block\_quic()</span>

```rust theme={null}
fn block_quic(self, block: bool) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">intercept\_ca\_cert()</span>

```rust theme={null}
fn intercept_ca_cert(self, path: impl Into<PathBuf>) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">intercept\_ca\_key()</span>

```rust theme={null}
fn intercept_ca_key(self, path: impl Into<PathBuf>) -> Self
```

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

#### <span className="msb-recv">.</span><span className="msb-hn">upstream\_ca\_cert()</span>

```rust theme={null}
fn upstream_ca_cert(self, path: impl Into<PathBuf>) -> Self
```

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

## ViolationActionBuilder

Builder for secret-violation behavior, used by [`NetworkBuilder::on_secret_violation()`](#on_secret_violation) and [`SecretBuilder::on_violation()`](/sdk/rust/secrets#on_violation). A blocking call (`block`, `block_and_log`, `block_and_terminate`) replaces any accumulated passthrough hosts; passthrough calls accumulate. When passthrough hosts are configured, non-matching hosts use the default action. Every setter returns `Self`. Produces a [`ViolationAction`](#violationaction).

#### <span className="msb-recv">.</span><span className="msb-hn">block()</span>

```rust theme={null}
fn block(self) -> Self
```

Block the request silently.

#### <span className="msb-recv">.</span><span className="msb-hn">block\_and\_log()</span>

```rust theme={null}
fn block_and_log(self) -> Self
```

Block the request and emit a warning log on the host. This is the [`ViolationAction`](#violationaction) default.

#### <span className="msb-recv">.</span><span className="msb-hn">block\_and\_terminate()</span>

```rust theme={null}
fn block_and_terminate(self) -> Self
```

Block the request and terminate the entire sandbox.

#### <span className="msb-recv">.</span><span className="msb-hn">passthrough\_host()</span>

```rust theme={null}
fn passthrough_host(self, host: impl Into<String>) -> Self
```

Allow an exact host to receive secret placeholders unchanged (no substitution).

<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 host.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">passthrough\_host\_pattern()</span>

```rust theme={null}
fn passthrough_host_pattern(self, pattern: impl Into<String>) -> Self
```

Allow hosts matching a wildcard pattern (e.g. `*.example.com`) to receive placeholders unchanged.

#### <span className="msb-recv">.</span><span className="msb-hn">passthrough\_all\_hosts()</span>

```rust theme={null}
fn passthrough_all_hosts(self, i_understand_the_risk: bool) -> Self
```

Allow **any** host to receive placeholders unchanged. Takes effect only when `i_understand_the_risk` is `true`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>i\_understand\_the\_risk</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Must be <code>true</code> to take effect.</div>
  </div>
</div>

## Types

### NetworkPolicy

<p className="msb-backref">Built by <a href="#networkpolicybuilder">NetworkPolicy::builder()</a> · used by <a href="#policy">policy()</a></p>

An ordered rule list plus two per-direction defaults, evaluated first-match-wins. Egress evaluation considers rules where `direction ∈ {Egress, Any}`; ingress considers `{Ingress, Any}`. If no rule matches, the direction-specific default applies. `Default` is [`public_only()`](#networkpolicypublic_only).

| Field            | Type                     | Description                                    |
| ---------------- | ------------------------ | ---------------------------------------------- |
| default\_egress  | [`Action`](#action)      | Action when no egress-applicable rule matches  |
| default\_ingress | [`Action`](#action)      | Action when no ingress-applicable rule matches |
| rules            | `Vec<`[`Rule`](#rule)`>` | Ordered rules; first match wins per direction  |

### Rule

<p className="msb-backref">Held by <a href="#networkpolicy">NetworkPolicy</a></p>

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`](#direction)          | Which evaluator considers this rule |
| destination | [`Destination`](#destination)      | Target filter                       |
| protocols   | `Vec<`[`Protocol`](#protocol)`>`   | Set semantics; empty = any protocol |
| ports       | `Vec<`[`PortRange`](#portrange)`>` | Set semantics; empty = any port     |
| action      | [`Action`](#action)                | What to do on match                 |

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

| Method                             | Description                                                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Rule::allow_egress(destination)`  | Allow rule, direction `Egress`                                                                                                                                                      |
| `Rule::deny_egress(destination)`   | Deny rule, direction `Egress`                                                                                                                                                       |
| `Rule::allow_ingress(destination)` | Allow rule, direction `Ingress`                                                                                                                                                     |
| `Rule::deny_ingress(destination)`  | Deny rule, direction `Ingress`                                                                                                                                                      |
| `Rule::allow_any(destination)`     | Allow rule, direction `Any`                                                                                                                                                         |
| `Rule::deny_any(destination)`      | Deny rule, direction `Any`                                                                                                                                                          |
| `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](/networking/dns#dns-as-egress) |

### Action

<p className="msb-backref">Used by <a href="#rule">Rule</a> · <a href="#networkpolicy">NetworkPolicy</a> · <a href="#default_egress">default\_egress()</a></p>

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

### Direction

<p className="msb-backref">Used by <a href="#rule">Rule</a></p>

| 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

<p className="msb-backref">Held by <a href="#rule">Rule</a> · committed by <a href="#ruledestinationbuilder">RuleDestinationBuilder</a></p>

| 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`](#domainname)`)`            | Match an exact domain (e.g. `example.com`) when a cached hostname for the remote IP equals it |
| `DomainSuffix(`[`DomainName`](#domainname)`)`      | Match the apex domain and every subdomain (e.g. `example.com` and `api.example.com`)          |
| `Group(`[`DestinationGroup`](#destinationgroup)`)` | Match a predefined address group                                                              |

### DestinationGroup

<p className="msb-backref">Held by <a href="#destination">Destination</a> · committed by <a href="#allow_public">RuleBuilder group adders</a></p>

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

<p className="msb-backref">Held by <a href="#rule">Rule</a> · set by <a href="#tcp">RuleBuilder protocol setters</a></p>

| 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`](#builderror).

### PortRange

<p className="msb-backref">Held by <a href="#rule">Rule</a> · added by <a href="#port-1">port()</a> · <a href="#port_range">port\_range()</a></p>

An inclusive port range.

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

| Method                         | Description                           |
| ------------------------------ | ------------------------------------- |
| `PortRange::single(port)`      | Match a single port                   |
| `PortRange::range(start, end)` | Match an inclusive range              |
| `contains(port)`               | Whether `port` falls within the range |

### DomainName

<p className="msb-backref">Held by <a href="#destination">Destination::Domain / DomainSuffix</a></p>

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`](#builderror).

```rust theme={null}
use microsandbox_network::policy::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()`](#build), so callers rarely construct `DomainName` directly.

| Method              | Description                                                                        |
| ------------------- | ---------------------------------------------------------------------------------- |
| `as_str()`          | Borrow the canonical string form                                                   |
| `try_into_suffix()` | Validate for use as a `DomainSuffix`; single-label names (e.g. `com`) are rejected |

### Nameserver

<p className="msb-backref">Used by <a href="#nameservers">nameservers()</a></p>

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

<p className="msb-backref">Used by <a href="#interface">interface()</a></p>

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()`](#ipv4_pool) / [`ipv6_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` |

### BuildError

<p className="msb-backref">Returned by <a href="#build">NetworkPolicyBuilder::build()</a> · wrapped by <a href="#networkbuilder">NetworkBuilder</a></p>

Errors surfaced by the builders' `build()` methods. The same enum covers [`NetworkPolicy::builder()`](#networkpolicybuilder), [`DnsBuilder`](#dnsbuilder), and [`NetworkBuilder`](#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         |
| `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                                        |

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

### ViolationAction

<p className="msb-backref">Built by <a href="#violationactionbuilder">ViolationActionBuilder</a> · used by <a href="#on_secret_violation">on\_secret\_violation()</a></p>

Action taken when a secret placeholder is sent to a disallowed host. Also documented on the [Secrets](/sdk/rust/secrets#violationaction) page, where it pairs with [`SecretBuilder`](/sdk/rust/secrets#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                                        |
| `Passthrough(Vec<`[`HostPattern`](/sdk/rust/secrets#hostpattern)`>)` | `"passthrough"`         | Forward matching hosts with the placeholder unchanged; non-matching hosts use the default action |