From d0417bb47c0267e3ad782d77a0c0a9ce69fc1b0b Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Thu, 19 Nov 2026 17:07:59 +0100 Subject: [PATCH 1/5] feat: run AWS CLI commands with the official AWS CLI v2 through lstk aws 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 --- .github/actions/host-tools/action.yml | 7 +- .github/dependabot.yml | 2 +- Dockerfile | 23 +- README.md | 10 +- data/sample-cloudformation/template.yaml | 12 + docs/DOCKER.md | 16 +- src/core/dependency-pins.test.ts | 7 +- src/core/localstack-env.ts | 4 +- src/lib/aws/aws-cli-sanitizer.test.ts | 49 ++++ src/lib/aws/aws-cli-sanitizer.ts | 43 +++- src/lib/aws/lstk-aws.test.ts | 66 ++++++ src/lib/aws/lstk-aws.ts | 53 +++++ src/lib/deployment/deployment-utils.ts | 4 +- src/prompts/infrastructure-tester.ts | 2 +- src/tools-tests/localstack-aws-client.test.ts | 221 ++++++++++++++++++ src/tools/localstack-aws-client.ts | 21 +- src/tools/localstack-deployer.ts | 130 +++++------ tests/docker/validate-image.mjs | 6 +- tests/mcp/tools.spec.mjs | 25 ++ 19 files changed, 585 insertions(+), 116 deletions(-) create mode 100644 data/sample-cloudformation/template.yaml create mode 100644 src/lib/aws/lstk-aws.test.ts create mode 100644 src/lib/aws/lstk-aws.ts create mode 100644 src/tools-tests/localstack-aws-client.test.ts diff --git a/.github/actions/host-tools/action.yml b/.github/actions/host-tools/action.yml index ad4244c..78e41da 100644 --- a/.github/actions/host-tools/action.yml +++ b/.github/actions/host-tools/action.yml @@ -1,7 +1,8 @@ name: Host tools description: >- Puts the Docker image's tools on the PATH for jobs that run the MCP server on the host: - always Terraform and uv (from the Dockerfile's host-tools stage) and lstk (docker/tools/npm), and + always Terraform, uv and the AWS CLI (from the Dockerfile's host-tools stage) and lstk + (docker/tools/npm), and optionally the Snowflake CLI from docker/tools/snowflake. Versions change only in those files. inputs: snowflake: @@ -11,11 +12,13 @@ inputs: runs: using: composite steps: - - name: Copy Terraform and uv out of the Dockerfile + # The AWS CLI comes first on the PATH, ahead of the one the runner image ships. + - name: Copy Terraform, uv and the AWS CLI out of the Dockerfile shell: bash run: | docker build --target host-tools --output "type=local,dest=$RUNNER_TEMP/host-tools" . echo "$RUNNER_TEMP/host-tools" >> "$GITHUB_PATH" + echo "$RUNNER_TEMP/host-tools/aws-cli/bin" >> "$GITHUB_PATH" - name: Install lstk shell: bash diff --git a/.github/dependabot.yml b/.github/dependabot.yml index eab09f9..7aac783 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -59,7 +59,7 @@ updates: - minor - patch - # FROM lines in the Dockerfile: node and hashicorp/terraform. + # FROM lines in the Dockerfile: node, hashicorp/terraform, astral-sh/uv and amazon/aws-cli. - package-ecosystem: docker directory: / schedule: diff --git a/Dockerfile b/Dockerfile index ac5c2d4..4a77a36 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,12 +2,13 @@ # Every tool version in this image comes from a file Dependabot updates (.github/dependabot.yml): # node, terraform FROM lines below (docker) +# aws-cli (v2) FROM line below (docker) # aws-cdk, lstk docker/tools/npm/package-lock.json (npm) # uv FROM line below (docker) # aws-sam-cli docker/tools/sam/uv.lock (uv) # snowflake-cli docker/tools/snowflake/uv.lock (uv) # dockerode & co. yarn.lock (npm, same lock as CI) -# The host-tools stage hands the same terraform and uv binaries to CI jobs that run on the host. +# The host-tools stage hands the same terraform, uv and AWS CLI to CI jobs that run on the host. # Debian packages (python3, git, curl) come with the node image's bookworm base. # Both node FROM lines must stay identical, and their major must match `node-version` in the # workflows; src/core/dependency-pins.test.ts checks this. @@ -25,14 +26,25 @@ RUN yarn build # Terraform's official image ships a static binary, so it runs on Debian as well. FROM hashicorp/terraform:1.17.2 AS terraform +# AWS's official image of the AWS CLI v2. Its installation under /usr/local/aws-cli is +# self-contained (frozen Python, built for an old glibc), so it runs on Debian as well. +# Trimmed here, before the COPYs, so the 35 MB never reach a layer: the per-service examples +# only feed `aws help` (which still needs the top-level global_*.rst), and aws_completer +# only shell Tab completion. The models stay uncompressed: this CLI cannot read .json.gz. +FROM amazon/aws-cli:2.39.3 AS awscli +RUN cd /usr/local/aws-cli/v2/current \ + && find dist/awscli/examples -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} + \ + && rm -f dist/aws_completer bin/aws_completer + # uv installs the Python CLIs below; it is mounted at build time and not part of the image. FROM ghcr.io/astral-sh/uv:0.13.9 AS uv -# Terraform and uv for CI jobs that run on the host, at the image's versions +# Terraform, uv and the AWS CLI for CI jobs that run on the host, at the image's versions # (.github/actions/host-tools): docker build --target host-tools --output type=local,dest=DIR . FROM scratch AS host-tools COPY --from=terraform /bin/terraform / COPY --from=uv /uv /uvx / +COPY --from=awscli /usr/local/aws-cli/v2/current/ /aws-cli/ FROM node:22.23.5-bookworm-slim AS runtime ENV DEBIAN_FRONTEND=noninteractive \ @@ -52,6 +64,11 @@ RUN set -eux; \ COPY --from=terraform /bin/terraform /usr/local/bin/terraform RUN terraform version +# `lstk aws` runs this CLI for the AWS client tool and the deployer's CloudFormation actions. +COPY --from=awscli /usr/local/aws-cli/v2/current/ /usr/local/aws-cli/ +RUN ln -s /usr/local/aws-cli/bin/aws /usr/local/bin/aws \ + && aws --version + # SAM CLI and Snowflake CLI each get their own venv from their own uv project: they pin # conflicting `rich` versions, so one environment cannot hold both. uv verifies every package # against the hashes in uv.lock, and --no-build refuses anything that would need a compiler. @@ -75,7 +92,7 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \ && ln -s /opt/snowflake-cli/bin/snow /usr/local/bin/snow \ && snow --version -# lstk wraps terraform, cdk, and sam for the deployer tool. aws-cdk >= 2.1138 honors the +# lstk wraps the AWS CLI, terraform, cdk, and sam. aws-cdk >= 2.1138 honors the # CDK_S3_FORCE_PATH_STYLE that lstk sets, so S3 assets reach host.docker.internal path-style. COPY docker/tools/npm/package.json docker/tools/npm/package-lock.json /opt/image-tools/npm/ RUN npm ci --prefix /opt/image-tools/npm --omit=dev --ignore-scripts --no-audit --no-fund \ diff --git a/README.md b/README.md index f63a11a..51a8d3f 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e | [`localstack-state-management`](./src/tools/localstack-state-management.ts) | Manages local file-based LocalStack state export/import workflows | - Export LocalStack state to a local file on disk through the LocalStack State REST API
- Import LocalStack state from a local file
- Inspect current LocalStack state as JSON metamodel data
- Reset all state or only selected services
- Supports service-level granularity for export, reset, and inspect
- Use this for local disk workflows; use Cloud Pods for remote cloud-backed snapshots
- Requires a valid LocalStack Auth Token | | [`localstack-extensions`](./src/tools/localstack-extensions.ts) | Installs, uninstalls, lists, and discovers LocalStack Extensions | - Manage installed extensions (`list`, `install`, `uninstall`) inside the running container
- Browse the LocalStack Extensions marketplace (`available`)
- Requires a valid LocalStack Auth Token | | [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | -| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands inside the LocalStack for AWS container | - Executes commands via `awslocal` inside the running container
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | +| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands against LocalStack for AWS | - Executes commands with the official AWS CLI v2 through `lstk aws`, so it requires `lstk` and `aws` in your system path
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | | [`localstack-azure-client`](./src/tools/localstack-azure-client.ts) | Runs Azure CLI (`az`) commands against the LocalStack for Azure emulator | - Runs the Azure CLI installed on your machine with its own profile, never your Azure login
- Blocks shell syntax and commands that would change the profile, install software or never end
- Uses the extensions you installed with `az extension add`
- Requires the Azure CLI and a valid LocalStack Auth Token | | [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN
- Start batch replication jobs, such as SSM parameters under a path prefix
- Poll job status by job ID and list existing jobs
- List resource types supported by the running Replicator extension
- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides | | [`localstack-app-inspector`](./src/tools/localstack-app-inspector.ts) | Inspects LocalStack application traces, spans, events, and IAM evaluations | - Enable or disable App Inspector for the running LocalStack instance
- List and inspect traces to understand AWS service-to-service flows
- Drill into spans, events, payload metadata, and IAM policy evaluation events
- Filter by service, region, operation, resource, ARN, status, and time range
- Requires a valid LocalStack Auth Token and the App Inspector feature in the connected LocalStack license | @@ -124,7 +124,7 @@ Run `npx -y @localstack/localstack-mcp-server init --help` for all options. ### Prerequisites - Docker installed and running. The MCP server manages the LocalStack container directly through the Docker API. -- [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) (`npm install -g @localstack/lstk`) plus the Terraform, AWS CDK (2.177.0 or newer), or AWS SAM (1.95.0 or newer) CLI in your system path if you want to deploy Terraform, CDK, or SAM projects +- [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) (`npm install -g @localstack/lstk`) and the [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) if you want to run AWS CLI commands or deploy CloudFormation stacks, plus the Terraform, AWS CDK (2.177.0 or newer), or AWS SAM (1.95.0 or newer) CLI in your system path if you want to deploy Terraform, CDK, or SAM projects - Snowflake CLI (`snow`) installed in your system path if you want to use the Snowflake tool - Azure CLI (`az`) installed in your system path if you want to use the Azure tool (see [docs/AZURE.md](./docs/AZURE.md)) - A [valid LocalStack Auth Token](https://docs.localstack.cloud/aws/getting-started/auth-token/) configured as `LOCALSTACK_AUTH_TOKEN` (**required for all MCP tools**) @@ -170,7 +170,7 @@ If you installed from source, change `command` and `args` to point to your local ### Run with Docker -The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory. +The `localstack/localstack-mcp-server` Docker image bundles `lstk` with the AWS CLI v2, Terraform, CDK, and SAM, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory. If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mount those project paths into the MCP container and pass the in-container path to the tool. The simplest convention is to mount projects at the same absolute path they use on the host. @@ -267,14 +267,14 @@ This repository includes [MCP Server Tester](https://github.com/gleanwork/mcp-se export LOCALSTACK_AUTH_TOKEN="" yarn test:mcp:tools ``` - The tests deploy a sample project, switch IAM enforcement to soft mode and save a Cloud Pod, so point them at an instance you don't need: set `LOCALSTACK_PORT` and `MAIN_CONTAINER_NAME` to use one other than the default on 4566. They need Docker, Terraform and [lstk](https://github.com/localstack/lstk) on the `PATH`. + The tests deploy a sample project, switch IAM enforcement to soft mode and save a Cloud Pod, so point them at an instance you don't need: set `LOCALSTACK_PORT` and `MAIN_CONTAINER_NAME` to use one other than the default on 4566. They need Docker, Terraform, the AWS CLI v2 and [lstk](https://github.com/localstack/lstk) on the `PATH`. - Run MCP host evals through [OpenRouter](https://openrouter.ai) (default model `google/gemini-2.5-flash`; set `EVAL_MODEL` to any OpenRouter model ID to override it): ```bash export OPENROUTER_API_KEY="" export LOCALSTACK_AUTH_TOKEN="" yarn test:mcp:evals ``` - The evals check whether a model picks and combines the right tools for a goal; their prompts don't name the tools. They start, change and stop LocalStack on port 4566, so don't run them against an instance you're using. They need Docker, Terraform, [lstk](https://github.com/localstack/lstk) and the Snowflake CLI (`snow`) on the `PATH`, and the sample project's providers downloaded with `terraform -chdir=data/sample-terraform init`. + The evals check whether a model picks and combines the right tools for a goal; their prompts don't name the tools. They start, change and stop LocalStack on port 4566, so don't run them against an instance you're using. They need Docker, Terraform, the AWS CLI v2, [lstk](https://github.com/localstack/lstk) and the Snowflake CLI (`snow`) on the `PATH`, and the sample project's providers downloaded with `terraform -chdir=data/sample-terraform init`. The [MCP evals workflow](./.github/workflows/mcp-evals.yml) runs them after every merge into `main` that changes the server, its tools or the evals, weekly and on demand; it needs the `OPENROUTER_API_KEY` repository secret. - Open the latest MCP Server Tester HTML report: ```bash diff --git a/data/sample-cloudformation/template.yaml b/data/sample-cloudformation/template.yaml new file mode 100644 index 0000000..78c0f62 --- /dev/null +++ b/data/sample-cloudformation/template.yaml @@ -0,0 +1,12 @@ +AWSTemplateFormatVersion: "2010-09-09" +Description: Sample stack for the localstack-deployer create-stack and delete-stack actions. + +Resources: + Queue: + Type: AWS::SQS::Queue + Properties: + QueueName: mcp-tools-cfn-queue + +Outputs: + QueueUrl: + Value: !Ref Queue diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 0b2be46..9547569 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -1,10 +1,9 @@ # Running the LocalStack MCP Server in Docker The published image bundles everything the server shells out to — `lstk` with -Terraform, AWS CDK, and AWS SAM, and the Snowflake `snow` +the AWS CLI v2, Terraform, AWS CDK, and AWS SAM, and the Snowflake `snow` CLI — so the **only dependency on your machine is Docker itself**. LocalStack -lifecycle, logs, and `awslocal` run through the Docker Engine API and LocalStack's -REST APIs. +lifecycle and logs run through the Docker Engine API and LocalStack's REST APIs. The image is multi-arch (`linux/amd64` and `linux/arm64`). @@ -55,7 +54,7 @@ docker run -i --rm \ | Flag | Why it's needed | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `-v /var/run/docker.sock:/var/run/docker.sock` | Lets the server create/stop/restart the sibling LocalStack container, read its logs, and run `awslocal` inside it. | +| `-v /var/run/docker.sock:/var/run/docker.sock` | Lets the server create/stop/restart the sibling LocalStack container and read its logs. | | `--add-host host.docker.internal:host-gateway` | Resolves `host.docker.internal` on Linux. Harmless on Docker Desktop (Mac/Windows), where it already resolves. | | `--add-host snowflake.localhost.localstack.cloud:host-gateway` | Lets the Snowflake CLI reach the sibling Snowflake emulator through the hostname the emulator expects for routing. | | `-e LOCALSTACK_AUTH_TOKEN` | Required by **every** tool in this server. | @@ -107,9 +106,11 @@ The simplest convention is to mount it at the same absolute path: Then tell the tool `directory: /Users/you/projects/my-infra`. -The deployer runs Terraform, SAM, and CDK through `lstk terraform|sam|cdk`, which -receives the LocalStack endpoint automatically when -`LOCALSTACK_HOSTNAME=host.docker.internal` is set. `lstk` forces CDK asset +The deployer runs Terraform, SAM, and CDK through `lstk terraform|sam|cdk`, and the AWS +client tool and the deployer's CloudFormation actions run the AWS CLI through `lstk aws`. +These receive the LocalStack endpoint automatically when +`LOCALSTACK_HOSTNAME=host.docker.internal` is set. A CloudFormation template is read inside +the MCP container, so bind-mount it like a project directory. `lstk` forces CDK asset publishing to path-style S3, so no extra S3 host alias is needed. Existing configs that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. @@ -173,6 +174,7 @@ release is at least 7 days old (its `cooldown`): | Node.js base image | `FROM node:…` in `Dockerfile` | `docker` (major updates by hand: the workflows use `node-version: 22.x`, the latest 22 at run time, and a test keeps the majors equal) | | Terraform | `FROM hashicorp/terraform:…` in `Dockerfile` | `docker` | | uv (build time only) | `FROM ghcr.io/astral-sh/uv:…` in `Dockerfile` | `docker` | +| AWS CLI v2 | `FROM amazon/aws-cli:…` in `Dockerfile` | `docker` | | `aws-cdk`, `lstk` | `docker/tools/npm/package-lock.json` | `npm` | | AWS SAM CLI | `docker/tools/sam/pyproject.toml` and `uv.lock` | `uv` | | Snowflake CLI | `docker/tools/snowflake/pyproject.toml` and `uv.lock` | `uv` | diff --git a/src/core/dependency-pins.test.ts b/src/core/dependency-pins.test.ts index b279c97..cfacb33 100644 --- a/src/core/dependency-pins.test.ts +++ b/src/core/dependency-pins.test.ts @@ -97,20 +97,23 @@ describe("dependency pins", () => { expect(docker).toMatch(/^[ \t]*(?:-[ \t]*)?runner:[ \t]*ubuntu-[\d.]+-arm[ \t]*$/m); }); - it("gives CI jobs the image's Terraform and uv, from the Dockerfile's host-tools stage", () => { + it("gives CI jobs the image's Terraform, uv and AWS CLI, from the Dockerfile's host-tools stage", () => { // Dependabot bumps the FROM lines, not action inputs or install scripts, so any other way // of installing these tools in CI would drift from the image. const stage = dockerfileInstructions().join("\n"); expect(stage).toMatch(/^FROM scratch AS host-tools$/m); expect(stage).toMatch(/^COPY --from=terraform \S+ \/$/m); expect(stage).toMatch(/^COPY --from=uv \S+ \S+ \/$/m); + expect(stage).toMatch(/^FROM amazon\/aws-cli:\d+\.\d+\.\d+ AS awscli$/m); + expect(stage).toMatch(/^COPY --from=awscli \S+ \/aws-cli\/$/m); + expect(read(".github/actions/host-tools/action.yml")).toContain("host-tools/aws-cli/bin"); const files = [ ...fs.readdirSync(path.join(ROOT, ".github/workflows")).map((f) => `.github/workflows/${f}`), ".github/actions/host-tools/action.yml", ]; const otherInstall = - /setup-terraform|setup-uv|terraform_version|\b(?:curl|wget)\b.*\b(?:hashicorp\.com|astral\.sh|astral-sh)\b|\b(?:pipx?|brew|apt(?:-get)?|mise|asdf) install\b.*\b(?:terraform|uv)\b/g; + /setup-terraform|setup-uv|terraform_version|awscli-exe|configure-aws-credentials|\b(?:curl|wget)\b.*\b(?:hashicorp\.com|astral\.sh|astral-sh)\b|\b(?:pipx?|brew|apt(?:-get)?|mise|asdf) install\b.*\b(?:terraform|uv)\b/g; for (const file of files) { expect(`${file}: ${read(file).match(otherInstall) ?? []}`).toBe(`${file}: `); } diff --git a/src/core/localstack-env.ts b/src/core/localstack-env.ts index 7e473a8..59bf072 100644 --- a/src/core/localstack-env.ts +++ b/src/core/localstack-env.ts @@ -1,7 +1,7 @@ import { LOCALSTACK_PORT } from "./config"; /** - * Build the environment for the spawned `lstk terraform|cdk|sam` proxies so they + * Build the environment for the spawned `lstk aws|terraform|cdk|sam` proxies so they * target the LocalStack endpoint this server is configured for. * * Why this is needed (verified against the lstk sources): @@ -12,7 +12,7 @@ import { LOCALSTACK_PORT } from "./config"; * - AWS_ENDPOINT_URL_S3 is left unset: lstk derives it and, for CDK >= 2.1138, * forces path-style S3. A preset S3 endpoint turns that off. * - * This env is injected ONLY into the IaC CLI child processes — never globally and + * This env is injected ONLY into the lstk child processes — never globally and * never into the LocalStack container, because a container-side AWS_ENDPOINT_URL * would redirect LocalStack's own internal service-to-service calls and break them. * diff --git a/src/lib/aws/aws-cli-sanitizer.test.ts b/src/lib/aws/aws-cli-sanitizer.test.ts index 5e5a664..7349160 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -57,6 +57,55 @@ describe("sanitizeAwsCliCommand", () => { } ); + test.each([ + "s3 ls --endpoint-url https://s3.amazonaws.com", + "s3 ls --endpoint-url=https://s3.amazonaws.com", + "s3 ls --profile prod", + "sts get-caller-identity --PROFILE=prod", + "sqs list-queues --endp https://sqs.us-east-1.amazonaws.com --pro prod", + "sqs list-queues --e=https://sqs.us-east-1.amazonaws.com", + "sqs list-queues --endpoint-ur=https://sqs.us-east-1.amazonaws.com", + "sqs list-queues --endpoint https://sqs.us-east-1.amazonaws.com", + "s3 ls --profil=prod", + "s3 ls --p prod", + ])("rejects options that leave LocalStack: %s", (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow("commands always target LocalStack"); + }); + + test.each([ + "s3 ls --page-size 10", + "s3api list-objects --bucket b --prefix logs/", + "sns subscribe --topic-arn t --protocol email --notification-endpoint a@b.c", + "ec2 describe-instances --e-tag-x y --region eu-west-1 --output json --debug", + ])("allows options that are not prefixes of --endpoint-url or --profile: %s", (command) => { + expect(sanitizeAwsCliCommand(command)).toBe(command); + }); + + test.each(["configure", "configure set region eu-west-1", "configure export-credentials"])( + "rejects configure other than list: %s", + (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow("Only 'configure list'"); + } + ); + + test.each(["help", "s3 help", "s3 ls help", "sqs list-queues --help", "s3api -h"])( + "allows a help request: %s", + (command) => { + expect(sanitizeAwsCliCommand(command)).toBe(command); + } + ); + + test.each([ + "sqs list-queues --queue-name-prefix help", + "sqs send-message --queue-url q --message-body help", + "s3 cp help s3://bucket/key", + "sqs list-queues help --region eu-west-1", + "sqs list-queues --help --endpoint-url-x y", + "s3api put-object --bucket b --key '--help'", + ])("rejects a help token that is not a pure help request: %s", (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow("may only end a help request"); + }); + test.each(["s3 ls 'unterminated", 's3 ls "unterminated'])( "rejects unterminated quotes: %s", (command) => { diff --git a/src/lib/aws/aws-cli-sanitizer.ts b/src/lib/aws/aws-cli-sanitizer.ts index 9f961db..fc133f9 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -1,3 +1,39 @@ +const HELP_TOKENS = new Set(["help", "-h", "--help"]); +// Global options that would send a command to another endpoint, or sign it with the +// credentials of a real AWS account, because the CLI runs where this server runs. +const LOCALSTACK_ESCAPE_OPTIONS = ["endpoint-url", "profile"]; + +/** + * Throws unless the argv `lstk aws` receives is certain to reach LocalStack. Every argv passed + * to `lstk aws` goes through this, whether it came from the agent's command or a tool parameter. + */ +export function assertTargetsLocalStack(args: string[]): void { + // The CLI accepts any unambiguous prefix of an option (`--endp x`, `--e=x`, `--pro p`), and a + // later --endpoint-url overrides the one lstk puts first. + for (const arg of args) { + const name = arg.match(/^--([^=]+)/)?.[1].toLowerCase(); + const escape = name && LOCALSTACK_ESCAPE_OPTIONS.find((option) => option.startsWith(name)); + if (escape) { + throw new Error( + `Option '${arg.split("=")[0]}' (--${escape}) is not allowed: commands always target LocalStack.` + ); + } + } + // lstk answers any help token itself and then runs aws without its endpoint and credential + // handling, so an API call with a `help` value would leave LocalStack. Only a pure help + // request, command words followed by one trailing help token, may contain one. + const helpIndex = args.findIndex((arg) => HELP_TOKENS.has(arg)); + if ( + helpIndex !== -1 && + (helpIndex !== args.length - 1 || + !args.slice(0, -1).every((arg) => /^[a-z0-9][a-z0-9-]*$/i.test(arg))) + ) { + throw new Error( + "'help', '-h' and '--help' may only end a help request such as 's3 ls help', not appear as a value." + ); + } +} + export function sanitizeAwsCliCommand(rawCommand: string): string { const command = rawCommand.trim(); if (!command) { @@ -16,7 +52,12 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { throw new Error("Command must start with an AWS service or built-in command."); } - splitAwsCliArgs(command); + const args = splitAwsCliArgs(command); + + assertTargetsLocalStack(args); + if (args[0]?.toLowerCase() === "configure" && args[1]?.toLowerCase() !== "list") { + throw new Error("Only 'configure list' is allowed: the AWS CLI config is not changed."); + } return command; } diff --git a/src/lib/aws/lstk-aws.test.ts b/src/lib/aws/lstk-aws.test.ts new file mode 100644 index 0000000..358ea20 --- /dev/null +++ b/src/lib/aws/lstk-aws.test.ts @@ -0,0 +1,66 @@ +import fs from "fs"; +import os from "os"; +import path from "path"; +import { runLstkAws } from "./lstk-aws"; + +// A stand-in `lstk` on the PATH that, like `lstk aws s3 cp - …`, reads stdin to the end before +// answering, then prints what it was run with. +const FAKE_LSTK = `#!/usr/bin/env node +let input = ""; +process.stdin.on("data", (chunk) => (input += chunk)); +process.stdin.on("end", () => { + process.stdout.write("> Note: No AWS profile found, run 'lstk setup aws'\\n"); + process.stdout.write(JSON.stringify({ + args: process.argv.slice(2), + input, + pager: process.env.AWS_PAGER, + endpoint: process.env.AWS_ENDPOINT_URL, + })); +}); +`; + +describe("runLstkAws", () => { + let binDir: string; + const saved = { + PATH: process.env.PATH, + AWS_ENDPOINT_URL: process.env.AWS_ENDPOINT_URL, + LOCALSTACK_HOSTNAME: process.env.LOCALSTACK_HOSTNAME, + }; + + beforeAll(() => { + binDir = fs.mkdtempSync(path.join(os.tmpdir(), "fake-lstk-")); + fs.writeFileSync(path.join(binDir, "lstk"), FAKE_LSTK, { mode: 0o755 }); + process.env.PATH = `${binDir}${path.delimiter}${saved.PATH}`; + delete process.env.AWS_ENDPOINT_URL; + delete process.env.LOCALSTACK_HOSTNAME; + }); + + afterAll(() => { + for (const [key, value] of Object.entries(saved)) { + if (value === undefined) delete process.env[key]; + else process.env[key] = value; + } + fs.rmSync(binDir, { recursive: true, force: true }); + }); + + test("gives the CLI no stdin, so a command reading it ends instead of waiting", async () => { + const result = await runLstkAws(["s3", "cp", "-", "s3://bucket/key"]); + + expect(result.exitCode).toBe(0); + expect(JSON.parse(result.stdout)).toEqual({ + args: ["aws", "s3", "cp", "-", "s3://bucket/key"], + input: "", + pager: "", + endpoint: "http://localhost.localstack.cloud:4566", + }); + }, 5_000); + + test("refuses an argv that would leave LocalStack before starting anything", async () => { + await expect(runLstkAws(["sqs", "list-queues", "--endp", "https://x"])).rejects.toThrow( + "commands always target LocalStack" + ); + await expect( + runLstkAws(["cloudformation", "delete-stack", "--stack-name", "help"]) + ).rejects.toThrow("may only end a help request"); + }); +}); diff --git a/src/lib/aws/lstk-aws.ts b/src/lib/aws/lstk-aws.ts new file mode 100644 index 0000000..5294622 --- /dev/null +++ b/src/lib/aws/lstk-aws.ts @@ -0,0 +1,53 @@ +import { runCommand, type CommandResult } from "../../core/command-runner"; +import { buildIacCliEnv } from "../../core/localstack-env"; +import { LSTK_INSTALL_MESSAGE } from "../deployment/deployment-utils"; +import { assertTargetsLocalStack } from "./aws-cli-sanitizer"; + +const AWS_CLI_INSTALL_MESSAGE = `❌ The AWS CLI is not installed or not available in PATH. + +lstk runs your own AWS CLI (v2). Please install it by following the official documentation: +https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +After installation, make sure the 'aws' command is available in your PATH.`; + +// lstk prints this to stdout whenever ~/.aws has no `localstack` profile, which is always the +// case in the Docker image. lstk supplies the credentials itself then, so the note is noise +// in front of the AWS CLI's output. +const NO_PROFILE_NOTE = /^> Note: No AWS profile found, run 'lstk setup aws'\r?\n/; + +/** Returns an install hint when lstk or the AWS CLI is missing, otherwise null. */ +export async function checkLstkAwsDependencies(): Promise { + const [lstk, aws] = await Promise.all([ + runCommand("lstk", ["--version"], { timeout: 10000 }), + runCommand("aws", ["--version"], { timeout: 10000 }), + ]); + if (lstk.error) return LSTK_INSTALL_MESSAGE; + if (aws.error) return AWS_CLI_INSTALL_MESSAGE; + return null; +} + +/** + * Runs `lstk aws `: the official AWS CLI, with endpoint, credentials and region set by + * lstk. The endpoint comes from AWS_ENDPOINT_URL (see buildIacCliEnv), and the pager is off + * because the output goes to the MCP client, not a terminal. + */ +export async function runLstkAws(args: string[]): Promise { + assertTargetsLocalStack(args); + // No stdin: lstk hands it on to aws, and a command reading it (`s3 cp - …`) would otherwise + // wait for input that never comes until the timeout. + const result = await runCommand("lstk", ["aws", ...args], { + env: buildIacCliEnv({ AWS_PAGER: "" }), + stdio: ["ignore", "pipe", "pipe"], + }); + return { ...result, stdout: result.stdout.replace(NO_PROFILE_NOTE, "") }; +} + +/** The error text of a failed `lstk aws` run; lstk reports its own failures on stdout. */ +export function lstkAwsErrorText(result: CommandResult): string { + return ( + result.stderr.trim() || + result.stdout.trim() || + result.error?.message || + `lstk aws exited with code ${result.exitCode}` + ); +} diff --git a/src/lib/deployment/deployment-utils.ts b/src/lib/deployment/deployment-utils.ts index d6ab9be..0f308e7 100644 --- a/src/lib/deployment/deployment-utils.ts +++ b/src/lib/deployment/deployment-utils.ts @@ -11,9 +11,9 @@ export interface DependencyCheckResult { export type ProjectType = "cdk" | "terraform" | "sam" | "cloudformation" | "ambiguous" | "unknown"; -const LSTK_INSTALL_MESSAGE = `❌ lstk is not installed or not available in PATH. +export const LSTK_INSTALL_MESSAGE = `❌ lstk is not installed or not available in PATH. -The deployer runs Terraform, CDK, and SAM through the lstk CLI. Please install it by following the official documentation: +This server runs the AWS CLI, Terraform, CDK, and SAM through the lstk CLI. Please install it by following the official documentation: https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/ Installation: diff --git a/src/prompts/infrastructure-tester.ts b/src/prompts/infrastructure-tester.ts index fcceadf..6d454c6 100644 --- a/src/prompts/infrastructure-tester.ts +++ b/src/prompts/infrastructure-tester.ts @@ -117,7 +117,7 @@ ${values.user_focus ? "Use the user focus to guide what you inspect first, valid Use the LocalStack MCP tools instead of guessing: - \`localstack-management\` for runtime status and start/restart. - \`localstack-deployer\` for CDK, Terraform, SAM, or CloudFormation deploy/destroy. -- \`localstack-aws-client\` for live \`awslocal\` resource probes. +- \`localstack-aws-client\` for live AWS CLI resource probes. - \`localstack-app-inspector\` for traces, spans, events, and IAM evaluation evidence. - \`localstack-logs-analysis\` for container errors around deploy or test windows. - \`localstack-docs\` for service coverage and LocalStack-specific limitations. diff --git a/src/tools-tests/localstack-aws-client.test.ts b/src/tools-tests/localstack-aws-client.test.ts new file mode 100644 index 0000000..a712ec9 --- /dev/null +++ b/src/tools-tests/localstack-aws-client.test.ts @@ -0,0 +1,221 @@ +// Tool tests live outside src/tools/ because xmcp registers every src/tools/*.ts as a tool. +// The boundary is the spawned process: runCommand is replaced by a fake lstk/aws pair. +import path from "path"; +import localstackAwsClient from "../tools/localstack-aws-client"; +import localstackDeployer from "../tools/localstack-deployer"; +import { runCommand, type CommandResult } from "../core/command-runner"; + +// The deployer's other parameters, which the CloudFormation actions ignore. +const deployerDefaults = { + projectType: "auto" as const, + directory: undefined, + variables: undefined, + stackName: undefined, + templatePath: undefined, + s3Bucket: undefined, + resolveS3: undefined, + saveParams: undefined, +}; + +jest.mock("../core/analytics", () => ({ + withToolAnalytics: (_name: string, _args: unknown, fn: () => unknown) => fn(), +})); +jest.mock("../core/preflight", () => ({ + ...jest.requireActual("../core/preflight"), + requireLocalStackRunning: jest.fn(async () => null), +})); +jest.mock("../core/command-runner", () => ({ + ...jest.requireActual("../core/command-runner"), + runCommand: jest.fn(), +})); + +const mockedRun = jest.mocked(runCommand); +const ok = (stdout = ""): CommandResult => ({ stdout, stderr: "", exitCode: 0 }); +const failed = (stdout: string, stderr = ""): CommandResult => ({ + stdout, + stderr, + exitCode: 1, + error: new Error("Command failed with exit code 1"), +}); +const missing = (): CommandResult => ({ + stdout: "", + stderr: "", + exitCode: null, + error: new Error("spawn aws ENOENT"), +}); + +/** Answers `--version` for both CLIs, and `lstk aws …` with the given result. */ +function fakeCli(awsResult: CommandResult, { awsInstalled = true } = {}) { + mockedRun.mockImplementation(async (command, args) => { + if (args[0] === "--version") { + return command === "aws" && !awsInstalled ? missing() : ok(`${command} 1.0.0`); + } + return awsResult; + }); +} + +const lstkAwsCalls = () => + mockedRun.mock.calls.filter(([command, args]) => command === "lstk" && args[0] === "aws"); +const text = (r: { content: Array<{ text: string }> }) => r.content[0].text; + +describe("localstack-aws-client", () => { + beforeEach(() => { + jest.clearAllMocks(); + process.env.LOCALSTACK_AUTH_TOKEN = "ls-test-token"; + delete process.env.AWS_ENDPOINT_URL; + delete process.env.LOCALSTACK_HOSTNAME; + }); + + test("runs the command through lstk aws, aimed at LocalStack and without a pager", async () => { + fakeCli(ok("2026-11-19 10:00:00 my-bucket\n")); + + const result = await localstackAwsClient({ command: `s3api list-objects --bucket "a b"` }); + + expect(result.isError).toBeFalsy(); + expect(text(result)).toContain("my-bucket"); + const [[, args, options]] = lstkAwsCalls(); + expect(args).toEqual(["aws", "s3api", "list-objects", "--bucket", "a b"]); + expect(options?.env).toMatchObject({ + AWS_ENDPOINT_URL: "http://localhost.localstack.cloud:4566", + AWS_PAGER: "", + }); + }); + + test("drops lstk's missing-profile note from the AWS CLI output", async () => { + fakeCli(ok(`> Note: No AWS profile found, run 'lstk setup aws'\n{"QueueUrls": []}\n`)); + + const result = await localstackAwsClient({ command: "sqs list-queues" }); + + expect(text(result).trim()).toBe(`{"QueueUrls": []}`); + }); + + test("refuses a command that would leave LocalStack, without running anything", async () => { + fakeCli(ok()); + + const result = await localstackAwsClient({ + command: "s3 ls --profile prod --endpoint-url https://s3.amazonaws.com", + }); + + expect(result.isError).toBe(true); + expect(text(result)).toContain("commands always target LocalStack"); + expect(mockedRun).not.toHaveBeenCalled(); + }); + + test("names the AWS CLI install page when aws is missing", async () => { + fakeCli(ok(), { awsInstalled: false }); + + const result = await localstackAwsClient({ command: "s3 ls" }); + + expect(result.isError).toBe(true); + expect(text(result)).toContain("getting-started-install.html"); + expect(lstkAwsCalls()).toHaveLength(0); + }); + + test("reports lstk's own failure, which it prints on stdout", async () => { + fakeCli(failed("Error: no LocalStack emulator is running at http://localhost:4566\n")); + + const result = await localstackAwsClient({ command: "s3 ls" }); + + expect(result.isError).toBe(true); + expect(text(result)).toContain("no LocalStack emulator is running"); + }); + + test("links the coverage docs when LocalStack does not emulate an action", async () => { + fakeCli( + failed( + "", + "An error occurred (InternalFailure): The API action 'CreateThing' for service 'iot' is either not available in your current license plan or has not yet been emulated by LocalStack." + ) + ); + + const result = await localstackAwsClient({ command: "iot create-thing --thing-name t" }); + + expect(text(result)).toContain("Service Not Implemented in LocalStack"); + expect(text(result)).toContain("coverage_iot"); + }); +}); + +describe("localstack-deployer CloudFormation actions", () => { + const template = path.resolve(__dirname, "../../data/sample-cloudformation/template.yaml"); + + beforeEach(() => { + jest.clearAllMocks(); + process.env.LOCALSTACK_AUTH_TOKEN = "ls-test-token"; + }); + + test("create-stack hands the AWS CLI the template file by absolute path", async () => { + fakeCli(ok('{"StackId": "arn:aws:cloudformation:us-east-1:000000000000:stack/s/1"}')); + + const result = await localstackDeployer({ + ...deployerDefaults, + action: "create-stack", + stackName: "s", + directory: path.relative(process.cwd(), path.dirname(template)), + }); + + expect(result.isError).toBeFalsy(); + expect(text(result)).toContain("StackId"); + expect(lstkAwsCalls()[0][1]).toEqual([ + "aws", + "cloudformation", + "create-stack", + "--stack-name", + "s", + "--template-body", + `file://${template}`, + ]); + }); + + test("delete-stack reports the AWS CLI's error", async () => { + fakeCli(failed("", "An error occurred (ValidationError): Stack s does not exist")); + + const result = await localstackDeployer({ + ...deployerDefaults, + action: "delete-stack", + stackName: "s", + }); + + expect(result.isError).toBe(true); + expect(text(result)).toContain("CloudFormation delete-stack failed"); + expect(text(result)).toContain("Stack s does not exist"); + expect(lstkAwsCalls()[0][1]).toEqual([ + "aws", + "cloudformation", + "delete-stack", + "--stack-name", + "s", + ]); + }); + + test.each([ + "--endpoint-url=https://cloudformation.us-east-1.amazonaws.com", + "my_stack", + "1stack", + ])("refuses a stack name that is not one, without running the CLI: %s", async (stackName) => { + fakeCli(ok()); + + const result = await localstackDeployer({ + ...deployerDefaults, + action: "delete-stack", + stackName, + }); + + expect(text(result)).toContain("Invalid Stack Name"); + expect(lstkAwsCalls()).toHaveLength(0); + }); + + // A valid name, but lstk would read it as a help request and skip its endpoint handling. + test.each(["help"])("refuses the stack name '%s', without running the CLI", async (stackName) => { + fakeCli(ok()); + + const result = await localstackDeployer({ + ...deployerDefaults, + action: "delete-stack", + stackName, + }); + + expect(result.isError).toBe(true); + expect(text(result)).toContain("may only end a help request"); + expect(lstkAwsCalls()).toHaveLength(0); + }); +}); diff --git a/src/tools/localstack-aws-client.ts b/src/tools/localstack-aws-client.ts index 3f5ea24..6edc2a4 100644 --- a/src/tools/localstack-aws-client.ts +++ b/src/tools/localstack-aws-client.ts @@ -3,8 +3,8 @@ import { type ToolMetadata, type InferSchema } from "xmcp"; import { runPreflights, requireLocalStackRunning, requireAuthToken } from "../core/preflight"; import { ResponseBuilder } from "../core/response-builder"; import { withToolAnalytics } from "../core/analytics"; -import { DockerApiClient } from "../lib/docker/docker.client"; import { sanitizeAwsCliCommand, splitAwsCliArgs } from "../lib/aws/aws-cli-sanitizer"; +import { checkLstkAwsDependencies, lstkAwsErrorText, runLstkAws } from "../lib/aws/lstk-aws"; // Define the schema for tool parameters export const schema = { @@ -13,7 +13,7 @@ export const schema = { .trim() .min(1, { message: "The command string cannot be empty." }) .describe( - "The AWS CLI command to execute (e.g., 's3 ls', 'dynamodb list-tables'). Do not include 'awslocal' or 'aws'." + "The AWS CLI command to execute (e.g., 's3 ls', 'dynamodb list-tables'). Do not include 'lstk', 'aws' or 'awslocal'." ), }; @@ -21,7 +21,7 @@ export const schema = { export const metadata: ToolMetadata = { name: "localstack-aws-client", description: - "Executes an AWS CLI command against the running LocalStack container using the 'awslocal' wrapper.", + "Executes an AWS CLI command against the running LocalStack for AWS emulator, through the official AWS CLI v2 and 'lstk aws', which set the endpoint, credentials and region.", annotations: { title: "LocalStack AWS Client", }, @@ -33,22 +33,19 @@ export default async function localstackAwsClient({ command }: InferSchema ${tempPath}`], - templateBody - ); - if (writeRes.exitCode !== 0) { - return ResponseBuilder.error( - "Template Upload Failed", - writeRes.stderr || `Failed to write template to ${tempPath}` - ); - } - - const createCmd = [ - "awslocal", + return runCloudFormation( + [ "cloudformation", "create-stack", "--stack-name", stackName, "--template-body", - `file://${tempPath}`, - ]; - const createRes = await dockerClient.executeInContainer(containerId, createCmd); - - try { - await dockerClient.executeInContainer(containerId, [ - "/bin/sh", - "-c", - `rm -f ${tempPath}`, - ]); - } catch {} - - if (createRes.exitCode === 0) { - return ResponseBuilder.markdown( - createRes.stdout && createRes.stdout.trim() - ? createRes.stdout - : `Stack '${stackName}' creation initiated.\n\nTip: Use the 'localstack-aws-client' tool with 'cloudformation describe-stacks' to monitor stack status and wait for CREATE_COMPLETE.` - ); - } - return ResponseBuilder.error( - "CloudFormation create-stack failed", - createRes.stderr || "Unknown error" - ); - } catch (error) { - const errorMessage = error instanceof Error ? error.message : String(error); - return ResponseBuilder.error( - "CloudFormation Error", - `An unexpected error occurred: ${errorMessage}` - ); - } + `file://${absoluteTemplatePath}`, + ], + "create-stack", + `Stack '${stackName}' creation initiated.\n\nTip: Use the 'localstack-aws-client' tool with 'cloudformation describe-stacks' to monitor stack status and wait for CREATE_COMPLETE.` + ); } if (action === "delete-stack") { @@ -229,29 +203,11 @@ export default async function localstackDeployer({ "The parameter 'stackName' is required for action 'delete-stack'." ); } - try { - const dockerClient = new DockerApiClient(); - const containerId = await dockerClient.findLocalStackContainer(); - const command = ["awslocal", "cloudformation", "delete-stack", "--stack-name", stackName]; - const result = await dockerClient.executeInContainer(containerId, command); - if (result.exitCode === 0) { - return ResponseBuilder.markdown( - result.stdout && result.stdout.trim() - ? result.stdout - : `Stack '${stackName}' deletion initiated.\n\nTip: Use the 'localstack-aws-client' tool with 'cloudformation describe-stacks' to monitor deletion status until DELETE_COMPLETE.` - ); - } - return ResponseBuilder.error( - "CloudFormation delete-stack failed", - result.stderr || "Unknown error" - ); - } catch (error) { - const errorMessage = error instanceof Error ? error.message : String(error); - return ResponseBuilder.error( - "CloudFormation Error", - `An unexpected error occurred: ${errorMessage}` - ); - } + return runCloudFormation( + ["cloudformation", "delete-stack", "--stack-name", stackName], + "delete-stack", + `Stack '${stackName}' deletion initiated.\n\nTip: Use the 'localstack-aws-client' tool with 'cloudformation describe-stacks' to monitor deletion status until DELETE_COMPLETE.` + ); } let resolvedProjectType: "cdk" | "terraform" | "sam"; @@ -357,6 +313,30 @@ Please check the directory path and ensure all prerequisites are met.` ); } +/** Runs a CloudFormation call through `lstk aws`; the template is read where this server runs. */ +async function runCloudFormation( + args: string[], + operation: "create-stack" | "delete-stack", + fallbackMessage: string +) { + try { + const missing = await checkLstkAwsDependencies(); + if (missing) return ResponseBuilder.error("Dependency Not Available", missing); + + const result = await runLstkAws(args); + if (result.exitCode === 0) { + return ResponseBuilder.markdown(result.stdout.trim() ? result.stdout : fallbackMessage); + } + return ResponseBuilder.error(`CloudFormation ${operation} failed`, lstkAwsErrorText(result)); + } catch (error) { + const errorMessage = error instanceof Error ? error.message : String(error); + return ResponseBuilder.error( + "CloudFormation Error", + `An unexpected error occurred: ${errorMessage}` + ); + } +} + /** * Execute the deployment commands based on project type and action */ diff --git a/tests/docker/validate-image.mjs b/tests/docker/validate-image.mjs index 2795be9..cae3f85 100644 --- a/tests/docker/validate-image.mjs +++ b/tests/docker/validate-image.mjs @@ -343,7 +343,7 @@ async function main() { // 5b. Readiness gate — after a cold start the container reports "running" before // every service accepts connections. A well-behaved client waits for readiness; - // poll a trivial awslocal call until it succeeds before exercising services. + // poll a trivial AWS CLI call until it succeeds before exercising services. if (!SKIP.has("start") && (!SKIP.has("aws") || !SKIP.has("deploy"))) { const ready = await callToolUntil( "localstack-aws-client", @@ -355,7 +355,7 @@ async function main() { ); } - // 6. aws-client — validates docker exec of awslocal inside the LS container + // 6. aws-client — validates the image's AWS CLI through lstk aws if (!SKIP.has("aws")) { try { const mb = await callTool( @@ -367,7 +367,7 @@ async function main() { const ok = !mb.isError && !ls.isError && /harness-test-bucket/.test(ls.text); record( "aws", - "localstack-aws-client (awslocal s3 mb + ls)", + "localstack-aws-client (lstk aws s3 mb + ls)", ok, `mb: ${snip(mb.text, 120)} | ls: ${snip(ls.text, 200)}` ); diff --git a/tests/mcp/tools.spec.mjs b/tests/mcp/tools.spec.mjs index f1bf52a..eae5f0a 100644 --- a/tests/mcp/tools.spec.mjs +++ b/tests/mcp/tools.spec.mjs @@ -82,6 +82,31 @@ test.describe("tools against a running LocalStack", () => { expect(await call(mcp, tool, { command: "sqs list-queues" })).toContain(QUEUE); }); + // The template is read by the AWS CLI where the server runs, then the stack's queue is read + // back through the AWS client tool. + test("deployer: creates and deletes a CloudFormation stack", async ({ mcp }) => { + const stackName = `${PREFIX}-cfn`; + const aws = (command) => call(mcp, "localstack-aws-client", { command }); + await call(mcp, "localstack-deployer", { + action: "create-stack", + stackName, + templatePath: "data/sample-cloudformation/template.yaml", + }); + try { + await expect + .poll(() => aws(`cloudformation describe-stacks --stack-name ${stackName}`), { + timeout: 60_000, + }) + .toContain("CREATE_COMPLETE"); + expect(await aws("sqs list-queues")).toContain("mcp-tools-cfn-queue"); + } finally { + await call(mcp, "localstack-deployer", { action: "delete-stack", stackName }); + } + await expect + .poll(() => aws("sqs list-queues"), { timeout: 60_000 }) + .not.toContain("mcp-tools-cfn-queue"); + }); + test("state-management: shows S3 state", async ({ mcp }) => { const state = await call(mcp, "localstack-state-management", { action: "inspect" }); expect(state).toContain("## LocalStack State Inspect"); From 9b3017190d983d92ef996fcdfb22ef6b2269f4d4 Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Thu, 19 Nov 2026 17:58:06 +0100 Subject: [PATCH 2/5] fix(aws-client): keep every AWS CLI request on LocalStack and in the 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 --- .github/dependabot.yml | 5 +- Dockerfile | 4 +- README.md | 3 +- data/sample-cloudformation/template.yaml | 2 +- docs/DOCKER.md | 6 +- src/core/dependency-pins.test.ts | 2 +- src/core/localstack-env.ts | 17 ++- src/lib/aws/aws-cli-sanitizer.test.ts | 29 ++++ src/lib/aws/aws-cli-sanitizer.ts | 56 +++++++- src/lib/aws/child-env.ts | 88 ++++++++++++ src/lib/aws/local-paths.test.ts | 84 +++++++++++ src/lib/aws/local-paths.ts | 134 ++++++++++++++++++ src/lib/aws/lstk-aws.test.ts | 132 +++++++++++++---- src/lib/aws/lstk-aws.ts | 77 ++++++++-- src/lib/azure/egress-guard.ts | 49 ++++++- src/tools-tests/localstack-aws-client.test.ts | 5 +- src/tools/localstack-aws-client.ts | 6 +- src/tools/localstack-deployer.ts | 8 +- tests/mcp/tools.spec.mjs | 33 ++++- 19 files changed, 671 insertions(+), 69 deletions(-) create mode 100644 src/lib/aws/child-env.ts create mode 100644 src/lib/aws/local-paths.test.ts create mode 100644 src/lib/aws/local-paths.ts diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 7aac783..b5da2aa 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -60,12 +60,15 @@ updates: - patch # FROM lines in the Dockerfile: node, hashicorp/terraform, astral-sh/uv and amazon/aws-cli. + # Releases wait 30 days: amazon/aws-cli ships almost daily, and each bump makes users pull its + # layer again. The docker ecosystem has no per-SemVer cooldown and one entry cannot set one per + # image, so the other images wait as long. Security updates are never delayed. - package-ecosystem: docker directory: / schedule: interval: weekly cooldown: - default-days: 7 + default-days: 30 open-pull-requests-limit: 5 groups: docker-minor-patch: diff --git a/Dockerfile b/Dockerfile index 4a77a36..817b578 100644 --- a/Dockerfile +++ b/Dockerfile @@ -53,11 +53,11 @@ ENV DEBIAN_FRONTEND=noninteractive \ UV_LINK_MODE=copy # python3 and python3-pip also serve `sam build` for Python functions (Debian's Python 3.11; -# other Python runtimes need `sam build --use-container`). +# other Python runtimes need `sam build --use-container`). mandoc renders `aws … help`. RUN set -eux; \ apt-get update; \ apt-get install -y --no-install-recommends ca-certificates curl unzip git \ - python3 python3-pip python3-venv; \ + python3 python3-pip python3-venv mandoc; \ apt-get clean; \ rm -rf /var/lib/apt/lists/* diff --git a/README.md b/README.md index 51a8d3f..03a3ac3 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e | [`localstack-state-management`](./src/tools/localstack-state-management.ts) | Manages local file-based LocalStack state export/import workflows | - Export LocalStack state to a local file on disk through the LocalStack State REST API
- Import LocalStack state from a local file
- Inspect current LocalStack state as JSON metamodel data
- Reset all state or only selected services
- Supports service-level granularity for export, reset, and inspect
- Use this for local disk workflows; use Cloud Pods for remote cloud-backed snapshots
- Requires a valid LocalStack Auth Token | | [`localstack-extensions`](./src/tools/localstack-extensions.ts) | Installs, uninstalls, lists, and discovers LocalStack Extensions | - Manage installed extensions (`list`, `install`, `uninstall`) inside the running container
- Browse the LocalStack Extensions marketplace (`available`)
- Requires a valid LocalStack Auth Token | | [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL
- List available ephemeral instances, fetch logs, and delete instances
- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create
- Requires a valid LocalStack Auth Token | -| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands against LocalStack for AWS | - Executes commands with the official AWS CLI v2 through `lstk aws`, so it requires `lstk` and `aws` in your system path
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | +| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands against LocalStack for AWS | - Executes commands with the official AWS CLI v2 through `lstk aws`, so it requires `lstk` and `aws` in your system path
- Keeps every request on LocalStack: the CLI runs without your `~/.aws` and behind a local proxy that refuses other hosts
- Reads and writes local files only inside `LOCALSTACK_AWS_WORKDIR`
- Sanitizes commands to block shell chaining
- Auto-detects LocalStack coverage errors and links to docs | | [`localstack-azure-client`](./src/tools/localstack-azure-client.ts) | Runs Azure CLI (`az`) commands against the LocalStack for Azure emulator | - Runs the Azure CLI installed on your machine with its own profile, never your Azure login
- Blocks shell syntax and commands that would change the profile, install software or never end
- Uses the extensions you installed with `az extension add`
- Requires the Azure CLI and a valid LocalStack Auth Token | | [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN
- Start batch replication jobs, such as SSM parameters under a path prefix
- Poll job status by job ID and list existing jobs
- List resource types supported by the running Replicator extension
- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides | | [`localstack-app-inspector`](./src/tools/localstack-app-inspector.ts) | Inspects LocalStack application traces, spans, events, and IAM evaluations | - Enable or disable App Inspector for the running LocalStack instance
- List and inspect traces to understand AWS service-to-service flows
- Drill into spans, events, payload metadata, and IAM policy evaluation events
- Filter by service, region, operation, resource, ARN, status, and time range
- Requires a valid LocalStack Auth Token and the App Inspector feature in the connected LocalStack license | @@ -227,6 +227,7 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi | `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image | | `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` | | `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` | +| `LOCALSTACK_AWS_WORKDIR` | The directory the AWS client tool runs the AWS CLI in. Local files a command reads or writes (`s3 cp`, `file://`, `--body`, an outfile) must be inside it. Unset in the Docker image, and when the server runs in `/` or your home directory: then only relative paths work, in a private temp directory. | The server's working directory | | `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory | | `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` | diff --git a/data/sample-cloudformation/template.yaml b/data/sample-cloudformation/template.yaml index 78c0f62..35ab907 100644 --- a/data/sample-cloudformation/template.yaml +++ b/data/sample-cloudformation/template.yaml @@ -5,7 +5,7 @@ Resources: Queue: Type: AWS::SQS::Queue Properties: - QueueName: mcp-tools-cfn-queue + QueueName: !Sub "${AWS::StackName}-queue" Outputs: QueueUrl: diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 9547569..f463db8 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -116,6 +116,9 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. ## Known limitations +- **AWS client files.** In the image, the AWS client tool reads and writes local files only in + `LOCALSTACK_AWS_WORKDIR`, which is unset by default. To `s3 cp` your own files, bind-mount their + directory at the same absolute path and set `-e LOCALSTACK_AWS_WORKDIR=`. - **Extra host aliases.** Include the aliases shown in the quick-start command. - **First cold start** of LocalStack can take up to ~2 minutes while the image is pulled and the runtime initializes; subsequent starts reuse the persisted volume. @@ -167,7 +170,8 @@ HARNESS_SKIP=docs,cloudpods,ephemeral,replicator ## Tool versions in the image Each tool's version is pinned in one file, and Dependabot opens the update PRs once a -release is at least 7 days old (its `cooldown`): +release is at least 7 days old (its `cooldown`). The `FROM` images wait 30 days, because the +AWS CLI ships almost daily and each bump re-downloads its layer: | Tool | Pinned in | Dependabot ecosystem | | --- | --- | --- | diff --git a/src/core/dependency-pins.test.ts b/src/core/dependency-pins.test.ts index cfacb33..90ec2e9 100644 --- a/src/core/dependency-pins.test.ts +++ b/src/core/dependency-pins.test.ts @@ -113,7 +113,7 @@ describe("dependency pins", () => { ".github/actions/host-tools/action.yml", ]; const otherInstall = - /setup-terraform|setup-uv|terraform_version|awscli-exe|configure-aws-credentials|\b(?:curl|wget)\b.*\b(?:hashicorp\.com|astral\.sh|astral-sh)\b|\b(?:pipx?|brew|apt(?:-get)?|mise|asdf) install\b.*\b(?:terraform|uv)\b/g; + /setup-terraform|setup-uv|terraform_version|awscli-exe|\b(?:curl|wget)\b.*\b(?:hashicorp\.com|astral\.sh|astral-sh)\b|\b(?:pipx?|brew|apt(?:-get)?|mise|asdf) install\b.*\b(?:terraform|uv)\b/g; for (const file of files) { expect(`${file}: ${read(file).match(otherInstall) ?? []}`).toBe(`${file}: `); } diff --git a/src/core/localstack-env.ts b/src/core/localstack-env.ts index 59bf072..c5e1625 100644 --- a/src/core/localstack-env.ts +++ b/src/core/localstack-env.ts @@ -22,14 +22,21 @@ import { LOCALSTACK_PORT } from "./config"; * Dummy credentials and CDK defaults are injected because CDK bootstrap requires * them even for LocalStack. */ -export function buildIacCliEnv(extra: Record = {}): NodeJS.ProcessEnv { - const base: NodeJS.ProcessEnv = { ...process.env, ...extra }; - - const explicitHost = process.env.LOCALSTACK_HOSTNAME?.trim(); +/** + * The LocalStack endpoint the lstk proxies target: localhost.localstack.cloud for a local + * LocalStack, otherwise LOCALSTACK_HOSTNAME (host.docker.internal in the Docker image). + */ +export function localstackEndpointUrl(env: NodeJS.ProcessEnv = process.env): string { + const explicitHost = env.LOCALSTACK_HOSTNAME?.trim(); const host = !explicitHost || explicitHost === "localhost" || explicitHost === "127.0.0.1" ? "localhost.localstack.cloud" : explicitHost; + return `http://${host}:${env.LOCALSTACK_PORT || LOCALSTACK_PORT}`; +} + +export function buildIacCliEnv(extra: Record = {}): NodeJS.ProcessEnv { + const base: NodeJS.ProcessEnv = { ...process.env, ...extra }; return { ...base, @@ -39,6 +46,6 @@ export function buildIacCliEnv(extra: Record = {}): NodeJS.Proce AWS_REGION: base.AWS_REGION || base.AWS_DEFAULT_REGION || "us-east-1", CDK_DEFAULT_ACCOUNT: base.CDK_DEFAULT_ACCOUNT || "000000000000", CDK_DEFAULT_REGION: base.CDK_DEFAULT_REGION || base.AWS_DEFAULT_REGION || "us-east-1", - AWS_ENDPOINT_URL: base.AWS_ENDPOINT_URL || `http://${host}:${LOCALSTACK_PORT}`, + AWS_ENDPOINT_URL: base.AWS_ENDPOINT_URL || localstackEndpointUrl(), }; } diff --git a/src/lib/aws/aws-cli-sanitizer.test.ts b/src/lib/aws/aws-cli-sanitizer.test.ts index 7349160..aa3d971 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -81,6 +81,35 @@ describe("sanitizeAwsCliCommand", () => { expect(sanitizeAwsCliCommand(command)).toBe(command); }); + test.each([ + "update", + "login", + "sso login --profile x", + "SSO LOGIN", + "history show", + "ssm start-session --target i-1", + "ecs execute-command --cluster c --task t --interactive --command sh", + "codeartifact login --tool npm --domain d --repository r", + "eks update-kubeconfig --name c", + "cloudformation package --template-file t.yaml --s3-bucket b", + "deploy install --config-file c", + "agent-toolkit list-installed-skills", + ])("refuses commands that act on this machine: %s", (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow(/is not allowed|always target LocalStack/); + }); + + test.each([ + "sso list-accounts --access-token t", + "ssm get-parameter --name p", + "eks list-clusters", + ])("allows the API commands of those services: %s", (command) => { + expect(sanitizeAwsCliCommand(command)).toBe(command); + }); + + test("refuses a leading lstk", () => { + expect(() => sanitizeAwsCliCommand("lstk aws s3 ls")).toThrow("must not include"); + }); + test.each(["configure", "configure set region eu-west-1", "configure export-credentials"])( "rejects configure other than list: %s", (command) => { diff --git a/src/lib/aws/aws-cli-sanitizer.ts b/src/lib/aws/aws-cli-sanitizer.ts index fc133f9..25d3d45 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -34,6 +34,53 @@ export function assertTargetsLocalStack(args: string[]): void { } } +const deny = (reason: string, ...prefixes: string[][]) => + prefixes.map((match) => ({ match, reason })); + +/** + * Commands refused before anything runs, matched on the leading command words. The CLI runs + * where this server runs, so these would change this machine, run another program on it, or + * wait for a person. The private HOME and the egress guard cover most of what remains. + */ +export const DENIED: Array<{ match: string[]; reason: string }> = [ + ...deny( + "this downloads and installs software on this machine", + ["update"], + ["deploy", "install"], + ["deploy", "uninstall"] + ), + ...deny( + "this opens a browser or waits for a person to sign in", + ["login"], + ["logout"], + ["sso", "login"], + ["sso", "logout"] + ), + ...deny( + "this opens a shell, a tunnel or a session on this machine", + ["ec2-instance-connect", "ssh"], + ["ec2-instance-connect", "open-tunnel"], + ["ssm", "start-session"], + ["ecs", "execute-command"], + ["emr", "ssh"], + ["emr", "socks"], + ["emr", "get"], + ["emr", "put"], + ["opsworks", "register"] + ), + ...deny( + "this configures other tools on this machine", + ["codeartifact", "login"], + ["eks", "update-kubeconfig"] + ), + ...deny( + "this uploads the local files a template names, which the tool cannot check; use the deployer tool", + ["cloudformation", "package"] + ), + ...deny("the AWS client keeps no history of its own", ["history"]), + ...deny("this manages agent skills on this machine", ["agent-toolkit"]), +]; + export function sanitizeAwsCliCommand(rawCommand: string): string { const command = rawCommand.trim(); if (!command) { @@ -44,8 +91,8 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { throw new Error("Command contains forbidden path traversal."); } - if (/^(?:aws|awslocal)(?:\s|$)/i.test(command)) { - throw new Error("Command must not include the aws or awslocal executable."); + if (/^(?:aws|awslocal|lstk)(?:\s|$)/i.test(command)) { + throw new Error("Command must not include the lstk, aws or awslocal executable."); } if (!/^(?:[a-z][a-z0-9-]*(?:\s+|$)|help$|version$)/i.test(command) || command.startsWith("-")) { @@ -55,6 +102,11 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { const args = splitAwsCliArgs(command); assertTargetsLocalStack(args); + const words = args.map((arg) => arg.toLowerCase()); + const denied = DENIED.find(({ match }) => match.every((word, i) => words[i] === word)); + if (denied) { + throw new Error(`'${denied.match.join(" ")}' is not allowed: ${denied.reason}.`); + } if (args[0]?.toLowerCase() === "configure" && args[1]?.toLowerCase() !== "list") { throw new Error("Only 'configure list' is allowed: the AWS CLI config is not changed."); } diff --git a/src/lib/aws/child-env.ts b/src/lib/aws/child-env.ts new file mode 100644 index 0000000..417d9f6 --- /dev/null +++ b/src/lib/aws/child-env.ts @@ -0,0 +1,88 @@ +import { mkdirSync, mkdtempSync } from "fs"; +import os from "os"; +import path from "path"; + +/** + * The environment `lstk aws` and the AWS CLI run with. Like the Azure tool's, it is built from an + * allow-list, never from a copy of the server's environment: `AWS_*` (profiles, endpoint URLs, + * `AWS_IGNORE_CONFIGURED_ENDPOINT_URLS`, `AWS_DATA_PATH`, credentials) and `LSTK_ENDPOINT_URL` + * would send a command elsewhere or sign it with real credentials. + * + * HOME is private, so neither lstk nor the CLI reads the user's ~/.aws: no profile, no + * credential_process, no plugins, no aliases (`!` aliases run shell commands), no history. Commands + * that write to `~` write there. The egress guard is the proxy for every request, and LocalStack + * is deliberately not in NO_PROXY: botocore picks a client's proxy from its configured endpoint, + * so a request its endpoint rules send elsewhere (a Multi-Region Access Point) would bypass it. + */ + +const INHERITED = ["PATH", "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "LANG", "PATHEXT"]; + +export interface AwsChildDirs { + homeDir: string; + tmpDir: string; +} + +let dirs: AwsChildDirs | undefined; + +/** One private home and temp dir per server process, owner-only. */ +export function privateDirs(): AwsChildDirs { + if (!dirs) { + const root = mkdtempSync(path.join(os.tmpdir(), "localstack-mcp-aws-")); + dirs = { homeDir: path.join(root, "home"), tmpDir: path.join(root, "tmp") }; + for (const dir of Object.values(dirs)) mkdirSync(dir, { recursive: true, mode: 0o700 }); + } + return dirs; +} + +const REGION = /^[a-z]{2}(?:-[a-z]+)+-\d+$/; + +export function buildAwsChildEnv( + parent: NodeJS.ProcessEnv, + platform: NodeJS.Platform, + options: AwsChildDirs & { endpointUrl: string; proxyUrl: string } +): Record { + const env: Record = {}; + const win = platform === "win32"; + for (const name of INHERITED) { + const key = win ? Object.keys(parent).find((k) => k.toUpperCase() === name) : name; + const value = key === undefined ? undefined : parent[key]; + if (value !== undefined) env[name] = value; + } + for (const [name, value] of Object.entries(parent)) { + if (/^LC_[A-Z]+$/.test(name) && value !== undefined) env[name] = value; + } + + env.HOME = options.homeDir; + env.USERPROFILE = options.homeDir; + env.TEMP = options.tmpDir; + env.TMP = options.tmpDir; + if (win) { + env.HOMEDRIVE = path.win32.parse(options.homeDir).root.replace(/[\\/]$/, ""); + env.HOMEPATH = options.homeDir.slice(env.HOMEDRIVE.length) || "\\"; + env.APPDATA = path.win32.join(options.homeDir, "AppData", "Roaming"); + env.LOCALAPPDATA = path.win32.join(options.homeDir, "AppData", "Local"); + } else { + env.TMPDIR = options.tmpDir; + } + + // The user's region is kept: it decides where a resource lives, never which host is called. + const region = [parent.AWS_REGION, parent.AWS_DEFAULT_REGION].find((r) => r && REGION.test(r)); + env.AWS_REGION = region ?? "us-east-1"; + env.AWS_DEFAULT_REGION = env.AWS_REGION; + env.AWS_ACCESS_KEY_ID = "test"; + env.AWS_SECRET_ACCESS_KEY = "test"; + env.AWS_ENDPOINT_URL = options.endpointUrl; + env.AWS_IGNORE_CONFIGURED_ENDPOINT_URLS = "false"; + // Their endpoint rules ignore a custom endpoint; the guard would refuse them anyway. + env.AWS_S3_DISABLE_MULTIREGION_ACCESS_POINTS = "true"; + env.AWS_EC2_METADATA_DISABLED = "true"; + env.AWS_PAGER = ""; + env.AWS_CLI_AUTO_PROMPT = "off"; + + for (const name of ["HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy"]) { + env[name] = options.proxyUrl; + } + // lstk's own analytics would only meet the guard's 403. + env.LOCALSTACK_DISABLE_EVENTS = "1"; + return env; +} diff --git a/src/lib/aws/local-paths.test.ts b/src/lib/aws/local-paths.test.ts new file mode 100644 index 0000000..9059b33 --- /dev/null +++ b/src/lib/aws/local-paths.test.ts @@ -0,0 +1,84 @@ +import fs from "fs"; +import os from "os"; +import path from "path"; +import { assertLocalPathsAllowed, awsWorkdir } from "./local-paths"; + +describe("awsWorkdir", () => { + test("is LOCALSTACK_AWS_WORKDIR when it is a directory, else an error", () => { + const dir = fs.realpathSync(os.tmpdir()); + expect(awsWorkdir({ LOCALSTACK_AWS_WORKDIR: dir })).toEqual({ workdir: dir }); + expect(awsWorkdir({ LOCALSTACK_AWS_WORKDIR: path.join(dir, "no-such-dir-x") })).toMatchObject({ + workdir: null, + error: expect.stringContaining("not an existing directory"), + }); + }); + + test("is the server's directory, but none in Docker, in / or in the home directory", () => { + const cwd = fs.realpathSync(os.tmpdir()); + const home = fs.realpathSync(os.homedir()); + expect(awsWorkdir({}, { cwd, home, inDocker: false })).toEqual({ workdir: cwd }); + expect(awsWorkdir({}, { cwd, home, inDocker: true })).toEqual({ workdir: null }); + expect(awsWorkdir({}, { cwd: "/", home, inDocker: false })).toEqual({ workdir: null }); + expect(awsWorkdir({}, { cwd: home, home, inDocker: false })).toEqual({ workdir: null }); + }); +}); + +describe("assertLocalPathsAllowed", () => { + let workdir: string; + let outside: string; + const home = "/home/someone"; + + beforeAll(() => { + workdir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "aws-workdir-"))); + outside = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "aws-outside-"))); + fs.writeFileSync(path.join(workdir, "in.txt"), "x"); + fs.symlinkSync(outside, path.join(workdir, "escape")); + }); + afterAll(() => { + fs.rmSync(workdir, { recursive: true, force: true }); + fs.rmSync(outside, { recursive: true, force: true }); + }); + + const allowed = (cmd: string, dir: string | null = workdir) => + assertLocalPathsAllowed(cmd.split(" "), dir, { home }); + + test.each([ + "s3 cp in.txt s3://b/in.txt", + "s3 cp s3://b/k out/new.txt", + "s3 cp IN/in.txt s3://b/k", + "lambda invoke --function-name f --payload fileb://in.txt out.json", + "logs filter-log-events --log-group-name /aws/lambda/f", + "ssm get-parameter --name /prod/db/password", + "iam create-role --role-name r --path / --assume-role-policy-document file://in.txt", + "s3api list-objects-v2 --bucket b --prefix /logs/", + "s3api put-object --bucket b --key /a/b --body in.txt", + ])("allows: %s", (cmd) => { + expect(() => allowed(cmd.replace("IN", workdir))).not.toThrow(); + }); + + test.each([ + "s3 cp /etc/hosts s3://b/k", + "s3 cp --recursive /etc s3://b/k", + "s3 sync --delete / s3://b", + "s3 cp s3://b/k ~/.zshrc", + "s3 cp s3://b/k ~root/.ssh/authorized_keys", + "s3 cp s3://b/k --quiet /tmp/new-file", + "s3api get-object --bucket b --key k /tmp/out", + "s3api put-object --bucket b --key k --body /etc/hosts", + "s3api put-object --bucket b --key k --body=/etc/hosts", + "lambda invoke --function-name f --payload file:///etc/hosts out.json", + "sqs send-message --queue-url q --message-body FILE://~/.aws/credentials", + "s3api put-object --bucket b --key k --body escape/secret", + "lambda create-function --function-name f --zip-file fileb://escape/x.zip", + "eks update-kubeconfig --name c --kubeconfig ../x", + "gamelift upload-build --name b --build-root escape", + "ssm get-parameters --names /a /b", + ])("refuses: %s", (cmd) => { + expect(() => allowed(cmd)).toThrow(/outside the AWS client's working directory/); + }); + + test("without a workdir, every absolute path is refused and relative ones stay private", () => { + expect(() => allowed("s3 cp in.txt s3://b/k", null)).not.toThrow(); + expect(() => allowed("s3 cp /tmp/x s3://b/k", null)).toThrow(/no working directory/); + }); +}); diff --git a/src/lib/aws/local-paths.ts b/src/lib/aws/local-paths.ts new file mode 100644 index 0000000..8c74b69 --- /dev/null +++ b/src/lib/aws/local-paths.ts @@ -0,0 +1,134 @@ +import fs from "fs"; +import os from "os"; +import path from "path"; + +/** + * Where the AWS client may read and write local files. The CLI runs where this server runs, so + * `s3 cp s3://b/k ~/.zshrc` would otherwise overwrite a file on the user's machine, and + * `s3 cp ~/.aws/credentials s3://b/c` would hand a secret to the agent. + * + * The working directory is LOCALSTACK_AWS_WORKDIR, or else the server's own directory. There is + * none in the Docker image (the server's code lives there) or when the server runs in `/` or the + * home directory (as some MCP hosts start it): local paths are then refused, except relative + * ones, which resolve in the tool's private temp directory. + */ +export function awsWorkdir( + env: NodeJS.ProcessEnv = process.env, + deps: { cwd?: string; home?: string; inDocker?: boolean } = {} +): { workdir: string | null; error?: string } { + const configured = env.LOCALSTACK_AWS_WORKDIR?.trim(); + if (configured) { + const dir = path.resolve(expandHome(configured, deps.home)); + if (!isDirectory(dir)) { + return { + workdir: null, + error: `LOCALSTACK_AWS_WORKDIR (${dir}) is not an existing directory: set it to the directory that holds the files the AWS client may read and write.`, + }; + } + return { workdir: realpath(dir) }; + } + if (deps.inDocker ?? fs.existsSync("/.dockerenv")) return { workdir: null }; + const cwd = realpath(deps.cwd ?? process.cwd()); + const home = realpath(deps.home ?? os.homedir()); + if (cwd === path.parse(cwd).root || cwd === home) return { workdir: null }; + return { workdir: cwd }; +} + +// Options whose value names a local file or directory, relative or absolute. +const PATH_OPTION = + /^--(?:[a-z0-9-]+-)?(?:file|outfile|body|kubeconfig|root|dir|directory|ca-bundle|block-data)$|^--source$/; +// Options whose value is a name that may start with `/` (IAM paths, SSM parameter and log group +// names, S3 keys and prefixes): never a local path, unless given as file://. +const NAME_OPTION = + /^--(?:[a-z0-9-]+-)?(?:name|names|path|paths|prefix|key|pattern|arn|id|ids|parameter|parameters|resource|resources|route|uri|url|expression|filter|query|location)$/; + +/** + * Throws when an argument names a local path outside the working directory. Every absolute or + * `~` argument counts, whatever comes before it: a boolean flag such as --recursive takes no + * value, so what follows it may well be a path. Only NAME_OPTION values are exempt. + */ +export function assertLocalPathsAllowed( + args: string[], + workdir: string | null, + deps: { home?: string; cwd?: string } = {} +): void { + // Relative paths resolve in the child's working directory: the workdir, or a private temp dir + // where nothing of the user's lives. + const check = (value: string, relativeToo: boolean) => { + // `~user/x` is another user's home to the CLI: always outside. + const isAbsolute = path.isAbsolute(value) || value.startsWith("~"); + if (!isAbsolute && (!relativeToo || workdir === null)) return; + if (isAbsolute && (workdir === null || /^~[^\\/]/.test(value))) throw outside(value, workdir); + const target = isAbsolute + ? path.resolve(expandHome(value, deps.home)) + : path.resolve(workdir as string, value); + const real = realpathOfLongestExisting(target); + if (real !== workdir && !real.startsWith((workdir as string) + path.sep)) { + throw outside(value, workdir); + } + }; + + let previousOption: string | undefined; + for (const arg of args) { + let option = previousOption; + let value = arg; + previousOption = undefined; + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + if (eq === -1) { + previousOption = arg.toLowerCase(); + continue; + } + option = arg.slice(0, eq).toLowerCase(); + value = arg.slice(eq + 1); + } + + const file = value.match(/^fileb?:\/\/([\s\S]*)$/i); + if (file) check(file[1], true); + else if (option !== undefined && PATH_OPTION.test(option)) check(value, true); + else if (option === undefined || !NAME_OPTION.test(option)) check(value, false); + } +} + +function outside(value: string, workdir: string | null): Error { + const where = + workdir === null + ? `The local path '${value}' is not allowed: the AWS client has no working directory here. Set LOCALSTACK_AWS_WORKDIR to the directory that holds your files, or use a relative path.` + : `The local path '${value}' is outside the AWS client's working directory (${workdir}). Use a path inside it, or set LOCALSTACK_AWS_WORKDIR.`; + return new Error( + `${where} A list of names that start with '/' can be given as JSON instead, e.g. --names '["/a","/b"]'.` + ); +} + +function expandHome(value: string, home = os.homedir()): string { + return /^~(?:[\\/]|$)/.test(value) ? path.join(home, value.slice(1)) : value; +} + +function isDirectory(p: string): boolean { + try { + return fs.statSync(p).isDirectory(); + } catch { + return false; + } +} + +function realpath(p: string): string { + try { + return fs.realpathSync(p); + } catch { + return path.resolve(p); + } +} + +/** The real path of `p`, following symlinks in the part of it that exists. */ +function realpathOfLongestExisting(p: string): string { + let existing = p; + const rest: string[] = []; + while (!fs.existsSync(existing)) { + const parent = path.dirname(existing); + if (parent === existing) break; + rest.unshift(path.basename(existing)); + existing = parent; + } + return path.join(realpath(existing), ...rest); +} diff --git a/src/lib/aws/lstk-aws.test.ts b/src/lib/aws/lstk-aws.test.ts index 358ea20..3ade575 100644 --- a/src/lib/aws/lstk-aws.test.ts +++ b/src/lib/aws/lstk-aws.test.ts @@ -1,66 +1,138 @@ import fs from "fs"; +import http from "http"; import os from "os"; import path from "path"; import { runLstkAws } from "./lstk-aws"; -// A stand-in `lstk` on the PATH that, like `lstk aws s3 cp - …`, reads stdin to the end before -// answering, then prints what it was run with. +// A stand-in `lstk` on the PATH. Like `lstk aws s3 cp - …` it reads stdin to the end first. It +// then sends one request through the proxy it was given (to the URL in ./target, since its +// environment is allow-listed), and prints what it ran with and what came back. const FAKE_LSTK = `#!/usr/bin/env node +const http = require("http"); +const target = require("fs").readFileSync("target", "utf8"); let input = ""; process.stdin.on("data", (chunk) => (input += chunk)); process.stdin.on("end", () => { - process.stdout.write("> Note: No AWS profile found, run 'lstk setup aws'\\n"); - process.stdout.write(JSON.stringify({ - args: process.argv.slice(2), - input, - pager: process.env.AWS_PAGER, - endpoint: process.env.AWS_ENDPOINT_URL, - })); + const proxy = new URL(process.env.HTTP_PROXY); + const req = http.request( + { host: proxy.hostname, port: proxy.port, path: target, headers: { host: new URL(target).host } }, + (res) => { + let body = ""; + res.on("data", (c) => (body += c)); + res.on("end", () => { + process.stdout.write("> Note: No AWS profile found, run 'lstk setup aws'\\n"); + process.stdout.write(JSON.stringify({ + args: process.argv.slice(2), + input, + cwd: process.cwd(), + status: res.statusCode, + body, + env: Object.fromEntries(Object.entries(process.env).filter(([k]) => /^(AWS_|LSTK_|HOME$|HTTPS?_PROXY$)/.test(k))), + })); + }); + } + ); + req.end(); }); `; describe("runLstkAws", () => { let binDir: string; - const saved = { - PATH: process.env.PATH, - AWS_ENDPOINT_URL: process.env.AWS_ENDPOINT_URL, - LOCALSTACK_HOSTNAME: process.env.LOCALSTACK_HOSTNAME, - }; + let workdir: string; + let localstack: http.Server; + let localstackPort: number; + const seen: string[] = []; + const saved = { ...process.env }; - beforeAll(() => { + beforeAll(async () => { binDir = fs.mkdtempSync(path.join(os.tmpdir(), "fake-lstk-")); + workdir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "aws-workdir-"))); fs.writeFileSync(path.join(binDir, "lstk"), FAKE_LSTK, { mode: 0o755 }); + localstack = http.createServer((req, res) => { + seen.push(`${req.headers.host} ${req.url}`); + res.end("from localstack"); + }); + await new Promise((resolve) => localstack.listen(0, "127.0.0.1", resolve)); + localstackPort = (localstack.address() as { port: number }).port; + process.env.PATH = `${binDir}${path.delimiter}${saved.PATH}`; - delete process.env.AWS_ENDPOINT_URL; delete process.env.LOCALSTACK_HOSTNAME; + process.env.LOCALSTACK_PORT = String(localstackPort); + process.env.LOCALSTACK_AWS_WORKDIR = workdir; + // What a user's shell might hold; none of it may reach the CLI. + process.env.AWS_PROFILE = "prod"; + process.env.AWS_ACCESS_KEY_ID = "AKIAREALKEY000000000"; + process.env.AWS_ENDPOINT_URL_S3 = "https://s3.amazonaws.com"; + process.env.AWS_IGNORE_CONFIGURED_ENDPOINT_URLS = "true"; + process.env.LSTK_ENDPOINT_URL = "https://example.com"; + process.env.AWS_REGION = "eu-west-1"; }); - afterAll(() => { - for (const [key, value] of Object.entries(saved)) { - if (value === undefined) delete process.env[key]; - else process.env[key] = value; - } + afterAll(async () => { + process.env = saved; + await new Promise((resolve) => localstack.close(() => resolve())); fs.rmSync(binDir, { recursive: true, force: true }); + fs.rmSync(workdir, { recursive: true, force: true }); }); - test("gives the CLI no stdin, so a command reading it ends instead of waiting", async () => { - const result = await runLstkAws(["s3", "cp", "-", "s3://bucket/key"]); + const run = async (target: string, args = ["s3", "ls"]) => { + fs.writeFileSync(path.join(workdir, "target"), target); + const result = await runLstkAws(args, { checkLocalPaths: true }); + return { result, out: JSON.parse(result.stdout) }; + }; + test("gives the CLI no stdin, so a command reading it ends instead of waiting", async () => { + const { result, out } = await run(`http://localhost.localstack.cloud:${localstackPort}/`, [ + "s3", + "cp", + "-", + "s3://bucket/key", + ]); expect(result.exitCode).toBe(0); - expect(JSON.parse(result.stdout)).toEqual({ - args: ["aws", "s3", "cp", "-", "s3://bucket/key"], - input: "", - pager: "", - endpoint: "http://localhost.localstack.cloud:4566", + expect(out.args).toEqual(["aws", "s3", "cp", "-", "s3://bucket/key"]); + expect(out.input).toBe(""); + }, 10_000); + + test("runs in the workdir with a private home and only the AWS settings it pins", async () => { + const { out } = await run(`http://localhost.localstack.cloud:${localstackPort}/`); + expect(out.cwd).toBe(workdir); + expect(out.env.HOME).not.toBe(os.homedir()); + expect(out.env).toMatchObject({ + AWS_ENDPOINT_URL: `http://localhost.localstack.cloud:${localstackPort}`, + AWS_ACCESS_KEY_ID: "test", + AWS_REGION: "eu-west-1", + AWS_PAGER: "", + AWS_IGNORE_CONFIGURED_ENDPOINT_URLS: "false", + AWS_S3_DISABLE_MULTIREGION_ACCESS_POINTS: "true", }); - }, 5_000); + for (const name of ["AWS_PROFILE", "AWS_ENDPOINT_URL_S3", "LSTK_ENDPOINT_URL"]) { + expect(out.env).not.toHaveProperty(name); + } + }, 10_000); - test("refuses an argv that would leave LocalStack before starting anything", async () => { + test("relays requests for LocalStack and its subdomains, keeping their Host", async () => { + const host = `bucket.localhost.localstack.cloud:${localstackPort}`; + const { result, out } = await run(`http://${host}/key`); + expect(out).toMatchObject({ status: 200, body: "from localstack" }); + expect(seen).toContain(`${host} /key`); + expect(result.blocked).toEqual([]); + }, 10_000); + + test("stops a request to any other host and reports it", async () => { + const { result, out } = await run("http://s3.amazonaws.com/bucket"); + expect(out.status).toBe(403); + expect(result.blocked).toEqual(["http://s3.amazonaws.com"]); + }, 10_000); + + test("refuses an argv that would leave LocalStack or the workdir before starting anything", async () => { await expect(runLstkAws(["sqs", "list-queues", "--endp", "https://x"])).rejects.toThrow( "commands always target LocalStack" ); await expect( runLstkAws(["cloudformation", "delete-stack", "--stack-name", "help"]) ).rejects.toThrow("may only end a help request"); + await expect( + runLstkAws(["s3", "cp", "/etc/hosts", "s3://b/k"], { checkLocalPaths: true }) + ).rejects.toThrow("outside the AWS client's working directory"); }); }); diff --git a/src/lib/aws/lstk-aws.ts b/src/lib/aws/lstk-aws.ts index 5294622..d9a665c 100644 --- a/src/lib/aws/lstk-aws.ts +++ b/src/lib/aws/lstk-aws.ts @@ -1,7 +1,10 @@ import { runCommand, type CommandResult } from "../../core/command-runner"; -import { buildIacCliEnv } from "../../core/localstack-env"; +import { localstackEndpointUrl } from "../../core/localstack-env"; +import { startEgressGuard } from "../azure/egress-guard"; import { LSTK_INSTALL_MESSAGE } from "../deployment/deployment-utils"; import { assertTargetsLocalStack } from "./aws-cli-sanitizer"; +import { buildAwsChildEnv, privateDirs } from "./child-env"; +import { assertLocalPathsAllowed, awsWorkdir } from "./local-paths"; const AWS_CLI_INSTALL_MESSAGE = `❌ The AWS CLI is not installed or not available in PATH. @@ -15,35 +18,87 @@ After installation, make sure the 'aws' command is available in your PATH.`; // in front of the AWS CLI's output. const NO_PROFILE_NOTE = /^> Note: No AWS profile found, run 'lstk setup aws'\r?\n/; +let dependenciesFound = false; + +/** Tests: forget that the CLIs were found. */ +export function resetLstkAwsDependencyCheck(): void { + dependenciesFound = false; +} + /** Returns an install hint when lstk or the AWS CLI is missing, otherwise null. */ export async function checkLstkAwsDependencies(): Promise { + if (dependenciesFound) return null; const [lstk, aws] = await Promise.all([ runCommand("lstk", ["--version"], { timeout: 10000 }), runCommand("aws", ["--version"], { timeout: 10000 }), ]); if (lstk.error) return LSTK_INSTALL_MESSAGE; if (aws.error) return AWS_CLI_INSTALL_MESSAGE; + dependenciesFound = true; return null; } +export interface LstkAwsResult extends CommandResult { + /** Hosts outside LocalStack the egress guard refused; any entry means the command failed. */ + blocked: string[]; +} + /** * Runs `lstk aws `: the official AWS CLI, with endpoint, credentials and region set by - * lstk. The endpoint comes from AWS_ENDPOINT_URL (see buildIacCliEnv), and the pager is off - * because the output goes to the MCP client, not a terminal. + * lstk. It runs with the environment of child-env.ts behind an egress guard that relays plain + * HTTP to LocalStack and refuses everything else, in the AWS client's working directory. + * `checkLocalPaths` holds the local paths in `args` to that directory (local-paths.ts). */ -export async function runLstkAws(args: string[]): Promise { +export async function runLstkAws( + args: string[], + options: { checkLocalPaths?: boolean } = {} +): Promise { assertTargetsLocalStack(args); - // No stdin: lstk hands it on to aws, and a command reading it (`s3 cp - …`) would otherwise - // wait for input that never comes until the timeout. - const result = await runCommand("lstk", ["aws", ...args], { - env: buildIacCliEnv({ AWS_PAGER: "" }), - stdio: ["ignore", "pipe", "pipe"], + const { workdir, error } = awsWorkdir(); + if (error) throw new Error(error); + const dirs = privateDirs(); + if (options.checkLocalPaths) assertLocalPathsAllowed(args, workdir); + + const endpointUrl = localstackEndpointUrl(); + const endpoint = new URL(endpointUrl); + const port = Number(endpoint.port || 80); + const guard = await startEgressGuard({ + tunnels: () => false, + relayHttp: { + allows: (host, p) => + p === port && (host === endpoint.hostname || host.endsWith(`.${endpoint.hostname}`)), + // localhost.localstack.cloud is 127.0.0.1 by definition; no DNS answer is needed for it. + to: { + host: endpoint.hostname === "localhost.localstack.cloud" ? "127.0.0.1" : endpoint.hostname, + port, + }, + }, }); - return { ...result, stdout: result.stdout.replace(NO_PROFILE_NOTE, "") }; + try { + // No stdin: lstk hands it on to aws, and a command reading it (`s3 cp - …`) would otherwise + // wait for input that never comes until the timeout. + const result = await runCommand("lstk", ["aws", ...args], { + env: buildAwsChildEnv(process.env, process.platform, { + ...dirs, + endpointUrl, + proxyUrl: guard.env.HTTP_PROXY, + }), + cwd: workdir ?? dirs.tmpDir, + stdio: ["ignore", "pipe", "pipe"], + }); + // Help pages come through man as overstrike (`N\bNA\bAM\bME\bE`); keep the letters. + const stdout = result.stdout.replace(NO_PROFILE_NOTE, "").replace(/[^\n]\x08/g, ""); + return { ...result, stdout, blocked: guard.refused() }; + } finally { + await guard.close(); + } } /** The error text of a failed `lstk aws` run; lstk reports its own failures on stdout. */ -export function lstkAwsErrorText(result: CommandResult): string { +export function lstkAwsErrorText(result: LstkAwsResult): string { + if (result.blocked.length > 0) { + return `The command tried to reach ${result.blocked.join(", ")}, outside LocalStack, and was stopped: the AWS client only talks to LocalStack.\n\n${result.stderr.trim()}`.trim(); + } return ( result.stderr.trim() || result.stdout.trim() || diff --git a/src/lib/azure/egress-guard.ts b/src/lib/azure/egress-guard.ts index cc4b00b..d6d338e 100644 --- a/src/lib/azure/egress-guard.ts +++ b/src/lib/azure/egress-guard.ts @@ -1,4 +1,9 @@ -import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; +import { + createServer, + request as httpRequest, + type IncomingMessage, + type ServerResponse, +} from "node:http"; import { connect, type AddressInfo, type Socket } from "node:net"; import type { Duplex } from "node:stream"; import { isLocalHost } from "./config"; @@ -26,6 +31,17 @@ export interface EgressGuard { export interface EgressGuardOptions { /** Tests: opens the connection to an allowed target; `host` is always 127.0.0.1 or ::1. */ connect?: (port: number, host: string) => Socket; + /** Which CONNECT targets may be tunnelled to loopback (default: isLocalHost). */ + tunnels?: (hostname: string) => boolean; + /** + * The AWS client's plain-HTTP emulator: a request whose URL `allows` is relayed to `to` with + * its Host header kept, so LocalStack still sees virtual-host names. Without it plain HTTP is + * always refused. + */ + relayHttp?: { + allows: (hostname: string, port: number) => boolean; + to: { host: string; port: number }; + }; } /** Answers a raw socket and ends it; reading on lets the answer arrive before the close. */ @@ -61,7 +77,7 @@ export async function startEgressGuard(options: EgressGuardOptions = {}): Promis if (!url || !/:\d+$/.test(target) || url.href !== `${url.origin}/`) { return reply(client, "400 Bad Request"); } - if (!isLocalHost(url.hostname)) { + if (!(options.tunnels ?? isLocalHost)(url.hostname)) { refused.add(url.hostname); return reply(client, `403 blocked by the egress guard: ${url.hostname}`); } @@ -90,13 +106,40 @@ export async function startEgressGuard(options: EgressGuardOptions = {}): Promis } }; - /** Plain HTTP is never relayed: the emulator's endpoints are https. */ + const relay = (req: IncomingMessage, res: ServerResponse, url: URL) => { + const to = options.relayHttp!.to; + const headers = { ...req.headers }; + delete headers["proxy-connection"]; + delete headers["proxy-authorization"]; + const upstream = httpRequest({ + host: to.host, + port: to.port, + method: req.method, + path: `${url.pathname}${url.search}`, + headers, + }); + upstream.on("error", () => { + if (!res.headersSent) res.writeHead(502, "Bad Gateway", { "Content-Length": 0 }); + res.destroy(); + }); + upstream.on("response", (answer) => { + answer.on("error", () => res.destroy()); + res.writeHead(answer.statusCode ?? 502, answer.statusMessage, answer.rawHeaders); + answer.pipe(res); + }); + req.pipe(upstream); + }; + + /** Plain HTTP is relayed only to the AWS client's emulator (relayHttp); Azure's is https. */ const refusePlainHttp = (req: IncomingMessage, res: ServerResponse) => { req.on("error", () => undefined); res.on("error", () => undefined); try { const raw = req.url ?? ""; const url = /^http:\/\//i.test(raw) && URL.canParse(raw) ? new URL(raw) : undefined; + if (url && options.relayHttp?.allows(url.hostname, Number(url.port || 80))) { + return relay(req, res, url); + } if (url) refused.add(`http://${url.host}`); const reason = url ? `blocked by the egress guard: http://${url.host}` : "Bad Request"; res.writeHead(url ? 403 : 400, reason, { "Content-Length": 0, Connection: "close" }); diff --git a/src/tools-tests/localstack-aws-client.test.ts b/src/tools-tests/localstack-aws-client.test.ts index a712ec9..4376a15 100644 --- a/src/tools-tests/localstack-aws-client.test.ts +++ b/src/tools-tests/localstack-aws-client.test.ts @@ -4,6 +4,7 @@ import path from "path"; import localstackAwsClient from "../tools/localstack-aws-client"; import localstackDeployer from "../tools/localstack-deployer"; import { runCommand, type CommandResult } from "../core/command-runner"; +import { resetLstkAwsDependencyCheck } from "../lib/aws/lstk-aws"; // The deployer's other parameters, which the CloudFormation actions ignore. const deployerDefaults = { @@ -61,6 +62,7 @@ const text = (r: { content: Array<{ text: string }> }) => r.content[0].text; describe("localstack-aws-client", () => { beforeEach(() => { jest.clearAllMocks(); + resetLstkAwsDependencyCheck(); process.env.LOCALSTACK_AUTH_TOKEN = "ls-test-token"; delete process.env.AWS_ENDPOINT_URL; delete process.env.LOCALSTACK_HOSTNAME; @@ -140,6 +142,7 @@ describe("localstack-deployer CloudFormation actions", () => { beforeEach(() => { jest.clearAllMocks(); + resetLstkAwsDependencyCheck(); process.env.LOCALSTACK_AUTH_TOKEN = "ls-test-token"; }); @@ -215,7 +218,7 @@ describe("localstack-deployer CloudFormation actions", () => { }); expect(result.isError).toBe(true); - expect(text(result)).toContain("may only end a help request"); + expect(text(result)).toContain("lstk reads it as a request for the AWS CLI's help"); expect(lstkAwsCalls()).toHaveLength(0); }); }); diff --git a/src/tools/localstack-aws-client.ts b/src/tools/localstack-aws-client.ts index 6edc2a4..3adcc84 100644 --- a/src/tools/localstack-aws-client.ts +++ b/src/tools/localstack-aws-client.ts @@ -21,7 +21,7 @@ export const schema = { export const metadata: ToolMetadata = { name: "localstack-aws-client", description: - "Executes an AWS CLI command against the running LocalStack for AWS emulator, through the official AWS CLI v2 and 'lstk aws', which set the endpoint, credentials and region.", + "Executes an AWS CLI command against the running LocalStack for AWS emulator, through the official AWS CLI v2 and 'lstk aws', which set the endpoint, credentials and region. Requests only ever reach LocalStack. Local files (s3 cp, file://, --body, an outfile) must be relative paths or inside the tool's working directory.", annotations: { title: "LocalStack AWS Client", }, @@ -38,9 +38,9 @@ export default async function localstackAwsClient({ command }: InferSchema { // The template is read by the AWS CLI where the server runs, then the stack's queue is read // back through the AWS client tool. test("deployer: creates and deletes a CloudFormation stack", async ({ mcp }) => { - const stackName = `${PREFIX}-cfn`; + // Unique per run, so a run killed before its delete-stack never blocks the next one. + const stackName = `${PREFIX}-cfn-${RUN}`; + const queue = `${stackName}-queue`; const aws = (command) => call(mcp, "localstack-aws-client", { command }); await call(mcp, "localstack-deployer", { action: "create-stack", @@ -98,13 +101,31 @@ test.describe("tools against a running LocalStack", () => { timeout: 60_000, }) .toContain("CREATE_COMPLETE"); - expect(await aws("sqs list-queues")).toContain("mcp-tools-cfn-queue"); + expect(await aws("sqs list-queues")).toContain(queue); } finally { await call(mcp, "localstack-deployer", { action: "delete-stack", stackName }); } - await expect - .poll(() => aws("sqs list-queues"), { timeout: 60_000 }) - .not.toContain("mcp-tools-cfn-queue"); + await expect.poll(() => aws("sqs list-queues"), { timeout: 60_000 }).not.toContain(queue); + }); + + // Each refusal must come from the tool, not from AWS: none of these may leave LocalStack or + // touch a file outside the server's working directory. + test("aws-client: keeps commands on LocalStack and in its working directory", async ({ mcp }) => { + const refused = async (command, pattern) => { + const { isError, text } = await callRaw(mcp, "localstack-aws-client", { command }); + expect(isError, `${command}:\n${text}`).toBe(true); + expect(text, command).toMatch(pattern); + }; + await refused( + "s3api list-objects-v2 --bucket arn:aws:s3::123456789012:accesspoint/mcp.mrap", + /Multi-Region Access Point ARNs are disabled/ + ); + await refused( + "sqs list-queues --endp https://sqs.us-east-1.amazonaws.com", + /target LocalStack/ + ); + await refused("s3 cp /etc/hosts s3://mcp-tools-bucket/hosts", /outside the AWS client's/); + await refused("update", /not allowed/); }); test("state-management: shows S3 state", async ({ mcp }) => { From 6e825910e86da8ee8501bc9d574220f8ed19187e Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Thu, 19 Nov 2026 18:12:34 +0100 Subject: [PATCH 3/5] fix(aws-client): take local-file options from the AWS CLI source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- src/lib/aws/aws-cli-sanitizer.test.ts | 5 +++- src/lib/aws/aws-cli-sanitizer.ts | 10 +++++++ src/lib/aws/local-paths.test.ts | 18 +++++++++++- src/lib/aws/local-paths.ts | 40 ++++++++++++++++++++++----- 4 files changed, 64 insertions(+), 9 deletions(-) diff --git a/src/lib/aws/aws-cli-sanitizer.test.ts b/src/lib/aws/aws-cli-sanitizer.test.ts index aa3d971..944086e 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -94,8 +94,11 @@ describe("sanitizeAwsCliCommand", () => { "cloudformation package --template-file t.yaml --s3-bucket b", "deploy install --config-file c", "agent-toolkit list-installed-skills", + "wizard", + "logs start-live-tail --log-group-identifiers g", + "logs tail /aws/lambda/f --follow", ])("refuses commands that act on this machine: %s", (command) => { - expect(() => sanitizeAwsCliCommand(command)).toThrow(/is not allowed|always target LocalStack/); + expect(() => sanitizeAwsCliCommand(command)).toThrow(/not allowed|always target LocalStack/); }); test.each([ diff --git a/src/lib/aws/aws-cli-sanitizer.ts b/src/lib/aws/aws-cli-sanitizer.ts index 25d3d45..c6a1a5f 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -78,6 +78,11 @@ export const DENIED: Array<{ match: string[]; reason: string }> = [ ["cloudformation", "package"] ), ...deny("the AWS client keeps no history of its own", ["history"]), + ...deny("this streams until it is stopped; read the events with filter-log-events instead", [ + "logs", + "start-live-tail", + ]), + ...deny("this needs a person to answer its prompts", ["wizard"]), ...deny("this manages agent skills on this machine", ["agent-toolkit"]), ]; @@ -107,6 +112,11 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { if (denied) { throw new Error(`'${denied.match.join(" ")}' is not allowed: ${denied.reason}.`); } + if (words[0] === "logs" && words[1] === "tail" && words.some((w) => /^--follow(?:=|$)/.test(w))) { + throw new Error( + "'logs tail --follow' is not allowed: it streams until it is stopped. Use 'logs tail' with --since instead." + ); + } if (args[0]?.toLowerCase() === "configure" && args[1]?.toLowerCase() !== "list") { throw new Error("Only 'configure list' is allowed: the AWS CLI config is not changed."); } diff --git a/src/lib/aws/local-paths.test.ts b/src/lib/aws/local-paths.test.ts index 9059b33..9592637 100644 --- a/src/lib/aws/local-paths.test.ts +++ b/src/lib/aws/local-paths.test.ts @@ -32,6 +32,7 @@ describe("assertLocalPathsAllowed", () => { workdir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "aws-workdir-"))); outside = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "aws-outside-"))); fs.writeFileSync(path.join(workdir, "in.txt"), "x"); + fs.writeFileSync(path.join(outside, "key.pem"), "secret"); fs.symlinkSync(outside, path.join(workdir, "escape")); }); afterAll(() => { @@ -52,6 +53,9 @@ describe("assertLocalPathsAllowed", () => { "iam create-role --role-name r --path / --assume-role-policy-document file://in.txt", "s3api list-objects-v2 --bucket b --prefix /logs/", "s3api put-object --bucket b --key /a/b --body in.txt", + "lambda invoke --function-name f --payload {} out.json", + "lambda create-function --function-name f --code ZipFile@=fileb://in.txt", + "ecs run-task --task-definition web:3", ])("allows: %s", (cmd) => { expect(() => allowed(cmd.replace("IN", workdir))).not.toThrow(); }); @@ -73,8 +77,20 @@ describe("assertLocalPathsAllowed", () => { "eks update-kubeconfig --name c --kubeconfig ../x", "gamelift upload-build --name b --build-root escape", "ssm get-parameters --names /a /b", + "servicecatalog generate provisioning-artifact --file-path OUT/key.pem --bucket-name b", + "ec2 get-password-data --instance-id i-1 --priv-launch-key OUT/key.pem", + "cloudfront sign --url u --key-pair-id k --private-key OUT/key.pem --date-less-than 1", + "gamelift get-game-session-log --game-session-id g --save-as OUT/log.zip", + "cloudtrail verify-query-results --local-export-path OUT/x", + "lambda-web deploy --code OUT", + "ecs deploy --service s --task-definition OUT/td.json --codedeploy-appspec OUT/a.json", + "lambda create-function --function-name f --code ZipFile@=fileb://OUT/x.zip", + "sqs send-message --queue-url q --message-attributes a={DataType=Binary,BinaryValue@=fileb://OUT/key.pem}", + "s3api head-object --bucket b --key OUT/key.pem", ])("refuses: %s", (cmd) => { - expect(() => allowed(cmd)).toThrow(/outside the AWS client's working directory/); + expect(() => allowed(cmd.replace(/OUT/g, outside))).toThrow( + /outside the AWS client's working directory/ + ); }); test("without a workdir, every absolute path is refused and relative ones stay private", () => { diff --git a/src/lib/aws/local-paths.ts b/src/lib/aws/local-paths.ts index 8c74b69..b879416 100644 --- a/src/lib/aws/local-paths.ts +++ b/src/lib/aws/local-paths.ts @@ -34,11 +34,21 @@ export function awsWorkdir( return { workdir: cwd }; } -// Options whose value names a local file or directory, relative or absolute. -const PATH_OPTION = - /^--(?:[a-z0-9-]+-)?(?:file|outfile|body|kubeconfig|root|dir|directory|ca-bundle|block-data)$|^--source$/; +// Options whose value names a local file or directory, relative or absolute. Taken from the +// AWS CLI v2 source: API parameters only take a local file through file://, fileb://, a +// streaming blob (the second line, from the service models) or a streaming operation's +// positional outfile, so the rest are customizations (the last line). +const PATH_OPTION = new RegExp( + "^--(?:[a-z0-9-]+-)?(?:file|outfile)$|^--(?:" + + [ + "body|block-data|annotation-payload|asset-content|documents|input-stream|invoke-args|payload", + "kubeconfig|ca-bundle|file-path|priv-launch-key|private-key|save-as|local-export-path|build-root|source|code|task-definition|codedeploy-appspec|dir|src|dest", + ].join("|") + + ")$" +); // Options whose value is a name that may start with `/` (IAM paths, SSM parameter and log group -// names, S3 keys and prefixes): never a local path, unless given as file://. +// names, S3 keys and prefixes). Their values are not checked, unless one names an existing +// file: an option missing from PATH_OPTION would read it. const NAME_OPTION = /^--(?:[a-z0-9-]+-)?(?:name|names|path|paths|prefix|key|pattern|arn|id|ids|parameter|parameters|resource|resources|route|uri|url|expression|filter|query|location)$/; @@ -83,10 +93,18 @@ export function assertLocalPathsAllowed( value = arg.slice(eq + 1); } - const file = value.match(/^fileb?:\/\/([\s\S]*)$/i); - if (file) check(file[1], true); - else if (option !== undefined && PATH_OPTION.test(option)) check(value, true); + // A whole value that is file://… names one path (commas and all). Inside a value, shorthand + // loads files with `key@=file://path`, and a list may hold several. + const whole = value.match(/^fileb?:\/\/([\s\S]*)$/i); + if (whole) { + check(whole[1], true); + continue; + } + for (const m of value.matchAll(/fileb?:\/\/([^,\]}"'\s]*)/gi)) check(m[1], true); + + if (option !== undefined && PATH_OPTION.test(option)) check(value, true); else if (option === undefined || !NAME_OPTION.test(option)) check(value, false); + else if (value !== "/" && isFile(expandHome(value, deps.home))) check(value, false); } } @@ -104,6 +122,14 @@ function expandHome(value: string, home = os.homedir()): string { return /^~(?:[\\/]|$)/.test(value) ? path.join(home, value.slice(1)) : value; } +function isFile(p: string): boolean { + try { + return (path.isAbsolute(p) || p.startsWith("~")) && fs.statSync(p).isFile(); + } catch { + return false; + } +} + function isDirectory(p: string): boolean { try { return fs.statSync(p).isDirectory(); From 56713fd94d2be770f79983025e3c40a6ba8d1d23 Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Thu, 19 Nov 2026 18:28:18 +0100 Subject: [PATCH 4/5] fix(aws-client): resolve every local path and match the deny list past 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 --- src/lib/aws/aws-cli-sanitizer.test.ts | 20 ++++++++++ src/lib/aws/aws-cli-sanitizer.ts | 20 +++++++++- src/lib/aws/child-env.ts | 3 +- src/lib/aws/local-paths.test.ts | 42 +++++++++++++++++++- src/lib/aws/local-paths.ts | 56 ++++++++++++++++++++------- src/lib/aws/lstk-aws.test.ts | 3 +- src/lib/aws/lstk-aws.ts | 7 +++- tests/mcp/tools.spec.mjs | 43 ++++++++++++++++++++ 8 files changed, 171 insertions(+), 23 deletions(-) diff --git a/src/lib/aws/aws-cli-sanitizer.test.ts b/src/lib/aws/aws-cli-sanitizer.test.ts index 944086e..f54109d 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -97,6 +97,10 @@ describe("sanitizeAwsCliCommand", () => { "wizard", "logs start-live-tail --log-group-identifiers g", "logs tail /aws/lambda/f --follow", + "cloudformation --no-cli-pager package --template-file t.yaml --s3-bucket b", + "ec2-instance-connect --no-paginate ssh --instance-id i-1", + "ssm --region us-east-1 start-session --target i-1", + "logs --color off tail x --follow", ])("refuses commands that act on this machine: %s", (command) => { expect(() => sanitizeAwsCliCommand(command)).toThrow(/not allowed|always target LocalStack/); }); @@ -109,6 +113,22 @@ describe("sanitizeAwsCliCommand", () => { expect(sanitizeAwsCliCommand(command)).toBe(command); }); + test.each([ + "s3 cp '..'/outside/secret s3://b/k", + `s3 cp ."."/outside/secret s3://b/k`, + `s3 cp s3://b/k "../outside/x"`, + "s3 cp --body='..'/x s3://b/k", + ])("rejects path traversal hidden by quotes: %s", (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow("forbidden path traversal"); + }); + + test.each(["s3 ls --config '..'x", "s3 ls --config=x.toml", "s3 ls --CONFIG x"])( + "rejects lstk's own --config: %s", + (command) => { + expect(() => sanitizeAwsCliCommand(command)).toThrow(/--config|path traversal/); + } + ); + test("refuses a leading lstk", () => { expect(() => sanitizeAwsCliCommand("lstk aws s3 ls")).toThrow("must not include"); }); diff --git a/src/lib/aws/aws-cli-sanitizer.ts b/src/lib/aws/aws-cli-sanitizer.ts index c6a1a5f..cfcea90 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -19,6 +19,11 @@ export function assertTargetsLocalStack(args: string[]): void { ); } } + // lstk strips its own --config from anywhere in the command and reads that file. + const lstkFlag = args.find((arg) => /^--config(?:=|$)/i.test(arg)); + if (lstkFlag) { + throw new Error(`Option '--config' is not allowed: lstk would read it as its own config file.`); + } // lstk answers any help token itself and then runs aws without its endpoint and credential // handling, so an API call with a `help` value would leave LocalStack. Only a pure help // request, command words followed by one trailing help token, may contain one. @@ -107,12 +112,23 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { const args = splitAwsCliArgs(command); assertTargetsLocalStack(args); + // On the parsed argv: a quote splits `..` in the raw string ('..'/x, ."."/x). + if (args.some((arg) => /(?:^|[\\/=]|:\/\/)\.\.(?:[\\/]|$)/.test(arg))) { + throw new Error("Command contains forbidden path traversal."); + } + + // The service is always the first word. The CLI accepts global options (--region, --output, + // --no-cli-pager, ...) before the operation, so a denied operation may come at any later + // position: matching any later word refuses the rare value that happens to equal it. const words = args.map((arg) => arg.toLowerCase()); - const denied = DENIED.find(({ match }) => match.every((word, i) => words[i] === word)); + const has = (word: string) => words.slice(1).includes(word); + const denied = DENIED.find( + ({ match }) => words[0] === match[0] && (match.length === 1 || has(match[1])) + ); if (denied) { throw new Error(`'${denied.match.join(" ")}' is not allowed: ${denied.reason}.`); } - if (words[0] === "logs" && words[1] === "tail" && words.some((w) => /^--follow(?:=|$)/.test(w))) { + if (words[0] === "logs" && has("tail") && words.some((w) => /^--follow(?:=|$)/.test(w))) { throw new Error( "'logs tail --follow' is not allowed: it streams until it is stopped. Use 'logs tail' with --since instead." ); diff --git a/src/lib/aws/child-env.ts b/src/lib/aws/child-env.ts index 417d9f6..76ef2a9 100644 --- a/src/lib/aws/child-env.ts +++ b/src/lib/aws/child-env.ts @@ -9,7 +9,8 @@ import path from "path"; * would send a command elsewhere or sign it with real credentials. * * HOME is private, so neither lstk nor the CLI reads the user's ~/.aws: no profile, no - * credential_process, no plugins, no aliases (`!` aliases run shell commands), no history. Commands + * credential_process, no plugins, no aliases (`!` aliases run shell commands), no history. The + * AWS client's path check keeps every command out of it, so none can write an alias there. Commands * that write to `~` write there. The egress guard is the proxy for every request, and LocalStack * is deliberately not in NO_PROXY: botocore picks a client's proxy from its configured endpoint, * so a request its endpoint rules send elsewhere (a Multi-Region Access Point) would bypass it. diff --git a/src/lib/aws/local-paths.test.ts b/src/lib/aws/local-paths.test.ts index 9592637..6471a31 100644 --- a/src/lib/aws/local-paths.test.ts +++ b/src/lib/aws/local-paths.test.ts @@ -1,7 +1,7 @@ import fs from "fs"; import os from "os"; import path from "path"; -import { assertLocalPathsAllowed, awsWorkdir } from "./local-paths"; +import { assertLocalPathsAllowed, awsWorkdir, withoutFollowingSymlinks } from "./local-paths"; describe("awsWorkdir", () => { test("is LOCALSTACK_AWS_WORKDIR when it is a directory, else an error", () => { @@ -41,7 +41,11 @@ describe("assertLocalPathsAllowed", () => { }); const allowed = (cmd: string, dir: string | null = workdir) => - assertLocalPathsAllowed(cmd.split(" "), dir, { home }); + assertLocalPathsAllowed(cmd.split(" "), dir, { + home, + cwd: path.join(outside, "tmp"), + privateHome: path.join(outside, "home"), + }); test.each([ "s3 cp in.txt s3://b/in.txt", @@ -87,6 +91,11 @@ describe("assertLocalPathsAllowed", () => { "lambda create-function --function-name f --code ZipFile@=fileb://OUT/x.zip", "sqs send-message --queue-url q --message-attributes a={DataType=Binary,BinaryValue@=fileb://OUT/key.pem}", "s3api head-object --bucket b --key OUT/key.pem", + "s3 cp ../x s3://b/k", + "s3 cp s3://b/k sub/../../x", + "s3 cp escape/secret s3://b/k", + "s3 cp s3://b/k --quiet ../outside-new", + "s3 cp --region us-east-1 escape s3://b/k", ])("refuses: %s", (cmd) => { expect(() => allowed(cmd.replace(/OUT/g, outside))).toThrow( /outside the AWS client's working directory/ @@ -96,5 +105,34 @@ describe("assertLocalPathsAllowed", () => { test("without a workdir, every absolute path is refused and relative ones stay private", () => { expect(() => allowed("s3 cp in.txt s3://b/k", null)).not.toThrow(); expect(() => allowed("s3 cp /tmp/x s3://b/k", null)).toThrow(/no working directory/); + // The private home sits next to the private temp dir. + expect(() => allowed("s3 cp s3://b/alias ../home/.aws/cli/alias", null)).toThrow( + /no working directory/ + ); + }); + + test("the private home stays off limits inside a broad workdir", () => { + expect(() => + assertLocalPathsAllowed(["s3", "cp", "s3://b/k", "home/x"], outside, { + home, + privateHome: path.join(outside, "home"), + }) + ).toThrow(/outside the AWS client's working directory/); + }); + + test("local transfers get --no-follow-symlinks, and --follow-symlinks is refused", () => { + expect(withoutFollowingSymlinks(["s3", "--region", "x", "sync", ".", "s3://b"])).toEqual([ + "s3", + "--region", + "x", + "sync", + ".", + "s3://b", + "--no-follow-symlinks", + ]); + expect(withoutFollowingSymlinks(["s3", "ls"])).toEqual(["s3", "ls"]); + expect(() => + withoutFollowingSymlinks(["s3", "cp", ".", "s3://b", "--follow-symlinks"]) + ).toThrow("not allowed"); }); }); diff --git a/src/lib/aws/local-paths.ts b/src/lib/aws/local-paths.ts index b879416..05c70ba 100644 --- a/src/lib/aws/local-paths.ts +++ b/src/lib/aws/local-paths.ts @@ -53,27 +53,32 @@ const NAME_OPTION = /^--(?:[a-z0-9-]+-)?(?:name|names|path|paths|prefix|key|pattern|arn|id|ids|parameter|parameters|resource|resources|route|uri|url|expression|filter|query|location)$/; /** - * Throws when an argument names a local path outside the working directory. Every absolute or - * `~` argument counts, whatever comes before it: a boolean flag such as --recursive takes no - * value, so what follows it may well be a path. Only NAME_OPTION values are exempt. + * Throws when an argument names a local path outside the directory the CLI runs in. Every value + * counts, relative ones included, whatever comes before it: a boolean flag such as --recursive + * takes no value, so what follows it may well be a path. A relative value resolves against that + * directory (the workdir, or the private temp dir `deps.cwd` when there is none), and symlinks + * are followed, so neither `../x` nor a link inside it leads out. Only NAME_OPTION values are + * exempt, unless they name an existing file. `deps.privateHome` is never allowed: an alias file + * written there would run shell commands. */ export function assertLocalPathsAllowed( args: string[], workdir: string | null, - deps: { home?: string; cwd?: string } = {} + deps: { home?: string; cwd?: string; privateHome?: string } = {} ): void { - // Relative paths resolve in the child's working directory: the workdir, or a private temp dir - // where nothing of the user's lives. - const check = (value: string, relativeToo: boolean) => { + const base = workdir ?? deps.cwd; + const check = (value: string) => { // `~user/x` is another user's home to the CLI: always outside. const isAbsolute = path.isAbsolute(value) || value.startsWith("~"); - if (!isAbsolute && (!relativeToo || workdir === null)) return; if (isAbsolute && (workdir === null || /^~[^\\/]/.test(value))) throw outside(value, workdir); + if (!isAbsolute && base === undefined) return; + const root = isAbsolute ? (workdir as string) : (base as string); const target = isAbsolute ? path.resolve(expandHome(value, deps.home)) - : path.resolve(workdir as string, value); + : path.resolve(root, value); const real = realpathOfLongestExisting(target); - if (real !== workdir && !real.startsWith((workdir as string) + path.sep)) { + if (!isInside(real, realpath(root))) throw outside(value, workdir); + if (deps.privateHome && isInside(real, realpath(deps.privateHome))) { throw outside(value, workdir); } }; @@ -97,17 +102,38 @@ export function assertLocalPathsAllowed( // loads files with `key@=file://path`, and a list may hold several. const whole = value.match(/^fileb?:\/\/([\s\S]*)$/i); if (whole) { - check(whole[1], true); + check(whole[1]); continue; } - for (const m of value.matchAll(/fileb?:\/\/([^,\]}"'\s]*)/gi)) check(m[1], true); + for (const m of value.matchAll(/fileb?:\/\/([^,\]}"'\s]*)/gi)) check(m[1]); - if (option !== undefined && PATH_OPTION.test(option)) check(value, true); - else if (option === undefined || !NAME_OPTION.test(option)) check(value, false); - else if (value !== "/" && isFile(expandHome(value, deps.home))) check(value, false); + if (option !== undefined && !PATH_OPTION.test(option) && NAME_OPTION.test(option)) { + if (value !== "/" && isFile(expandHome(value, deps.home))) check(value); + } else if (value !== "" && !/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) { + // Everything but a URL (s3://, https://, arn: has no //) may be read as a path. + check(value); + } } } +/** + * s3 cp, mv and sync walk a local directory and follow its symlinks by default, so a link inside + * the workdir would upload, or delete, files outside it. They get --no-follow-symlinks. + */ +export function withoutFollowingSymlinks(args: string[]): string[] { + const words = args.map((arg) => arg.toLowerCase()); + const transfer = words[0] === "s3" && ["cp", "mv", "sync"].some((op) => words.includes(op)); + if (!transfer) return args; + if (words.some((w) => /^--follow-symlinks(?:=|$)/.test(w))) { + throw new Error( + "'--follow-symlinks' is not allowed: a link could lead outside the AWS client's working directory." + ); + } + return words.includes("--no-follow-symlinks") ? args : [...args, "--no-follow-symlinks"]; +} + +const isInside = (p: string, dir: string) => p === dir || p.startsWith(dir + path.sep); + function outside(value: string, workdir: string | null): Error { const where = workdir === null diff --git a/src/lib/aws/lstk-aws.test.ts b/src/lib/aws/lstk-aws.test.ts index 3ade575..4d1d8e1 100644 --- a/src/lib/aws/lstk-aws.test.ts +++ b/src/lib/aws/lstk-aws.test.ts @@ -89,7 +89,8 @@ describe("runLstkAws", () => { "s3://bucket/key", ]); expect(result.exitCode).toBe(0); - expect(out.args).toEqual(["aws", "s3", "cp", "-", "s3://bucket/key"]); + // A local transfer never follows a symlink out of the workdir. + expect(out.args).toEqual(["aws", "s3", "cp", "-", "s3://bucket/key", "--no-follow-symlinks"]); expect(out.input).toBe(""); }, 10_000); diff --git a/src/lib/aws/lstk-aws.ts b/src/lib/aws/lstk-aws.ts index d9a665c..db6f6ce 100644 --- a/src/lib/aws/lstk-aws.ts +++ b/src/lib/aws/lstk-aws.ts @@ -4,7 +4,7 @@ import { startEgressGuard } from "../azure/egress-guard"; import { LSTK_INSTALL_MESSAGE } from "../deployment/deployment-utils"; import { assertTargetsLocalStack } from "./aws-cli-sanitizer"; import { buildAwsChildEnv, privateDirs } from "./child-env"; -import { assertLocalPathsAllowed, awsWorkdir } from "./local-paths"; +import { assertLocalPathsAllowed, awsWorkdir, withoutFollowingSymlinks } from "./local-paths"; const AWS_CLI_INSTALL_MESSAGE = `❌ The AWS CLI is not installed or not available in PATH. @@ -57,7 +57,10 @@ export async function runLstkAws( const { workdir, error } = awsWorkdir(); if (error) throw new Error(error); const dirs = privateDirs(); - if (options.checkLocalPaths) assertLocalPathsAllowed(args, workdir); + if (options.checkLocalPaths) { + assertLocalPathsAllowed(args, workdir, { cwd: dirs.tmpDir, privateHome: dirs.homeDir }); + args = withoutFollowingSymlinks(args); + } const endpointUrl = localstackEndpointUrl(); const endpoint = new URL(endpointUrl); diff --git a/tests/mcp/tools.spec.mjs b/tests/mcp/tools.spec.mjs index eadfac5..eefc3f5 100644 --- a/tests/mcp/tools.spec.mjs +++ b/tests/mcp/tools.spec.mjs @@ -1,3 +1,5 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; import { expect, test } from "@gleanwork/mcp-server-tester/fixtures/mcp"; // One deterministic call sequence per tool against a running LocalStack: no model involved, so @@ -55,6 +57,47 @@ test.describe("tools against a running LocalStack", () => { expect(status).toMatch(/Services initialized: [1-9]\d*\/\d+/); }); + // The AWS client runs `lstk aws` with a private HOME, so lstk knows no containers of its own: + // it must reach the one this server starts (localstack-main, not lstk's localstack-aws) + // through the endpoint the server hands it. Stopping first makes this server start it, even + // when another tool started the running instance. + test("aws-client: reaches the LocalStack the server started, through lstk aws", async ({ + mcp, + }) => { + await call(mcp, "localstack-management", { action: "stop" }); + await call(mcp, "localstack-management", { action: "start" }); + const container = process.env.MAIN_CONTAINER_NAME || "localstack-main"; + const { stdout } = await promisify(execFile)("docker", [ + "inspect", + "--format", + "{{.State.Running}}", + container, + ]); + expect(stdout.trim(), `container ${container}`).toBe("true"); + + const aws = (command) => call(mcp, "localstack-aws-client", { command }); + await expect + .poll( + async () => + ( + await callRaw(mcp, "localstack-aws-client", { + command: "sts get-caller-identity --query Account --output text", + }) + ).text, + { + timeout: 60_000, + } + ) + .toContain("000000000000"); + const bucket = `${PREFIX}-started-${RUN}`; + await aws(`s3 mb s3://${bucket}`); + try { + expect(await aws("s3 ls")).toContain(bucket); + } finally { + await aws(`s3 rb s3://${bucket}`); + } + }); + // Disabling first means the enable has to change something, whatever an earlier run left. test("app-inspector: disables and enables tracing", async ({ mcp }) => { const tool = "localstack-app-inspector"; From 0fc287cece4cfe3487c838f229c052127a824666 Mon Sep 17 00:00:00 2001 From: Joel Scheuner Date: Thu, 19 Nov 2026 18:57:08 +0100 Subject: [PATCH 5/5] fix(aws-client): one value-shape path rule instead of option-name lists 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 --- src/lib/aws/aws-cli-sanitizer.test.ts | 6 + src/lib/aws/aws-cli-sanitizer.ts | 18 ++- src/lib/aws/local-paths.test.ts | 24 +++- src/lib/aws/local-paths.ts | 117 ++++++++---------- src/lib/aws/lstk-aws.ts | 8 ++ src/tools-tests/localstack-aws-client.test.ts | 3 +- 6 files changed, 107 insertions(+), 69 deletions(-) diff --git a/src/lib/aws/aws-cli-sanitizer.test.ts b/src/lib/aws/aws-cli-sanitizer.test.ts index f54109d..0101683 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -101,6 +101,12 @@ describe("sanitizeAwsCliCommand", () => { "ec2-instance-connect --no-paginate ssh --instance-id i-1", "ssm --region us-east-1 start-session --target i-1", "logs --color off tail x --follow", + "logs tail g --foll", + "lightsail push-container-image --service-name s --image i --label l", + "cli-dev wizard-dev --run-wizard x", + "deploy push --application-name a --s3-location s3://b/a.zip --source app", + "gamelift upload-build --name b --build-version 1 --build-root app", + "lambda-web deploy --code app", ])("refuses commands that act on this machine: %s", (command) => { expect(() => sanitizeAwsCliCommand(command)).toThrow(/not allowed|always target LocalStack/); }); diff --git a/src/lib/aws/aws-cli-sanitizer.ts b/src/lib/aws/aws-cli-sanitizer.ts index cfcea90..f4f5bad 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -89,6 +89,17 @@ export const DENIED: Array<{ match: string[]; reason: string }> = [ ]), ...deny("this needs a person to answer its prompts", ["wizard"]), ...deny("this manages agent skills on this machine", ["agent-toolkit"]), + ...deny("this is the CLI's developer tooling", ["cli-dev"]), + ...deny("this runs lightsailctl and Docker on this machine", [ + "lightsail", + "push-container-image", + ]), + ...deny( + "this zips a local directory and follows its symlinks out of the working directory", + ["deploy", "push"], + ["gamelift", "upload-build"], + ["lambda-web"] + ), ]; export function sanitizeAwsCliCommand(rawCommand: string): string { @@ -128,7 +139,12 @@ export function sanitizeAwsCliCommand(rawCommand: string): string { if (denied) { throw new Error(`'${denied.match.join(" ")}' is not allowed: ${denied.reason}.`); } - if (words[0] === "logs" && has("tail") && words.some((w) => /^--follow(?:=|$)/.test(w))) { + // Any unambiguous prefix of --follow is --follow to the CLI. + const follow = (w: string) => { + const name = w.match(/^--([a-z-]+)(?:=|$)/)?.[1]; + return name !== undefined && "follow".startsWith(name); + }; + if (words[0] === "logs" && has("tail") && words.some(follow)) { throw new Error( "'logs tail --follow' is not allowed: it streams until it is stopped. Use 'logs tail' with --since instead." ); diff --git a/src/lib/aws/local-paths.test.ts b/src/lib/aws/local-paths.test.ts index 6471a31..efeb58d 100644 --- a/src/lib/aws/local-paths.test.ts +++ b/src/lib/aws/local-paths.test.ts @@ -13,6 +13,11 @@ describe("awsWorkdir", () => { }); }); + test("refuses / and the home directory as LOCALSTACK_AWS_WORKDIR", () => { + expect(awsWorkdir({ LOCALSTACK_AWS_WORKDIR: "/" }).error).toContain("must not be /"); + expect(awsWorkdir({ LOCALSTACK_AWS_WORKDIR: os.homedir() }).error).toContain("must not be /"); + }); + test("is the server's directory, but none in Docker, in / or in the home directory", () => { const cwd = fs.realpathSync(os.tmpdir()); const home = fs.realpathSync(os.homedir()); @@ -60,6 +65,11 @@ describe("assertLocalPathsAllowed", () => { "lambda invoke --function-name f --payload {} out.json", "lambda create-function --function-name f --code ZipFile@=fileb://in.txt", "ecs run-task --task-definition web:3", + // Names whose first directory is not on this machine. + "ssm get-parameters --names /a/b /c/d", + "sns publish --topic-arn t --message /hello", + "cloudfront create-invalidation --distribution-id X --paths /index.html /about.html", + "s3api put-object --bucket b --key /etc-like/key --body in.txt", ])("allows: %s", (cmd) => { expect(() => allowed(cmd.replace("IN", workdir))).not.toThrow(); }); @@ -80,7 +90,6 @@ describe("assertLocalPathsAllowed", () => { "lambda create-function --function-name f --zip-file fileb://escape/x.zip", "eks update-kubeconfig --name c --kubeconfig ../x", "gamelift upload-build --name b --build-root escape", - "ssm get-parameters --names /a /b", "servicecatalog generate provisioning-artifact --file-path OUT/key.pem --bucket-name b", "ec2 get-password-data --instance-id i-1 --priv-launch-key OUT/key.pem", "cloudfront sign --url u --key-pair-id k --private-key OUT/key.pem --date-less-than 1", @@ -96,6 +105,10 @@ describe("assertLocalPathsAllowed", () => { "s3 cp escape/secret s3://b/k", "s3 cp s3://b/k --quiet ../outside-new", "s3 cp --region us-east-1 escape s3://b/k", + // An abbreviated --public-key-outfile, writing a new file in an existing directory. + "iot create-keys-and-certificate --public-key OUT/new.fish", + "iot create-keys-and-certificate --public-key ~/new.fish", + "s3 sync / s3://b", ])("refuses: %s", (cmd) => { expect(() => allowed(cmd.replace(/OUT/g, outside))).toThrow( /outside the AWS client's working directory/ @@ -111,6 +124,15 @@ describe("assertLocalPathsAllowed", () => { ); }); + test.each(["$HOME/.aws/cli/alias", "${HOME}/x", "file://$TMPDIR/x"])( + "refuses a leading variable the CLI would expand: %s", + (value) => { + expect(() => allowed(`iam create-virtual-mfa-device --outfile ${value}`)).toThrow( + "expand the variable" + ); + } + ); + test("the private home stays off limits inside a broad workdir", () => { expect(() => assertLocalPathsAllowed(["s3", "cp", "s3://b/k", "home/x"], outside, { diff --git a/src/lib/aws/local-paths.ts b/src/lib/aws/local-paths.ts index 05c70ba..31877d6 100644 --- a/src/lib/aws/local-paths.ts +++ b/src/lib/aws/local-paths.ts @@ -25,7 +25,14 @@ export function awsWorkdir( error: `LOCALSTACK_AWS_WORKDIR (${dir}) is not an existing directory: set it to the directory that holds the files the AWS client may read and write.`, }; } - return { workdir: realpath(dir) }; + const real = realpath(dir); + if (real === path.parse(real).root || real === realpath(deps.home ?? os.homedir())) { + return { + workdir: null, + error: `LOCALSTACK_AWS_WORKDIR (${real}) must not be / or your home directory: it would expose ~/.aws and every other file to the AWS client.`, + }; + } + return { workdir: real }; } if (deps.inDocker ?? fs.existsSync("/.dockerenv")) return { workdir: null }; const cwd = realpath(deps.cwd ?? process.cwd()); @@ -34,32 +41,20 @@ export function awsWorkdir( return { workdir: cwd }; } -// Options whose value names a local file or directory, relative or absolute. Taken from the -// AWS CLI v2 source: API parameters only take a local file through file://, fileb://, a -// streaming blob (the second line, from the service models) or a streaming operation's -// positional outfile, so the rest are customizations (the last line). -const PATH_OPTION = new RegExp( - "^--(?:[a-z0-9-]+-)?(?:file|outfile)$|^--(?:" + - [ - "body|block-data|annotation-payload|asset-content|documents|input-stream|invoke-args|payload", - "kubeconfig|ca-bundle|file-path|priv-launch-key|private-key|save-as|local-export-path|build-root|source|code|task-definition|codedeploy-appspec|dir|src|dest", - ].join("|") + - ")$" -); -// Options whose value is a name that may start with `/` (IAM paths, SSM parameter and log group -// names, S3 keys and prefixes). Their values are not checked, unless one names an existing -// file: an option missing from PATH_OPTION would read it. -const NAME_OPTION = - /^--(?:[a-z0-9-]+-)?(?:name|names|path|paths|prefix|key|pattern|arn|id|ids|parameter|parameters|resource|resources|route|uri|url|expression|filter|query|location)$/; - /** - * Throws when an argument names a local path outside the directory the CLI runs in. Every value - * counts, relative ones included, whatever comes before it: a boolean flag such as --recursive - * takes no value, so what follows it may well be a path. A relative value resolves against that - * directory (the workdir, or the private temp dir `deps.cwd` when there is none), and symlinks - * are followed, so neither `../x` nor a link inside it leads out. Only NAME_OPTION values are - * exempt, unless they name an existing file. `deps.privateHome` is never allowed: an alias file - * written there would run shell commands. + * Throws when an argument may name a local path outside the directory the CLI runs in. One rule + * for every value, whatever option it belongs to: the CLI accepts any unambiguous prefix of an + * option name (`--public-key` for `--public-key-outfile`), so a name proves nothing. + * + * - A relative value resolves against that directory (the workdir, or the private temp dir + * `deps.cwd` when there is none), following symlinks, and must stay inside. + * - An absolute or `~` value must be inside the workdir, unless its first directory does not + * exist on this machine: then it is a name (/aws/lambda/f, /prod/db/password, /index.html) + * the CLI cannot read, and writing it would only create a new top-level directory. + * - A file:// or fileb:// path, anywhere in a value (shorthand loads files with `key@=file://`), + * is always a path: no name exception. + * - A leading `$VAR`: the CLI expands variables in paths, so `$HOME/x` would leave the check. + * - `deps.privateHome` is never allowed: an alias written there would run shell commands. */ export function assertLocalPathsAllowed( args: string[], @@ -67,52 +62,45 @@ export function assertLocalPathsAllowed( deps: { home?: string; cwd?: string; privateHome?: string } = {} ): void { const base = workdir ?? deps.cwd; - const check = (value: string) => { - // `~user/x` is another user's home to the CLI: always outside. + // `/` is a name (`iam … --path /`) except to the transfers, which would walk the whole disk. + const words = args.map((arg) => arg.toLowerCase()); + const transfer = words[0] === "s3" && ["cp", "mv", "sync"].some((op) => words.includes(op)); + const check = (value: string, mayBeName: boolean) => { + if (mayBeName && value === "/" && !transfer) return; + if (/^\$\{?[A-Za-z_]/.test(value)) { + throw new Error( + `The value '${value}' is not allowed: the AWS CLI would expand the variable in a path. Write the path out.` + ); + } const isAbsolute = path.isAbsolute(value) || value.startsWith("~"); - if (isAbsolute && (workdir === null || /^~[^\\/]/.test(value))) throw outside(value, workdir); if (!isAbsolute && base === undefined) return; - const root = isAbsolute ? (workdir as string) : (base as string); const target = isAbsolute ? path.resolve(expandHome(value, deps.home)) - : path.resolve(root, value); + : path.resolve(base as string, value); + // `~user/x` is another user's home to the CLI: never a name. + if (isAbsolute && mayBeName && !value.startsWith("~") && !topLevelExists(target)) return; + const root = isAbsolute ? workdir : (base as string); const real = realpathOfLongestExisting(target); - if (!isInside(real, realpath(root))) throw outside(value, workdir); + if (root === null || /^~[^\\/]/.test(value) || !isInside(real, realpath(root))) { + throw outside(value, workdir); + } if (deps.privateHome && isInside(real, realpath(deps.privateHome))) { throw outside(value, workdir); } }; - let previousOption: string | undefined; for (const arg of args) { - let option = previousOption; - let value = arg; - previousOption = undefined; - if (arg.startsWith("--")) { - const eq = arg.indexOf("="); - if (eq === -1) { - previousOption = arg.toLowerCase(); - continue; - } - option = arg.slice(0, eq).toLowerCase(); - value = arg.slice(eq + 1); - } - - // A whole value that is file://… names one path (commas and all). Inside a value, shorthand - // loads files with `key@=file://path`, and a list may hold several. + // `--option=value`: the value; a bare `--option` is checked as the value of nothing. + const value = arg.startsWith("--") ? arg.slice(arg.indexOf("=") + 1 || arg.length) : arg; + if (value === "") continue; const whole = value.match(/^fileb?:\/\/([\s\S]*)$/i); if (whole) { - check(whole[1]); + check(whole[1], false); continue; } - for (const m of value.matchAll(/fileb?:\/\/([^,\]}"'\s]*)/gi)) check(m[1]); - - if (option !== undefined && !PATH_OPTION.test(option) && NAME_OPTION.test(option)) { - if (value !== "/" && isFile(expandHome(value, deps.home))) check(value); - } else if (value !== "" && !/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) { - // Everything but a URL (s3://, https://, arn: has no //) may be read as a path. - check(value); - } + for (const m of value.matchAll(/fileb?:\/\/([^,\]}"'\s]*)/gi)) check(m[1], false); + // Everything but a URL (s3://, https://; an arn: has no //) may be read as a path. + if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) check(value, true); } } @@ -139,21 +127,18 @@ function outside(value: string, workdir: string | null): Error { workdir === null ? `The local path '${value}' is not allowed: the AWS client has no working directory here. Set LOCALSTACK_AWS_WORKDIR to the directory that holds your files, or use a relative path.` : `The local path '${value}' is outside the AWS client's working directory (${workdir}). Use a path inside it, or set LOCALSTACK_AWS_WORKDIR.`; - return new Error( - `${where} A list of names that start with '/' can be given as JSON instead, e.g. --names '["/a","/b"]'.` - ); + return new Error(where); } function expandHome(value: string, home = os.homedir()): string { return /^~(?:[\\/]|$)/.test(value) ? path.join(home, value.slice(1)) : value; } -function isFile(p: string): boolean { - try { - return (path.isAbsolute(p) || p.startsWith("~")) && fs.statSync(p).isFile(); - } catch { - return false; - } +/** Whether the first directory below the root of an absolute path exists. */ +function topLevelExists(p: string): boolean { + const { root } = path.parse(p); + const first = p.slice(root.length).split(/[\\/]/)[0]; + return first === "" || fs.existsSync(path.join(root, first)); } function isDirectory(p: string): boolean { diff --git a/src/lib/aws/lstk-aws.ts b/src/lib/aws/lstk-aws.ts index db6f6ce..1546d4e 100644 --- a/src/lib/aws/lstk-aws.ts +++ b/src/lib/aws/lstk-aws.ts @@ -34,6 +34,14 @@ export async function checkLstkAwsDependencies(): Promise { ]); if (lstk.error) return LSTK_INSTALL_MESSAGE; if (aws.error) return AWS_CLI_INSTALL_MESSAGE; + // 2.37.7 is the first release whose downloads honor --no-follow-symlinks. + const version = aws.stdout + .match(/aws-cli\/(\d+)\.(\d+)\.(\d+)/) + ?.slice(1) + .map(Number); + if (!version || version[0] !== 2 || version[1] < 37 || (version[1] === 37 && version[2] < 7)) { + return `❌ The AWS client needs AWS CLI v2.37.7 or newer, found: ${aws.stdout.trim() || "unknown"}.\n\n${AWS_CLI_INSTALL_MESSAGE.split("\n").slice(2).join("\n")}`; + } dependenciesFound = true; return null; } diff --git a/src/tools-tests/localstack-aws-client.test.ts b/src/tools-tests/localstack-aws-client.test.ts index 4376a15..770b842 100644 --- a/src/tools-tests/localstack-aws-client.test.ts +++ b/src/tools-tests/localstack-aws-client.test.ts @@ -49,7 +49,8 @@ const missing = (): CommandResult => ({ function fakeCli(awsResult: CommandResult, { awsInstalled = true } = {}) { mockedRun.mockImplementation(async (command, args) => { if (args[0] === "--version") { - return command === "aws" && !awsInstalled ? missing() : ok(`${command} 1.0.0`); + if (command === "aws") return awsInstalled ? ok("aws-cli/2.40.4 Python/3.14.8") : missing(); + return ok("lstk 1.4.4"); } return awsResult; });