Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
34 changes: 23 additions & 11 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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

Expand Down
30 changes: 30 additions & 0 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 15 additions & 6 deletions kits/localstack/localstack.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
22 changes: 22 additions & 0 deletions scripts/smoke.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:' ;;
Expand All @@ -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() {
Expand Down