DNS

Microsandbox handles DNS queries on the host instead of letting the guest contact a resolver directly. This makes domain rules and DNS rebinding protection possible.

DNS as egress

Every DNS query must pass the sandbox's egress policy.

The public, private, and host profiles already allow DNS through the gateway. With a custom deny-by-default policy, add the equivalent of allow_dns() or use allow@dns in the CLI. Otherwise, every lookup will be denied.

DNS over TLS uses TCP port 853 and needs its own allow rule. It also requires TLS interception.

DNS rebinding protection is separate from query access. Private or reserved answers are rejected unless an explicit address rule allows them. An allow-by-default policy does not disable this protection. See Network defenses for the full policy behavior.

Blocking domains

Denied domains receive a local NXDOMAIN response and are never sent to the upstream resolver. The same rules also protect connections that use TLS SNI or a recently resolved IP address.

let sb = Sandbox::builder("safe-agent") .image("python") .network(|n| n.policy(policy)) .create() .await?;

```typescript TypeScript
import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("safe-agent")
  .image("python")
  .network({
    denyDomains: ["malware.example.com"],
    denyDomainSuffixes: [".tracking.com"],
  })
  .create();

from microsandbox import Network, Sandbox

sb = await Sandbox.create(
    "safe-agent",
    image="python",
    network=Network(
        deny_domains=("malware.example.com",),
        deny_domain_suffixes=(".tracking.com",),
    ),
)

sb, err := m.CreateSandbox(ctx, "safe-agent",
    m.WithImage("python"),
    m.WithNetwork(&m.NetworkConfig{
        DenyDomains:        []string{"malware.example.com"},
        DenyDomainSuffixes: []string{".tracking.com"},
    }),
)

msb create python --name safe-agent --net-default allow \
  --net-rule "[email protected],deny@*.tracking.com"

Pinning nameservers

<Tooltip tip="Custom nameservers are not available on Microsandbox Cloud. Cloud sandboxes use platform-managed DNS."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

By default, Microsandbox uses the host's resolver list. Set nameservers when you need specific resolvers.

Nameservers can be IP addresses, hostnames, or either form with a port. Hostnames are resolved once when the sandbox starts.

Resolvers are tried in order. A timeout or connection failure moves to the next resolver. DNS responses such as SERVFAIL and REFUSED do not. Each unreachable resolver can delay the query by up to query_timeout_ms.

let sb = Sandbox::builder("safe-agent") .image("python") .network(|n| n.dns(|d| d .nameservers([ "1.1.1.1".parse::<Nameserver>()?, "1.0.0.1".parse::<Nameserver>()?, ]) .query_timeout_ms(3000) )) .create() .await?;

```typescript TypeScript
import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("safe-agent")
  .image("python")
  .network((n) => n.dns((d) =>
    d.nameservers(["1.1.1.1", "1.0.0.1"])
      .queryTimeoutMs(3000),
  ))
  .create();

from microsandbox import DnsConfig, Network, Sandbox

sb = await Sandbox.create(
    "safe-agent",
    image="python",
    network=Network(
        dns=DnsConfig(
            nameservers=("1.1.1.1", "1.0.0.1"),
            query_timeout_ms=3000,
        ),
    ),
)

timeout := uint64(3000)
sb, err := m.CreateSandbox(ctx, "safe-agent",
    m.WithImage("python"),
    m.WithNetwork(&m.NetworkConfig{
        DNS: &m.DNSConfig{
            Nameservers:    []string{"1.1.1.1", "1.0.0.1"},
            QueryTimeoutMs: &timeout,
        },
    }),
)

msb create python --name safe-agent \
  --dns-nameserver 1.1.1.1 \
  --dns-nameserver 1.0.0.1 \
  --dns-query-timeout-ms 3000

An application can request a specific resolver, such as with dig @1.1.1.1. That request skips the configured default list, but it still has to pass the network policy.

DNS over alternative transports

Domain blocking and rebinding protection apply only to DNS traffic that Microsandbox can identify. Use network rules to control DNS over HTTPS or to restrict which resolvers the guest can reach.

Domain-based policy rules

Microsandbox records the IP addresses returned for each domain. A domain rule matches a later connection only when that sandbox resolved the domain to that IP.

An application that connects directly to a hard-coded IP does not match a domain rule. Use an IP or CIDR rule for that traffic.

See also

• Network defenses explains rebinding protection and DNS-to-IP binding.
• TLS interception explains inspection for HTTPS and DNS over TLS.