Locking down Claude Code sandbox egress with strictAllowlist

One hostname is not enough

This is the part I could not grasp by reading docs alone.

I had naively assumed that "to push to GitHub, allow github.com; to call the Anthropic API, allow api.anthropic.com" would be enough. The recon results said otherwise.

A single "operation" fanned out to several hosts. That npm serves tarballs from a different host, and that git sometimes reaches codeload.github.com, were things I only noticed by watching the connections directly.

In short, the very premise of "one host per service" was wrong. Had I written the allowlist under that assumption, that midnight stall would have reproduced indefinitely.

Resisting the wildcard temptation

Adding a host every time something leaks is tedious. It is tempting to settle it with a broad wildcard like *.amazonaws.com.

I started to write exactly that. Then my hand stopped. Allowing an entire cloud that happens to host a CDN's tarballs also opens a path to countless unrelated buckets and endpoints. The one line dilutes the reason you added strictAllowlist in the first place.

In the end I chose to accept the occasional miss over a broad wildcard. Fill the allowlist with concrete hostnames, and when it grows, re-run recon and add the diff. I strongly recommend this over convenience wildcards: a decision not to trade away the "safe default" intent for operational ease.

Three steps before you enable it

Rather than switching the setting on in a hurry, this order cut down on accidents.

1. Run the pipeline once through egress-recon.sh without strictAllowlist, recording every destination
2. Drop the recorded hostnames into the allowlist and enable strictAllowlist
3. Watch runs with guard-run.sh and fail loudly the moment an unexpected connection appears (pick the cadence from the measurements below)

Just inserting these three steps replaces "stalls silently in production" with "observed once up front and eliminated."

Config, and making the deny observable

Put the discovered hosts into config. Confirm the exact key names against your version's settings schema (strictAllowlist is new, so the details may still change). I keep this in .claude/settings.json.

// .claude/settings.json (example)
{
  "sandbox": {
    "network": {
      "strictAllowlist": true,
      "allow": [
        "api.anthropic.com",
        "github.com",
        "codeload.github.com",
        "registry.npmjs.org"
      ]
    }
  }
}

On top of that, add observability so a deny is not mistaken for a network outage. Wrap the pipeline once with a thin harness that records, on every run, whether it reached a host outside expectations.

#!/usr/bin/env bash
# guard-run.sh — reconcile hosts touched during a run against the allowlist
set -euo pipefail
ALLOW_FILE="${1:?pass an allowlist file}"; shift
SEEN="$(mktemp)"; trap 'rm -f "$SEEN"' EXIT
 
# use egress-recon.sh inside, collecting destinations
./egress-recon.sh "$@" | awk '{print $1}' | grep -vE '^\(' | sort -u > "$SEEN"
 
# report only destinations not on the allowlist
UNKNOWN="$(comm -23 "$SEEN" <(sort -u "$ALLOW_FILE") || true)"
if [ -n "$UNKNOWN" ]; then
  echo "⚠️ detected connections outside the allowlist:" >&2
  echo "$UNKNOWN" >&2
  # in automation, prefer a loud failure over a silent one
  exit 1
fi
echo "✅ all destinations were within the allowlist"

Once this was in place, I could state in a single log line whether a stall was "the network's fault" or "a gap in the allowlist." The disappearance of pointless re-runs was the change I felt most in my body.

The speed of a failure is a fingerprint

If a deny arrives wearing the face of an outage, then stop reading the face and start reading the speed. That reframing sent me back to measure how long each kind of failure actually takes.

#!/usr/bin/env python3
# probe-failure-shape.py — measure the "shape" of a failure to isolate its cause
# usage: ./probe-failure-shape.py github.com api.anthropic.com 10.255.255.1
import socket, time, errno, statistics, sys
 
def probe(host, port=443, timeout=3.0):
    t0 = time.perf_counter()
    try:
        # resolve and connect on the same path the pipeline uses
        addr = socket.getaddrinfo(host, port, socket.AF_INET, socket.SOCK_STREAM)[0][4]
        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        s.settimeout(timeout)
        s.connect(addr)
        s.close()
        return "connected", (time.perf_counter() - t0) * 1000
    except socket.gaierror as e:
        return f"DNS failure (gaierror {e.errno})", (time.perf_counter() - t0) * 1000
    except socket.timeout:
        # return elapsed time too, so you can see if it pinned to the ceiling
        return "timeout", (time.perf_counter() - t0) * 1000
    except OSError as e:
        return f"errno={e.errno} ({errno.errorcode.get(e.errno, '?')})", (time.perf_counter() - t0) * 1000
 
for host in sys.argv[1:]:
    runs = [probe(host) for _ in range(3)]
    ms = [r[1] for r in runs]
    print(f"{host}\t{runs[0][0]}\tmedian {statistics.median(ms):.2f}ms")

Here are the results with a three-second timeout, three runs per host. These are measurements from my own environment, so the absolute numbers will move elsewhere. What matters is the difference in order of magnitude.

Seeing them side by side is what made it click. The time to failure is itself a fingerprint of the cause.

Well under a millisecond means you reached the peer and were turned away immediately: a closed port, or a RST somewhere on the path. One to two milliseconds means the name never resolved at all, and you should check the DNS path before suspecting the allowlist.

The interesting row is the last one. A failure that pins to the timeout ceiling. Three seconds on a three-second setting, ten on a ten-second setting. A failure that does not vary is not a machine misbehaving. It is a rule someone wrote. When packets are dropped without any reply, the wait is decided entirely by your own ceiling.

That midnight stall wore exactly this face. A genuine network problem varies, failing somewhere short of the ceiling. Landing on the same clean number every single time was the unnatural part. Once you have seen it, a deny and an outage no longer look alike.

Observation has a price tag too

Tracing continuously is not free. Measuring the same HTTPS fetch five times, the bare run had a median of 88.0 ms, while going through strace -f came to 240.9 ms. Roughly 2.7x.

That number changed my mind about running guard-run on every single execution. Right after adding a new tool, plus once a week on a schedule: that cadence absorbs the slowdown while still catching the diff. A safety mechanism that becomes the reason things feel slow eventually gets removed. Mechanisms last longer when their weight is bearable.

Reverse lookups let me down

Earlier in this article I shared a script that "reverse-resolves" destinations. Being honest about it, that was the part where my assumptions were thin.

When I actually ran reverse lookups on the IPs recon collected, neither GitHub's 20.27.177.113 nor Anthropic's 160.79.104.10 returned a PTR record. All three addresses I tried had no reverse entry at all. Cloud provider ranges routinely ship without PTR, and that turns out to be the norm rather than the exception.

There was a more awkward discovery too. Tracing a single git ls-remote surfaced 172.16.10.1 among the destinations. An RFC1918 private address. Not the service at all, but a gateway or proxy sitting on the path.

In other words, recon output contains relay points that were never candidates for the allowlist in the first place. Copying observed IPs straight into an allowlist falls apart right here.

One more reason you cannot write IPs

To be sure, I resolved the main hosts twenty times each and counted unique addresses.

Only registry.npmjs.org, sitting behind a CDN, handed back twelve different addresses in twenty lookups. An allowlist pinned to those IPs would break by the next day. Write allowlists with hostnames. The measurement made the reason concrete.

So I dropped reverse lookups and went the other way: resolve the allowlist candidates forward to build a dictionary, then map observed IPs back to names through it.

#!/usr/bin/env python3
# resolve-map.py — resolve allowlist candidates forward, map observed IPs back to names
# usage: ./resolve-map.py allowlist.txt observed-ips.txt
import socket, sys
 
allow_file, observed_file = sys.argv[1], sys.argv[2]
names = [l.strip() for l in open(allow_file) if l.strip() and not l.startswith("#")]
 
ip2name = {}
for name in names:
    # CDN addresses rotate per lookup, so query repeatedly and grow the set
    for _ in range(8):
        try:
            for info in socket.getaddrinfo(name, 443, socket.AF_INET, socket.SOCK_STREAM):
                ip2name.setdefault(info[4][0], set()).add(name)
        except socket.gaierror:
            print(f"# cannot resolve: {name}", file=sys.stderr)
            break
 
unknown = []
for line in open(observed_file):
    ip = line.strip()
    if not ip:
        continue
    if ip in ip2name:
        print(f"{ip}\t{','.join(sorted(ip2name[ip]))}")
    else:
        unknown.append(ip)
 
for ip in unknown:
    # a relay point, or a genuine gap in the allowlist? a human decides here
    print(f"{ip}\t(matches no name on the allowlist)")
 
sys.exit(1 if unknown else 0)

One IP can map to several names, which is unremarkable on a CDN, so the dictionary values are sets. Whatever fails to match is the remainder that needs human judgment, and in my environment that remainder was a single address: 172.16.10.1. Once you know it is a relay point, it becomes a familiar face you can safely ignore.

Do not let the observation end as a one-off investigation. Keep the path back to names, and updating the allowlist shifts from guessing at additions to applying a diff.

Judgment calls that paid off

A few situational lessons that stuck after a few weeks of running it.

The tighter the lock, the quieter the failure. That is exactly why two things became the crux: observing the hosts you really touch before you lock, and making the deny clearly visible after you lock. The effort before and after the switch is worth more than the single line that enables it.

I am still learning as I run this. If it spares someone taking automation toward a safer default one detour, I would be glad. Thank you for reading.