From cfad72b77a4a7a28f72da948a2dd21611bd37b13 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Fri, 13 Nov 2026 17:37:02 -0500 Subject: [PATCH 1/9] fix(kit): resolve localhost.localstack.cloud from /etc/hosts because sbx refuses its DNS lookup --- kits/localstack/files/bin/lskit-map-hostname | 27 ++++++++++++++++++++ kits/localstack/files/bin/lskit-mcp | 10 ++++++++ kits/localstack/files/bin/lskit-start | 1 + kits/localstack/localstack.yaml | 7 +++++ 4 files changed, 45 insertions(+) create mode 100755 kits/localstack/files/bin/lskit-map-hostname diff --git a/kits/localstack/files/bin/lskit-map-hostname b/kits/localstack/files/bin/lskit-map-hostname new file mode 100755 index 0000000..8056840 --- /dev/null +++ b/kits/localstack/files/bin/lskit-map-hostname @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# Maps localhost.localstack.cloud to loopback in a hosts file, so that the +# name resolves without DNS. The kit denies the name at the sandbox proxy, and +# sbx also refuses the DNS lookup of a denied name. +# +# A hosts file has no wildcards, so subdomains such as +# s3.localhost.localstack.cloud get no entry. +# +# Usage: lskit-map-hostname sandbox (must run as root) +# lskit-map-hostname container NAME (the LocalStack container) +set -euo pipefail + +readonly HOSTS_ENTRY="127.0.0.1 localhost.localstack.cloud" +readonly ADD_ENTRY="grep -q -x -F '$HOSTS_ENTRY' /etc/hosts || echo '$HOSTS_ENTRY' >>/etc/hosts" + +main() { + case "${1:-}" in + sandbox) sh -c "$ADD_ENTRY" ;; + container) docker exec -u 0 "${2:?usage: lskit-map-hostname container NAME}" sh -c "$ADD_ENTRY" ;; + *) + echo "usage: lskit-map-hostname sandbox | container NAME" >&2 + exit 2 + ;; + esac +} + +main "$@" diff --git a/kits/localstack/files/bin/lskit-mcp b/kits/localstack/files/bin/lskit-mcp index fbf981c..697c058 100755 --- a/kits/localstack/files/bin/lskit-mcp +++ b/kits/localstack/files/bin/lskit-mcp @@ -25,7 +25,17 @@ main() { export LOCALSTACK_IMAGE_NAME="$image" fi export PATH="$KIT_HOME/bin:$KIT_HOME/node/bin:$PATH" + map_hostname_in "${MAIN_CONTAINER_NAME:-}" exec node "$SERVER_ENTRY" "$@" } +# The AWS client of the server runs awslocal in the LocalStack container with +# the endpoint localhost.localstack.cloud. A container from a later lstk start +# or restart has no hosts entry for the name, so the launcher adds it again. +map_hostname_in() { + if [[ -n "$1" ]]; then + lskit-map-hostname container "$1" >/dev/null 2>&1 || true + fi +} + main "$@" diff --git a/kits/localstack/files/bin/lskit-start b/kits/localstack/files/bin/lskit-start index a93cb15..1902ea6 100755 --- a/kits/localstack/files/bin/lskit-start +++ b/kits/localstack/files/bin/lskit-start @@ -133,6 +133,7 @@ record_emulator() { fi printf '%s\n' "$name" >"$STATE_DIR/container-name" docker inspect -f '{{.Config.Image}}' "$name" >"$STATE_DIR/image" 2>/dev/null || true + lskit-map-hostname container "$name" || echo "note: localhost.localstack.cloud has no hosts entry in $name." } running_emulator_name() { diff --git a/kits/localstack/localstack.yaml b/kits/localstack/localstack.yaml index 1a40384..15a8ba4 100644 --- a/kits/localstack/localstack.yaml +++ b/kits/localstack/localstack.yaml @@ -104,6 +104,8 @@ capabilities: # 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). + # sbx also refuses the DNS lookup of a denied name, so + # lskit-map-hostname puts localhost.localstack.cloud in /etc/hosts. # The rules match names, so a DNS name that resolves to 127.0.0.1 # still reaches the host under an allow-all policy. - localhost @@ -141,6 +143,11 @@ capabilities: [cli] check_for_update_on_startup = false startup: + # sbx refuses the DNS lookup of the names that the deny rules list, + # so the name must resolve from /etc/hosts. + - command: /opt/localstack-kit/bin/lskit-map-hostname sandbox || true + user: "0" + description: Resolve localhost.localstack.cloud to the sandbox without DNS - command: /opt/localstack-kit/bin/lskit-start background: true # Hook variables are deny by default in the spec. sbx 0.45 passes the From 18c452995310ab53ffeaa546a732797329b4c293 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Fri, 13 Nov 2026 17:37:02 -0500 Subject: [PATCH 2/9] test(scripts): check the MCP AWS client and the LocalStack hostname after a restart --- scripts/smoke.sh | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/scripts/smoke.sh b/scripts/smoke.sh index a4286fa..508d595 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -87,6 +87,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 +101,13 @@ check_mcp_tools() { ((tool_count >= 10)) } +# The AWS client runs awslocal in the LocalStack container with the endpoint +# localhost.localstack.cloud, so the name must resolve there. +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 +129,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() { From a020f0d6104cd03330ec5f9cf5d07915a41667a2 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Fri, 13 Nov 2026 17:37:02 -0500 Subject: [PATCH 3/9] docs: explain that LocalStack hostnames resolve from /etc/hosts --- AGENTS.md | 1 + docs/development.md | 4 +++- docs/security.md | 7 +++++++ docs/troubleshooting.md | 20 ++++++++++++++++++++ 4 files changed, 31 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 911b692..e285f49 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,7 @@ Lessons from building the kits in this repo. Scopes for commits here: kit, scrip - 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. +- sbx 0.51 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. lskit-map-hostname writes localhost.localstack.cloud to /etc/hosts in the sandbox and in the LocalStack container. The MCP server AWS client runs awslocal in the container with that name, so the launcher adds the entry again for a container from a later lstk start. - 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. diff --git a/docs/development.md b/docs/development.md index 3e5562b..eec89fc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,7 +9,9 @@ kits/ localstack.dockerfile tools under /opt/localstack-kit context.md instructions for the agent files/bin/ lstk wrapper, startup hook (lskit-start), boot state - (lskit-status), MCP launcher and registration, shims + (lskit-status), MCP launcher and registration, hosts + entry for the LocalStack name (lskit-map-hostname), + shims files/etc/ shell snippet that keeps LocalStack names off the proxy files/usr-local-bin/ dockerd wrapper that lets Docker pull Lambda images localstack-claude/ set: Docker's Claude Code kit and the mixin diff --git a/docs/security.md b/docs/security.md index cfeb60c..05a835b 100644 --- a/docs/security.md +++ b/docs/security.md @@ -106,6 +106,13 @@ The kit does two things: `localhost.localstack.cloud`, and `**.localhost.localstack.cloud` at the proxy. A request for these names through the proxy gets HTTP 403. +`sbx` 0.51 also refuses the DNS lookup of a name that a deny rule lists, so +the LocalStack names do not resolve in the sandbox. The kit writes +`127.0.0.1 localhost.localstack.cloud` to `/etc/hosts` in the sandbox and in +the LocalStack container, and the name then resolves without DNS. A hosts +file has no wildcards, so subdomains such as `s3.localhost.localstack.cloud` +do not resolve. Use `http://localhost:4566`. + 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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d9b70b9..152465b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -97,6 +97,26 @@ 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/" +``` + +The kit denies `localhost.localstack.cloud` and its subdomains at the sandbox +proxy, and `sbx` 0.51 also refuses the DNS lookup of a denied name. +`sbx policy log` shows `DNS lookup blocked by proxy policy`. The kit puts +`localhost.localstack.cloud` in `/etc/hosts` in the sandbox and in the +LocalStack container, so this name resolves. Subdomains do not resolve. Use +`http://localhost:4566`, and path-style addresses for Amazon S3. + +If the LocalStack MCP server cannot connect after you start a LocalStack +container without lstk, add the entry to that container: + +```console +$ lskit-map-hostname container localstack-main +``` + ## Port 4566 is in use on the host If LocalStack also runs on your host, `-p 4566:4566` cannot publish the From 77c426c486e51fcede5ebc317975a0e0c8247710 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 12:43:12 -0500 Subject: [PATCH 4/9] fix(kit): give the LocalStack DNS server the sandbox resolver as its upstream --- kits/localstack/files/bin/lskit-map-hostname | 23 +++++++------------- kits/localstack/files/bin/lskit-mcp | 10 --------- kits/localstack/files/bin/lskit-start | 1 - kits/localstack/files/bin/lstk | 19 ++++++++++++++++ kits/localstack/localstack.yaml | 9 +++++--- 5 files changed, 33 insertions(+), 29 deletions(-) diff --git a/kits/localstack/files/bin/lskit-map-hostname b/kits/localstack/files/bin/lskit-map-hostname index 8056840..42650f2 100755 --- a/kits/localstack/files/bin/lskit-map-hostname +++ b/kits/localstack/files/bin/lskit-map-hostname @@ -1,27 +1,20 @@ #!/usr/bin/env bash -# Maps localhost.localstack.cloud to loopback in a hosts file, so that the -# name resolves without DNS. The kit denies the name at the sandbox proxy, and -# sbx also refuses the DNS lookup of a denied name. +# Maps localhost.localstack.cloud to loopback in the sandbox hosts file, so +# that the name resolves without DNS. The kit denies the name at the sandbox +# proxy, and sbx also refuses the DNS lookup of a denied name. The sandbox +# cannot use the LocalStack DNS server, because /etc/resolv.conf is read-only +# there. # # A hosts file has no wildcards, so subdomains such as -# s3.localhost.localstack.cloud get no entry. +# s3.localhost.localstack.cloud get no entry in the sandbox. # -# Usage: lskit-map-hostname sandbox (must run as root) -# lskit-map-hostname container NAME (the LocalStack container) +# This must run as root. set -euo pipefail readonly HOSTS_ENTRY="127.0.0.1 localhost.localstack.cloud" -readonly ADD_ENTRY="grep -q -x -F '$HOSTS_ENTRY' /etc/hosts || echo '$HOSTS_ENTRY' >>/etc/hosts" main() { - case "${1:-}" in - sandbox) sh -c "$ADD_ENTRY" ;; - container) docker exec -u 0 "${2:?usage: lskit-map-hostname container NAME}" sh -c "$ADD_ENTRY" ;; - *) - echo "usage: lskit-map-hostname sandbox | container NAME" >&2 - exit 2 - ;; - esac + grep -q -x -F "$HOSTS_ENTRY" /etc/hosts || echo "$HOSTS_ENTRY" >>/etc/hosts } main "$@" diff --git a/kits/localstack/files/bin/lskit-mcp b/kits/localstack/files/bin/lskit-mcp index 697c058..fbf981c 100755 --- a/kits/localstack/files/bin/lskit-mcp +++ b/kits/localstack/files/bin/lskit-mcp @@ -25,17 +25,7 @@ main() { export LOCALSTACK_IMAGE_NAME="$image" fi export PATH="$KIT_HOME/bin:$KIT_HOME/node/bin:$PATH" - map_hostname_in "${MAIN_CONTAINER_NAME:-}" exec node "$SERVER_ENTRY" "$@" } -# The AWS client of the server runs awslocal in the LocalStack container with -# the endpoint localhost.localstack.cloud. A container from a later lstk start -# or restart has no hosts entry for the name, so the launcher adds it again. -map_hostname_in() { - if [[ -n "$1" ]]; then - lskit-map-hostname container "$1" >/dev/null 2>&1 || true - fi -} - main "$@" diff --git a/kits/localstack/files/bin/lskit-start b/kits/localstack/files/bin/lskit-start index 1902ea6..a93cb15 100755 --- a/kits/localstack/files/bin/lskit-start +++ b/kits/localstack/files/bin/lskit-start @@ -133,7 +133,6 @@ record_emulator() { fi printf '%s\n' "$name" >"$STATE_DIR/container-name" docker inspect -f '{{.Config.Image}}' "$name" >"$STATE_DIR/image" 2>/dev/null || true - lskit-map-hostname container "$name" || echo "note: localhost.localstack.cloud has no hosts entry in $name." } running_emulator_name() { diff --git a/kits/localstack/files/bin/lstk b/kits/localstack/files/bin/lstk index 8d5dcc8..fc97a64 100755 --- a/kits/localstack/files/bin/lstk +++ b/kits/localstack/files/bin/lstk @@ -10,12 +10,31 @@ readonly LSTK_BINARY=/opt/localstack-kit/lstk/lstk readonly ACTIVE_CONFIG_FILE=/tmp/localstack-kit/config-path main() { + export_dns_upstream if needs_active_config "$@"; then set -- --config "$(head -n 1 "$ACTIVE_CONFIG_FILE")" "$@" fi exec env -u AWS_ENDPOINT_URL "$LSTK_BINARY" "$@" } +# LocalStack runs a DNS server that resolves localhost.localstack.cloud and +# its subdomains in the LocalStack container and in the containers that +# LocalStack starts. The server starts only if it finds an upstream DNS +# server, and it finds one by a lookup that the sandbox resolver refuses. So +# the wrapper names the sandbox resolver as the upstream. The sandbox network +# policy still applies to each lookup that LocalStack forwards. lstk passes +# LOCALSTACK_* variables to the container. +export_dns_upstream() { + local resolver + if [[ -n "${LOCALSTACK_DNS_SERVER:-}" || -n "${DNS_SERVER:-}" ]]; then + return + fi + resolver="$(awk '$1 == "nameserver" && $2 ~ /^[0-9.]+$/ { print $2; exit }' /etc/resolv.conf 2>/dev/null)" + if [[ -n "$resolver" ]]; then + export LOCALSTACK_DNS_SERVER="$resolver" + fi +} + # lstk reads ./.lstk/config.toml, then ~/.config/lstk/config.toml. Outside the # project root, that can be a different config from the one the sandbox # started LocalStack with, so the wrapper passes that config. diff --git a/kits/localstack/localstack.yaml b/kits/localstack/localstack.yaml index 15a8ba4..4e013ca 100644 --- a/kits/localstack/localstack.yaml +++ b/kits/localstack/localstack.yaml @@ -104,7 +104,9 @@ capabilities: # 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). - # sbx also refuses the DNS lookup of a denied name, so + # sbx also refuses the DNS lookup of a denied name. In the + # LocalStack container, the LocalStack DNS server resolves the + # names (the lstk wrapper gives it an upstream). In the sandbox, # lskit-map-hostname puts localhost.localstack.cloud in /etc/hosts. # The rules match names, so a DNS name that resolves to 127.0.0.1 # still reaches the host under an allow-all policy. @@ -144,8 +146,9 @@ capabilities: check_for_update_on_startup = false startup: # sbx refuses the DNS lookup of the names that the deny rules list, - # so the name must resolve from /etc/hosts. - - command: /opt/localstack-kit/bin/lskit-map-hostname sandbox || true + # and /etc/resolv.conf is read-only in the sandbox, so the name must + # resolve from /etc/hosts there. + - command: /opt/localstack-kit/bin/lskit-map-hostname || true user: "0" description: Resolve localhost.localstack.cloud to the sandbox without DNS - command: /opt/localstack-kit/bin/lskit-start From e4cbced165c19f1c8510760f59452277d581c217 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 12:43:12 -0500 Subject: [PATCH 5/9] test(scripts): check that LocalStack DNS resolves subdomains in its container --- scripts/smoke.sh | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/scripts/smoke.sh b/scripts/smoke.sh index 508d595..ce67d37 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -66,11 +66,19 @@ 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 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 has an upstream DNS server. +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 @@ -102,7 +110,8 @@ check_mcp_tools() { } # The AWS client runs awslocal in the LocalStack container with the endpoint -# localhost.localstack.cloud, so the name must resolve there. +# localhost.localstack.cloud. The LocalStack DNS server resolves the name +# there, so this check fails if that server has no upstream. check_mcp_aws_client() { in_sandbox "$(mcp_request_command tools/call '{"name":"localstack-aws-client","arguments":{"command":"s3 ls"}}')" \ | grep -q lskit-smoke From 525e49c34e6e94475cfd1137ad429a50d0f4cf45 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 12:43:12 -0500 Subject: [PATCH 6/9] docs: explain how LocalStack hostnames resolve in the container and in the sandbox --- AGENTS.md | 2 +- docs/development.md | 9 +++++---- docs/security.md | 19 ++++++++++++++----- docs/troubleshooting.md | 27 +++++++++++++++++++++------ 4 files changed, 41 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e285f49..94dd8eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,7 +76,7 @@ Lessons from building the kits in this repo. Scopes for commits here: kit, scrip - 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. -- sbx 0.51 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. lskit-map-hostname writes localhost.localstack.cloud to /etc/hosts in the sandbox and in the LocalStack container. The MCP server AWS client runs awslocal in the container with that name, so the launcher adds the entry again for a container from a later lstk start. +- sbx 0.51 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. The sandbox resolver answers only names that a rule allows, so LocalStack finds no upstream and its DNS server does not start (LocalStack log: No upstream dns server found). The lstk wrapper sets LOCALSTACK_DNS_SERVER to the sandbox resolver, and the LocalStack DNS server then resolves the LocalStack names in the LocalStack container and in Lambda containers. The MCP server AWS client runs awslocal in that container. /etc/resolv.conf is read-only in the sandbox, so lskit-map-hostname writes localhost.localstack.cloud to /etc/hosts there. - 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. diff --git a/docs/development.md b/docs/development.md index eec89fc..45f2f9c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,10 +8,11 @@ kits/ localstack.yaml kit descriptor: args, network rules, hooks, context localstack.dockerfile tools under /opt/localstack-kit context.md instructions for the agent - files/bin/ lstk wrapper, startup hook (lskit-start), boot state - (lskit-status), MCP launcher and registration, hosts - entry for the LocalStack name (lskit-map-hostname), - shims + files/bin/ lstk wrapper (also sets the LocalStack DNS upstream), + startup hook (lskit-start), boot state + (lskit-status), MCP launcher and registration, + sandbox hosts entry for the LocalStack name + (lskit-map-hostname), shims files/etc/ shell snippet that keeps LocalStack names off the proxy files/usr-local-bin/ dockerd wrapper that lets Docker pull Lambda images localstack-claude/ set: Docker's Claude Code kit and the mixin diff --git a/docs/security.md b/docs/security.md index 05a835b..b80e840 100644 --- a/docs/security.md +++ b/docs/security.md @@ -107,11 +107,20 @@ The kit does two things: proxy. A request for these names through the proxy gets HTTP 403. `sbx` 0.51 also refuses the DNS lookup of a name that a deny rule lists, so -the LocalStack names do not resolve in the sandbox. The kit writes -`127.0.0.1 localhost.localstack.cloud` to `/etc/hosts` in the sandbox and in -the LocalStack container, and the name then resolves without DNS. A hosts -file has no wildcards, so subdomains such as `s3.localhost.localstack.cloud` -do not resolve. Use `http://localhost:4566`. +the sandbox resolver does not resolve the LocalStack names. The kit resolves +them in two places: + +- In the LocalStack container and in the containers that LocalStack starts, + such as AWS Lambda functions, the LocalStack DNS server resolves + `localhost.localstack.cloud` and its subdomains. The kit sets the sandbox + resolver as the upstream of this server (`DNS_SERVER`). LocalStack forwards + all other lookups to the sandbox resolver, so the network policy still + applies to them. +- In the sandbox, `/etc/resolv.conf` is read-only, so the sandbox cannot use + the LocalStack DNS server. The kit writes + `127.0.0.1 localhost.localstack.cloud` to `/etc/hosts`. A hosts file has no + wildcards, so subdomains such as `s3.localhost.localstack.cloud` do not + resolve in the sandbox. Use `http://localhost:4566`. 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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 152465b..52a5dd0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -105,18 +105,33 @@ Could not connect to the endpoint URL: "http://s3.localhost.localstack.cloud:456 The kit denies `localhost.localstack.cloud` and its subdomains at the sandbox proxy, and `sbx` 0.51 also refuses the DNS lookup of a denied name. -`sbx policy log` shows `DNS lookup blocked by proxy policy`. The kit puts -`localhost.localstack.cloud` in `/etc/hosts` in the sandbox and in the -LocalStack container, so this name resolves. Subdomains do not resolve. Use +`sbx policy log` shows `DNS lookup blocked by proxy policy`. + +In the sandbox, the kit puts `localhost.localstack.cloud` in `/etc/hosts`, so +this name resolves. Subdomains do not resolve in the sandbox. Use `http://localhost:4566`, and path-style addresses for Amazon S3. -If the LocalStack MCP server cannot connect after you start a LocalStack -container without lstk, add the entry to that container: +In the LocalStack container, the LocalStack DNS server resolves the name and +its subdomains. The server needs an upstream DNS server, and the kit's lstk +wrapper sets the sandbox resolver as the upstream. Without an upstream, the +LocalStack log shows this line, and the LocalStack MCP server cannot connect: + +```text +Error starting the DNS server: No upstream dns server found. +``` + +This occurs if you start a LocalStack container without the kit's lstk. Give +that container the first `nameserver` address from `/etc/resolv.conf` of the +sandbox: ```console -$ lskit-map-hostname container localstack-main +$ docker run -e DNS_SERVER=172.17.0.0 ... ``` +The wrapper sets `LOCALSTACK_DNS_SERVER`, and this value replaces a +`DNS_SERVER` setting in an lstk config. To use a different upstream, create +the sandbox with `-e LOCALSTACK_DNS_SERVER=
`. + ## Port 4566 is in use on the host If LocalStack also runs on your host, `-p 4566:4566` cannot publish the From c33c9d7409a206f4b11a6c186f5922b442926330 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 22:27:37 -0500 Subject: [PATCH 7/9] fix(kit): allow the LocalStack hostnames and localstack.cloud so that sbx resolves them --- kits/localstack/files/bin/lskit-map-hostname | 20 ------------- kits/localstack/files/bin/lstk | 19 ------------ kits/localstack/localstack.yaml | 31 ++++++++++---------- 3 files changed, 15 insertions(+), 55 deletions(-) delete mode 100755 kits/localstack/files/bin/lskit-map-hostname diff --git a/kits/localstack/files/bin/lskit-map-hostname b/kits/localstack/files/bin/lskit-map-hostname deleted file mode 100755 index 42650f2..0000000 --- a/kits/localstack/files/bin/lskit-map-hostname +++ /dev/null @@ -1,20 +0,0 @@ -#!/usr/bin/env bash -# Maps localhost.localstack.cloud to loopback in the sandbox hosts file, so -# that the name resolves without DNS. The kit denies the name at the sandbox -# proxy, and sbx also refuses the DNS lookup of a denied name. The sandbox -# cannot use the LocalStack DNS server, because /etc/resolv.conf is read-only -# there. -# -# A hosts file has no wildcards, so subdomains such as -# s3.localhost.localstack.cloud get no entry in the sandbox. -# -# This must run as root. -set -euo pipefail - -readonly HOSTS_ENTRY="127.0.0.1 localhost.localstack.cloud" - -main() { - grep -q -x -F "$HOSTS_ENTRY" /etc/hosts || echo "$HOSTS_ENTRY" >>/etc/hosts -} - -main "$@" diff --git a/kits/localstack/files/bin/lstk b/kits/localstack/files/bin/lstk index fc97a64..8d5dcc8 100755 --- a/kits/localstack/files/bin/lstk +++ b/kits/localstack/files/bin/lstk @@ -10,31 +10,12 @@ readonly LSTK_BINARY=/opt/localstack-kit/lstk/lstk readonly ACTIVE_CONFIG_FILE=/tmp/localstack-kit/config-path main() { - export_dns_upstream if needs_active_config "$@"; then set -- --config "$(head -n 1 "$ACTIVE_CONFIG_FILE")" "$@" fi exec env -u AWS_ENDPOINT_URL "$LSTK_BINARY" "$@" } -# LocalStack runs a DNS server that resolves localhost.localstack.cloud and -# its subdomains in the LocalStack container and in the containers that -# LocalStack starts. The server starts only if it finds an upstream DNS -# server, and it finds one by a lookup that the sandbox resolver refuses. So -# the wrapper names the sandbox resolver as the upstream. The sandbox network -# policy still applies to each lookup that LocalStack forwards. lstk passes -# LOCALSTACK_* variables to the container. -export_dns_upstream() { - local resolver - if [[ -n "${LOCALSTACK_DNS_SERVER:-}" || -n "${DNS_SERVER:-}" ]]; then - return - fi - resolver="$(awk '$1 == "nameserver" && $2 ~ /^[0-9.]+$/ { print $2; exit }' /etc/resolv.conf 2>/dev/null)" - if [[ -n "$resolver" ]]; then - export LOCALSTACK_DNS_SERVER="$resolver" - fi -} - # lstk reads ./.lstk/config.toml, then ~/.config/lstk/config.toml. Outside the # project root, that can be a different config from the one the sandbox # started LocalStack with, so the wrapper passes that config. diff --git a/kits/localstack/localstack.yaml b/kits/localstack/localstack.yaml index 4e013ca..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,20 +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). - # sbx also refuses the DNS lookup of a denied name. In the - # LocalStack container, the LocalStack DNS server resolves the - # names (the lstk wrapper gives it an upstream). In the sandbox, - # lskit-map-hostname puts localhost.localstack.cloud in /etc/hosts. - # 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: @@ -145,12 +150,6 @@ capabilities: [cli] check_for_update_on_startup = false startup: - # sbx refuses the DNS lookup of the names that the deny rules list, - # and /etc/resolv.conf is read-only in the sandbox, so the name must - # resolve from /etc/hosts there. - - command: /opt/localstack-kit/bin/lskit-map-hostname || true - user: "0" - description: Resolve localhost.localstack.cloud to the sandbox without DNS - command: /opt/localstack-kit/bin/lskit-start background: true # Hook variables are deny by default in the spec. sbx 0.45 passes the From 0a2c8354bab25beabe87bc4389ac8926fcbb71b0 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 22:27:37 -0500 Subject: [PATCH 8/9] test(scripts): check that LocalStack subdomains resolve in the sandbox --- scripts/smoke.sh | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/smoke.sh b/scripts/smoke.sh index ce67d37..5c4ff46 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -66,13 +66,16 @@ 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 has an upstream DNS server. +# 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')" @@ -111,7 +114,7 @@ check_mcp_tools() { # 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 has no upstream. +# 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 From 8a5f9b2ca56036b2c75ad925ce51f6f77a833267 Mon Sep 17 00:00:00 2001 From: Patrick Lafond Date: Sun, 15 Nov 2026 22:27:37 -0500 Subject: [PATCH 9/9] docs: explain the network rules that let LocalStack hostnames resolve --- AGENTS.md | 7 +++--- docs/development.md | 7 ++---- docs/security.md | 50 +++++++++++++++++++---------------------- docs/troubleshooting.md | 39 ++++++++++++++------------------ 4 files changed, 46 insertions(+), 57 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 94dd8eb..06572ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,13 +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. -- sbx 0.51 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. The sandbox resolver answers only names that a rule allows, so LocalStack finds no upstream and its DNS server does not start (LocalStack log: No upstream dns server found). The lstk wrapper sets LOCALSTACK_DNS_SERVER to the sandbox resolver, and the LocalStack DNS server then resolves the LocalStack names in the LocalStack container and in Lambda containers. The MCP server AWS client runs awslocal in that container. /etc/resolv.conf is read-only in the sandbox, so lskit-map-hostname writes localhost.localstack.cloud to /etc/hosts there. +- 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/development.md b/docs/development.md index 45f2f9c..3e5562b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,11 +8,8 @@ kits/ localstack.yaml kit descriptor: args, network rules, hooks, context localstack.dockerfile tools under /opt/localstack-kit context.md instructions for the agent - files/bin/ lstk wrapper (also sets the LocalStack DNS upstream), - startup hook (lskit-start), boot state - (lskit-status), MCP launcher and registration, - sandbox hosts entry for the LocalStack name - (lskit-map-hostname), shims + files/bin/ lstk wrapper, startup hook (lskit-start), boot state + (lskit-status), MCP launcher and registration, shims files/etc/ shell snippet that keeps LocalStack names off the proxy files/usr-local-bin/ dockerd wrapper that lets Docker pull Lambda images localstack-claude/ set: Docker's Claude Code kit and the mixin diff --git a/docs/security.md b/docs/security.md index b80e840..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,36 +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. - -`sbx` 0.51 also refuses the DNS lookup of a name that a deny rule lists, so -the sandbox resolver does not resolve the LocalStack names. The kit resolves -them in two places: - -- In the LocalStack container and in the containers that LocalStack starts, - such as AWS Lambda functions, the LocalStack DNS server resolves - `localhost.localstack.cloud` and its subdomains. The kit sets the sandbox - resolver as the upstream of this server (`DNS_SERVER`). LocalStack forwards - all other lookups to the sandbox resolver, so the network policy still - applies to them. -- In the sandbox, `/etc/resolv.conf` is read-only, so the sandbox cannot use - the LocalStack DNS server. The kit writes - `127.0.0.1 localhost.localstack.cloud` to `/etc/hosts`. A hosts file has no - wildcards, so subdomains such as `s3.localhost.localstack.cloud` do not - resolve in the sandbox. Use `http://localhost:4566`. - -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 52a5dd0..0296e8d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -103,35 +103,30 @@ GATEWAY_LISTEN = "0.0.0.0:4566,0.0.0.0:443" Could not connect to the endpoint URL: "http://s3.localhost.localstack.cloud:4566/" ``` -The kit denies `localhost.localstack.cloud` and its subdomains at the sandbox -proxy, and `sbx` 0.51 also refuses the DNS lookup of a denied name. -`sbx policy log` shows `DNS lookup blocked by proxy policy`. +`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: -In the sandbox, the kit puts `localhost.localstack.cloud` in `/etc/hosts`, so -this name resolves. Subdomains do not resolve in the sandbox. Use -`http://localhost:4566`, and path-style addresses for Amazon S3. +```console +$ sbx policy check network --sandbox ls-claude localhost.localstack.cloud:4566 +$ sbx policy log ls-claude +``` -In the LocalStack container, the LocalStack DNS server resolves the name and -its subdomains. The server needs an upstream DNS server, and the kit's lstk -wrapper sets the sandbox resolver as the upstream. Without an upstream, the -LocalStack log shows this line, and the LocalStack MCP server cannot connect: +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. ``` -This occurs if you start a LocalStack container without the kit's lstk. Give -that container the first `nameserver` address from `/etc/resolv.conf` of the -sandbox: - -```console -$ docker run -e DNS_SERVER=172.17.0.0 ... -``` - -The wrapper sets `LOCALSTACK_DNS_SERVER`, and this value replaces a -`DNS_SERVER` setting in an lstk config. To use a different upstream, create -the sandbox with `-e LOCALSTACK_DNS_SERVER=
`. - ## Port 4566 is in use on the host If LocalStack also runs on your host, `-p 4566:4566` cannot publish the