Skip to content

feat: run AWS CLI commands with the official AWS CLI v2 through lstk aws - #137

Draft
joe4dev wants to merge 5 commits into
mainfrom
devx-1330-mcp-server-run-aws-cli-commands-with-the-official
Draft

joe4dev wants to merge 5 commits into
mainfrom
devx-1330-mcp-server-run-aws-cli-commands-with-the-official

Conversation

@joe4dev

@joe4dev joe4dev commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Linear: DEVX-1330 · related: DEVX-1331 (lstk fix this PR works around)

Summary

localstack-aws-client and the deployer's create-stack/delete-stack ran awslocal inside the LocalStack container. They now run the official AWS CLI v2 through lstk aws where the server runs: on the user's machine with npx, or in the server's Docker image. The deployer already runs Terraform, CDK and SAM through lstk the same way.

awslocal is AWS CLI v1 (1.46.3) that the LocalStack image happens to install, and the image's Dockerfile has a TODO to remove it.

 src/tools/localstack-aws-client.ts, src/tools/localstack-deployer.ts
-  docker exec <localstack> awslocal …
+  runLstkAws(…)                        src/lib/aws/lstk-aws.ts
 src/lib/aws/child-env.ts               (new) allow-listed env, private HOME
 src/lib/azure/egress-guard.ts          relayHttp: plain HTTP to LocalStack only
 src/lib/aws/local-paths.ts             (new) LOCALSTACK_AWS_WORKDIR and the path rule
 src/lib/aws/aws-cli-sanitizer.ts       argv checks and the deny list
 Dockerfile                             FROM amazon/aws-cli (trimmed), mandoc

Decision: confine the CLI with rules (option B)

Inside the LocalStack container, awslocal could not see the user's files, AWS credentials, ~/.aws config or programs. Run where the server runs, the CLI can. So an agent's command could, without these rules, reach real AWS with real credentials, read ~/.aws/credentials, overwrite ~/.zshrc, or start ssh.

We chose to keep the CLI where the server runs and confine it with a minimal set of rules, accepting that the rules on files and commands are a model of the CLI's behavior rather than a hard boundary.

A. Throwaway container per command B. Rules (chosen) C. Allow-list API operations
How Run lstk aws in a container that mounts only the workdir, read-only root, no docker.sock, network only to LocalStack Allow-listed env + private HOME + egress guard, plus path rule and deny list Allow modeled API operations and a vetted few customizations (s3 ls/cp/mv/rm/sync/mb/rb/presign); local files only through file:// and outfiles
Pros A real boundary, like awslocal had; files and programs confined without modeling the CLI No extra image or container start; works in npx and Docker mode as is; small code Smaller surface to reason about than a deny list
Cons ~0.5–1 s per command; needs a small linux image with lstk + aws to publish and pull; more moving parts in npx mode File and command rules model the CLI: six review rounds each found gaps in them, so expect more Drops less common commands; still models CLI parsing (abbreviations, $VARS, shorthand)

The network side is structural and has held since review round 4: the private HOME and env mean the CLI never sees real credentials or the user's AWS config, and the egress guard refuses every host but LocalStack, whatever route the CLI takes.

The rules

  1. Environment (child-env.ts). Built from an allow-list. HOME is private, so there's no user ~/.aws: no profiles, credential_process, plugins, aliases or history. AWS_* and LSTK_* are dropped. The endpoint, test credentials and region are pinned, AWS_IGNORE_CONFIGURED_ENDPOINT_URLS=false, and Multi-Region Access Points are off.
  2. Egress guard (egress-guard.ts, shared with the Azure tool). Every request goes through it as the HTTP(S) proxy. It relays plain HTTP to the LocalStack host and its subdomains on the LocalStack port, and refuses every other host. A refusal fails the tool call.
    • LocalStack is deliberately not in NO_PROXY: botocore picks a client's proxy from its configured endpoint, so a request rewritten to another host would bypass the guard.
  3. Command checks (aws-cli-sanitizer.ts, on the parsed argv).
    • The existing checks: no shell syntax and no ...
    • No --endpoint-url/--profile or their abbreviations, and no lstk --config.
    • help only as the end of a pure help request (lstk bug, DEVX-1331).
    • A deny list of commands that act on the machine: update, logins, ssh/sessions/tunnels, codeartifact login, eks update-kubeconfig, cloudformation package, deploy push, gamelift upload-build, lambda-web, lightsail push-container-image, history, wizard, cli-dev, and streams that never end.
  4. Local files (local-paths.ts). The CLI runs in LOCALSTACK_AWS_WORKDIR. It defaults to the server's directory, with none in the Docker image or when the server runs in / or the home directory. Every value is judged by its shape, not its option name, because the CLI accepts abbreviated option names:
    • Relative values must resolve, symlinks followed, inside that directory.
    • Absolute and ~ values must be inside the workdir, unless their first directory doesn't exist on the machine (a name such as /aws/lambda/f).
    • file:// values and shorthand @= loads are always paths.
    • A leading $VAR is refused, because the CLI expands it in paths.
    • s3 cp/mv/sync get --no-follow-symlinks, which needs AWS CLI ≥ 2.37.7.

Evidence

  • yarn test: 564 passed, including:
    • Tool tests against a fake lstk/aws.
    • A fake lstk that reads stdin and sends requests through the guard. It shows the private HOME, the dropped AWS_PROFILE/AWS_ENDPOINT_URL_S3/LSTK_ENDPOINT_URL, relays to LocalStack subdomains with the Host header kept, and a blocked s3.amazonaws.com.
    • Path-rule and sanitizer cases for every bypass found in review.
  • End to end with the real lstk 1.4.5 and aws 2.40.4 against a fake LocalStack, on the host and in the image built from this branch (aws-cli/2.39.3, lstk 1.4.4). Every exploit from the six review rounds is refused, everyday commands work, and help renders.
  • New live tests in tests/mcp/tools.spec.mjs:
    • The AWS client reaches the LocalStack the server started, through lstk aws.
    • The deployer creates and deletes a CloudFormation stack.
    • The AWS client refuses MRAP, endpoint and path escapes and update.
    • Not run yet: needs LOCALSTACK_AUTH_TOKEN.
  • tsc --noEmit clean.

Merge Danger

Door: two-way

Blast Radius: every AWS CLI call an agent makes through the server, and the image size

  • The AWS CLI now runs on the user's machine (npx) or in the server container, confined by the rules above instead of by the LocalStack container. The file and command rules are best effort (see the decision).
  • npx users need lstk and AWS CLI ≥ 2.37.7 on the PATH.
  • Local files must be in LOCALSTACK_AWS_WORKDIR, which defaults to the server's directory. In the Docker image there is none unless it's set.
  • The image grows by about 250 MB unpacked (the AWS CLI's frozen Python and service models; examples and aws_completer are trimmed). The FROM images now wait 30 days for updates, because the AWS CLI releases almost daily.
  • Responses are unchanged, except that lstk's "No AWS profile found" note is dropped and help pages render as plain text.

TODO

  • Run yarn test:mcp:tools and tests/docker/validate-image.mjs with an auth token.
  • Decide whether the live test "reaches the LocalStack the server started" may stop and start the developer's instance when run locally. It does, to make the server start it.
  • Known and accepted: the deployer's create-stack reads templatePath from anywhere, as before this PR (the deployer works on any project directory).
  • Pre-existing, not from this PR: the SIGKILL fallback in src/core/command-runner.ts never fires, because child.killed is already true after SIGTERM. lstk does stop aws on SIGTERM.
  • When DEVX-1331 ships in lstk, the help-token rule can go.

🤖 Generated with Claude Code

joe4dev and others added 5 commits November 19, 2026 17:07
The AWS client tool and the deployer's create-stack/delete-stack actions ran
awslocal inside the LocalStack container. They now run the official AWS CLI v2
through `lstk aws` where the server runs, like Terraform, CDK and SAM.

- Docker image: AWS CLI v2 copied from amazon/aws-cli (trimmed), Dependabot-managed
- CI host-tools action exports the same CLI
- Command checks keep every command on LocalStack (help tokens, option prefixes,
  stack names); the CLI gets no stdin
- Tool tests, plus a live create/delete-stack test

Towards DEVX-1330

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…workdir

- Run lstk aws with an allow-listed environment and a private HOME: no user
  ~/.aws (profiles, credential_process, plugins, aliases, history), no AWS_*
  or LSTK_* from the server's environment
- Route every request through the egress guard, which relays plain HTTP to
  LocalStack and refuses other hosts; disable Multi-Region Access Points
- Hold local paths (s3 cp, file://, --body, outfiles) to LOCALSTACK_AWS_WORKDIR
- Refuse commands that act on this machine (update, login, sso login,
  history, ssm start-session, codeartifact login, cloudformation package, ...)
- Render help with mandoc in the image; strip overstrike
- 30-day cooldown for the Dockerfile images; unique live-test names

Towards DEVX-1330

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Round 4 found `--file-path`, `--priv-launch-key` and `--private-key` exempt as
name options. The path rule now lists the options that take local files from
the AWS CLI v2 source (customizations and streaming blobs), checks a name-like
option's value when it names an existing file, and checks every file:// inside
a value (shorthand `key@=fileb://…`). Refuses `wizard`, `logs start-live-tail`
and `logs tail --follow`.

Towards DEVX-1330

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t global options

Round 5 found that a quoted `..` passed the raw-string traversal check and that
relative positional paths were never resolved, so `s3 cp '../x'` read and wrote
outside the workdir (and, without one, could write an alias into the private
HOME). It also found that a global option before the operation
(`cloudformation --no-cli-pager package`) shifted the deny list's word positions.

- Check `..` on the parsed argv
- Resolve every value but a name or URL, relative ones too, against the
  directory the CLI runs in, following symlinks; never allow the private HOME
- Match a denied operation at any word after the service
- Refuse lstk's own --config; add --no-follow-symlinks to s3 cp/mv/sync
- Live test: the AWS client reaches the LocalStack the server started

Towards DEVX-1330

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Round 6 found that option names prove nothing (the CLI accepts abbreviations:
`--public-key` is `--public-key-outfile`), that the CLI expands `$VARS` in
paths, and more commands that act on the machine.

- Judge every value by its shape: relative ones resolve inside the directory
  the CLI runs in; absolute and ~ ones must be inside the workdir unless their
  first directory does not exist (a name such as /aws/lambda/f); file:// is
  always a path. Drops the PATH/NAME option lists and the over-blocking of
  values such as /start or /index.html
- Refuse a leading $VAR, and / or the home directory as LOCALSTACK_AWS_WORKDIR
- Deny deploy push, gamelift upload-build, lambda-web, lightsail
  push-container-image and cli-dev; catch abbreviations of --follow
- Require AWS CLI 2.37.7+, whose downloads honor --no-follow-symlinks

Towards DEVX-1330

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant