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.

Rule	How it applies to DNS
Domain or domain suffix	Matches the requested name directly. Protocol and port filters do not apply.
`Any`	Matches the protocol and port used for the query
`Group::Host`	Matches the gateway that handles the query
IP or CIDR	Does not match because the name has not been resolved yet

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 inspection. DNS rebinding protection is separate from query access. microsandbox rejects private or reserved answers 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

microsandbox returns a local NXDOMAIN response for denied domains and never forwards them to the upstream resolver. The same rules also protect connections that use TLS SNI or a recently resolved IP address.

import { Sandbox } from "microsandbox";

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

let policy = NetworkPolicy::builder()
    .default_allow()
    .egress(|e| e
        .deny_domains(["malware.example.com"])
        .deny_domain_suffixes([".tracking.com"]))
    .build()?;

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

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 "deny@malware.example.com,deny@*.tracking.com"

Pinning nameservers

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. microsandbox resolves hostnames once when the sandbox starts. microsandbox tries resolvers 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.

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();

use microsandbox_network::dns::Nameserver;

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?;

from microsandbox import Network, Sandbox
from microsandbox.types import DnsConfig

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

Transport	Behavior
UDP or TCP on port `53`	Intercepted
DNS over TLS on TCP port `853`	Intercepted when TLS inspection is enabled
DNS over QUIC, mDNS, LLMNR, and NetBIOS-NS	Refused so the guest can fall back to regular DNS
DNS over HTTPS	Treated as normal HTTPS traffic

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. microsandbox uses the lowest TTL across the relevant addresses and alias chain in each DNS answer, with a one-second minimum, for all addresses in that answer. For example, addresses with TTLs of 30 and 120 seconds both get a 30-second lifetime. Later answers retain earlier addresses until they expire and extend only the addresses they contain, so rotating CDN answers do not invalidate connections using an earlier answer. Each sandbox retains up to 16,384 hostname/address bindings in total, with at most 1,024 per hostname shared across IPv4 and IPv6. An address shared by two domains counts twice. If a DNS answer would exceed either limit, microsandbox returns SERVFAIL without adding any of that answer’s addresses or removing existing bindings. Answers containing only existing bindings can still refresh them; expired bindings free space for new answers. 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.

Reference

For exact DNS and network APIs, see TypeScript, Rust, Python, or Go. For CLI fields and flags, see Sandbox configuration and Sandbox commands.

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

Getting Started

Sandboxes

Networking

Deep dive

Troubleshooting

DNS as egress

Blocking domains

Pinning nameservers

DNS over alternative transports

Domain-based policy rules

Reference

​DNS as egress

​Blocking domains

​Pinning nameservers

​DNS over alternative transports

​Domain-based policy rules

​Reference

​Related

DNS as egress

Blocking domains

Pinning nameservers

DNS over alternative transports

Domain-based policy rules

Reference

Related