diff --git a/AGENTS.md b/AGENTS.md index 911b692..06572ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,12 +75,14 @@ Lessons from building the kits in this repo. Scopes for commits here: kit, scrip - Kits from a third-party publisher need an approved credential binding. sbx asks only in a terminal, so approve once with an interactive sbx run before unattended tests. - sbx 0.45 stops a local sandbox 30 seconds after the last session and ignores long-running@1. Tests keep an idle sbx exec session open. - lstk treats AWS_ENDPOINT_URL as a remote emulator and refuses local commands. The kit's lstk wrapper removes it. -- localhost.localstack.cloud goes through the sandbox proxy unless it is in NO_PROXY, and the proxy resolves it on the host. Never remove the kit's NO_PROXY snippet or deny rules. +- localhost.localstack.cloud goes through the sandbox proxy unless it is in NO_PROXY, and the proxy resolves it on the host. Never remove the kit's NO_PROXY snippet or the loopback deny rules. +- sbx 0.51 resolves only names that a rule allows, and it refuses the DNS lookup of a name that a deny rule lists (sbx policy log: DNS lookup blocked by proxy policy). NO_PROXY does not help, because the name must resolve first. So the kit allows the LocalStack names and never denies them. The deny rule for 127.0.0.0/8 still refuses them at the proxy, because sbx checks the resolved address against CIDR rules. Test this with a listener on the host when you change the rules. +- LocalStack looks up localstack.cloud to find an upstream DNS server. If no rule allows that name, the LocalStack DNS server does not start (LocalStack log: No upstream dns server found), and the LocalStack names do not resolve in the LocalStack container or in Lambda containers. The MCP server AWS client runs awslocal in that container. - The sandbox template sets GODEBUG=tarinsecurepath=0, which breaks AWS Lambda base image pulls. The kit's dockerd wrapper relaxes it for dockerd and the processes that dockerd starts: containerd, which unpacks the layers, and the container shims. - Zero-filled files in a pulled image mean the host disk was full (the sandbox log shows I/O errors on vdd). Check df before long test runs, and prune the lskit builder cache after builds. - A set can only list kits whose descriptor is the same on every platform. docker/sbx-kit-codex 0.155.1 lists extra packages on arm64 and breaks multi-platform set builds. Check both platforms before you change a pinned agent kit. - A project lstk config (.lstk/config.toml or LSKIT_LSTK_CONFIG) belongs to the user. Never rewrite it. The kit adds its defaults as LOCALSTACK_* variables, and only for keys the file does not set. -- sbx network rules match names, not resolved addresses. A deny for localhost does not stop another name that resolves to 127.0.0.1. Say so in the docs when a rule is a partial control. +- sbx 0.45 network rules matched names, not resolved addresses. sbx 0.51 also checks the resolved address against CIDR rules, except behind an upstream proxy that resolves the name. Say so in the docs when a rule is a partial control. - The first login shell of a new sandbox prints the template banner on stdout. Test helpers use bash -c, not bash -lc, when they read command output. - Read an lstk config as TOML, never with a text match. lstk loads it through viper, which also ignores the case of keys, so a text match misses literal strings, inline tables, and keys such as Image. lskit-check-config parses it with smol-toml. - A kit arg with the value latest does not change the text of a build step, so BuildKit keeps using the cached step after a new release. scripts/build.sh passes the current release numbers for lstk and the MCP server. diff --git a/docs/security.md b/docs/security.md index cfeb60c..c20d8b6 100644 --- a/docs/security.md +++ b/docs/security.md @@ -8,7 +8,7 @@ This page tells you what the kit isolates, what it does not isolate, and why. | --- | --- | --- | | Your host files and processes | Yes | The Docker Sandboxes microVM. The agent sees only the workspace that you mount. | | Your AWS accounts | Partly | The sandbox gets no AWS credentials. The AWS tools point at LocalStack. The kit does not block AWS endpoints. | -| A LocalStack or other service on your host | Partly | The kit denies loopback names at the sandbox proxy. Under the `allow-all` policy, another name that resolves to `127.0.0.1` still reaches the host. | +| A LocalStack or other service on your host | Yes, with `sbx` 0.51 | The kit denies loopback names and loopback addresses at the sandbox proxy. `sbx` also refuses a name that resolves to a loopback address. | | Your agent credentials | Yes | Docker Sandboxes keeps them on the host. The sandbox gets a placeholder. | | Your LocalStack auth token | No | The token must be in the sandbox. The agent can read it. | | The sandbox, from files in the workspace | Partly | The agent runs code from the workspace, and a project lstk config runs at boot. The kit limits the images that a project config can start. | @@ -97,20 +97,32 @@ LocalStack or other local services. `localhost.localstack.cloud` and its subdomains resolve to `127.0.0.1`, so a client that sends these names to the proxy reaches the host. -The kit does two things: +The kit does three things: - It adds the LocalStack names to `NO_PROXY` and to the Java proxy bypass list, for agent shells, lstk, and the MCP server. These clients connect directly to the LocalStack in the sandbox. -- It denies `localhost`, `127.0.0.0/8`, `::1`, `host.docker.internal`, - `localhost.localstack.cloud`, and `**.localhost.localstack.cloud` at the - proxy. A request for these names through the proxy gets HTTP 403. - -This stops accidental access. It does not stop an agent that tries on -purpose: the proxy rules match names, so under the `allow-all` policy, any -other name that resolves to `127.0.0.1`, such as `127.0.0.1.nip.io`, still -reaches the host. The `balanced` and `deny-all` policies refuse names that no -rule allows, so they close this path. +- It denies `localhost`, `127.0.0.0/8`, `::1`, and `host.docker.internal` at + the proxy. A request for these targets through the proxy gets HTTP 403. +- It allows `localhost.localstack.cloud` and `**.localhost.localstack.cloud`, + because `sbx` resolves only the names that a rule allows. A direct + connection to these names stays in the sandbox. Through the proxy, `sbx` + checks the address that a name resolves to against the deny rules, so the + rule for `127.0.0.0/8` refuses these names with HTTP 403. + +Do not add the LocalStack names to the deny rules. `sbx` refuses the DNS +lookup of a name that a deny rule lists, and then no client in the sandbox or +in the LocalStack container can resolve the name. + +The kit also allows `localstack.cloud`. LocalStack looks up this name to find +an upstream DNS server. Without it, the LocalStack DNS server does not start, +and the LocalStack names do not resolve in the LocalStack container or in the +containers that LocalStack starts, such as AWS Lambda functions. + +With `sbx` 0.51, the address check also refuses other names that resolve to +`127.0.0.1`, such as `127.0.0.1.nip.io`, under the `allow-all` policy. An +earlier `sbx` matched names only, so use `sbx` 0.51 or later. If `sbx` uses +an upstream proxy that resolves the names, `sbx` checks the name only. ## Docker daemon setting diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d9b70b9..0296e8d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -97,6 +97,36 @@ env profile of the project config, and run `lstk restart`: GATEWAY_LISTEN = "0.0.0.0:4566,0.0.0.0:443" ``` +## A LocalStack hostname does not resolve + +```text +Could not connect to the endpoint URL: "http://s3.localhost.localstack.cloud:4566/" +``` + +`sbx` resolves only the names that a network rule allows, and it refuses the +DNS lookup of a name that a deny rule lists. The kit allows +`localhost.localstack.cloud` and its subdomains, so they resolve to +`127.0.0.1` in the sandbox. Find the rule that refuses the name: + +```console +$ sbx policy check network --sandbox ls-claude localhost.localstack.cloud:4566 +$ sbx policy log ls-claude +``` + +A deny rule for the name in your own policy has this effect, and +`sbx policy log` then shows `DNS lookup blocked by proxy policy`. Remove that +rule. The kit's rule for `127.0.0.0/8` already keeps these names away from +the host. + +In the LocalStack container, the LocalStack DNS server resolves the names. +It starts only if it can look up `localstack.cloud`, which the kit allows. If +the LocalStack log shows this line, a rule refuses that name, and the +LocalStack MCP server cannot connect: + +```text +Error starting the DNS server: No upstream dns server found. +``` + ## Port 4566 is in use on the host If LocalStack also runs on your host, `-p 4566:4566` cannot publish the diff --git a/kits/localstack/localstack.yaml b/kits/localstack/localstack.yaml index 1a40384..b696314 100644 --- a/kits/localstack/localstack.yaml +++ b/kits/localstack/localstack.yaml @@ -76,6 +76,15 @@ capabilities: # LocalStack license activation and product events - api.localstack.cloud:443 - analytics.localstack.cloud:443 + # LocalStack looks up this name to find an upstream DNS server. + # If the lookup fails, the LocalStack DNS server does not start. + - localstack.cloud:443 + # The LocalStack names resolve to 127.0.0.1, which is the sandbox + # for a direct connection. sbx resolves only the names that a rule + # allows. The deny rule for 127.0.0.0/8 still refuses these names + # at the proxy, because sbx also checks the resolved address. + - localhost.localstack.cloud + - "**.localhost.localstack.cloud" # LocalStack image pulls from Docker Hub - registry-1.docker.io:443 - auth.docker.io:443 @@ -102,16 +111,16 @@ capabilities: - us.i.posthog.com:443 deny: # Through the proxy, loopback is the host, which can run its own - # LocalStack. Sandbox clients reach these names directly, because - # NO_PROXY has them (proxy-bypass.sh adds the LocalStack names). - # The rules match names, so a DNS name that resolves to 127.0.0.1 - # still reaches the host under an allow-all policy. + # LocalStack. Sandbox clients reach the LocalStack names directly, + # because NO_PROXY has them (proxy-bypass.sh adds them). + # sbx refuses the DNS lookup of a name that a deny rule lists, so + # the LocalStack names must not be in this list. sbx 0.51 checks + # the address that a name resolves to against the CIDR rules, so + # the loopback rules refuse each name that resolves to loopback. - localhost - 127.0.0.0/8 - "::1/128" - host.docker.internal - - localhost.localstack.cloud - - "**.localhost.localstack.cloud" - type: com.docker.sandbox/lifecycle@1 config: diff --git a/scripts/smoke.sh b/scripts/smoke.sh index a4286fa..5c4ff46 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -66,11 +66,22 @@ check_isolation() { local url run_check "LocalStack hostnames reach the sandbox emulator" in_sandbox \ 'aws --endpoint-url http://localhost.localstack.cloud:4566 s3 ls | grep -q lskit-smoke' + run_check "LocalStack subdomains resolve in the sandbox" in_sandbox \ + 'aws --endpoint-url http://s3.localhost.localstack.cloud:4566 s3 ls | grep -q lskit-smoke' + run_check "LocalStack DNS resolves LocalStack subdomains in its container" check_container_dns for url in "${PROXY_DENIED_URLS[@]}"; do run_check "The proxy refuses $url" check_proxy_refuses "$url" done } +# The LocalStack DNS server starts only if it finds an upstream DNS server, +# and it finds one only if the network policy allows localstack.cloud. +check_container_dns() { + local container + container="$(in_sandbox 'head -n 1 /tmp/localstack-kit/container-name')" + in_sandbox "docker exec $container python3 -c 'import socket; socket.gethostbyname(\"s3.localhost.localstack.cloud\")'" +} + # --noproxy '' makes curl use the proxy even for names in NO_PROXY. check_proxy_refuses() { local status @@ -87,6 +98,7 @@ check_tools() { check_mcp() { run_check "MCP server lists LocalStack tools" check_mcp_tools + run_check "MCP server AWS client reaches LocalStack" check_mcp_aws_client run_check "MCP server is registered with $agent" check_mcp_registration if [[ "$agent" == codex ]]; then run_check "MCP server works with the variables that Codex passes" check_mcp_with_codex_env @@ -100,6 +112,14 @@ check_mcp_tools() { ((tool_count >= 10)) } +# The AWS client runs awslocal in the LocalStack container with the endpoint +# localhost.localstack.cloud. The LocalStack DNS server resolves the name +# there, so this check fails if that server did not start. +check_mcp_aws_client() { + in_sandbox "$(mcp_request_command tools/call '{"name":"localstack-aws-client","arguments":{"command":"s3 ls"}}')" \ + | grep -q lskit-smoke +} + check_mcp_registration() { case "$agent" in claude) in_sandbox 'claude mcp list' | grep -q '^localstack:' ;; @@ -121,6 +141,8 @@ check_restart() { run_check "LocalStack starts again after the sandbox restarts" restart_sandbox run_check "LocalStack answers after the restart" in_sandbox \ 'curl -s -m 5 -o /dev/null -w "%{http_code}" http://localhost:4566/_localstack/health | grep -qx 200' + run_check "LocalStack hostnames resolve after the restart" in_sandbox \ + 'curl -s -m 5 -o /dev/null -w "%{http_code}" http://localhost.localstack.cloud:4566/_localstack/health | grep -qx 200' } restart_sandbox() {