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..b5da2aa 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -59,13 +59,16 @@ 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. + # 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 ac5c2d4..817b578 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 \ @@ -41,17 +53,22 @@ 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/* 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..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 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
- 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 | @@ -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. @@ -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` | @@ -267,14 +268,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..35ab907 --- /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: !Sub "${AWS::StackName}-queue" + +Outputs: + QueueUrl: + Value: !Ref Queue diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 0b2be46..f463db8 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,14 +106,19 @@ 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. ## 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. @@ -166,13 +170,15 @@ 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 | | --- | --- | --- | | 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..90ec2e9 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|\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..c5e1625 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. * @@ -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 5e5a664..0101683 100644 --- a/src/lib/aws/aws-cli-sanitizer.test.ts +++ b/src/lib/aws/aws-cli-sanitizer.test.ts @@ -57,6 +57,113 @@ 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([ + "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", + "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", + "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/); + }); + + 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.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"); + }); + + 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..f4f5bad 100644 --- a/src/lib/aws/aws-cli-sanitizer.ts +++ b/src/lib/aws/aws-cli-sanitizer.ts @@ -1,3 +1,107 @@ +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 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. + 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." + ); + } +} + +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 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"]), + ...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 { const command = rawCommand.trim(); if (!command) { @@ -8,15 +112,46 @@ 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("-")) { throw new Error("Command must start with an AWS service or built-in command."); } - splitAwsCliArgs(command); + 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 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}.`); + } + // 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." + ); + } + 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/child-env.ts b/src/lib/aws/child-env.ts new file mode 100644 index 0000000..76ef2a9 --- /dev/null +++ b/src/lib/aws/child-env.ts @@ -0,0 +1,89 @@ +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. 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. + */ + +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..efeb58d --- /dev/null +++ b/src/lib/aws/local-paths.test.ts @@ -0,0 +1,160 @@ +import fs from "fs"; +import os from "os"; +import path from "path"; +import { assertLocalPathsAllowed, awsWorkdir, withoutFollowingSymlinks } 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("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()); + 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.writeFileSync(path.join(outside, "key.pem"), "secret"); + 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, + cwd: path.join(outside, "tmp"), + privateHome: path.join(outside, "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", + "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(); + }); + + 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", + "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", + "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", + // 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/ + ); + }); + + 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.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, { + 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 new file mode 100644 index 0000000..31877d6 --- /dev/null +++ b/src/lib/aws/local-paths.ts @@ -0,0 +1,171 @@ +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.`, + }; + } + 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()); + const home = realpath(deps.home ?? os.homedir()); + if (cwd === path.parse(cwd).root || cwd === home) return { workdir: null }; + return { workdir: cwd }; +} + +/** + * 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[], + workdir: string | null, + deps: { home?: string; cwd?: string; privateHome?: string } = {} +): void { + const base = workdir ?? deps.cwd; + // `/` 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 && base === undefined) return; + const target = isAbsolute + ? path.resolve(expandHome(value, deps.home)) + : 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 (root === null || /^~[^\\/]/.test(value) || !isInside(real, realpath(root))) { + throw outside(value, workdir); + } + if (deps.privateHome && isInside(real, realpath(deps.privateHome))) { + throw outside(value, workdir); + } + }; + + for (const arg of args) { + // `--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], false); + continue; + } + 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); + } +} + +/** + * 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 + ? `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); +} + +function expandHome(value: string, home = os.homedir()): string { + return /^~(?:[\\/]|$)/.test(value) ? path.join(home, value.slice(1)) : value; +} + +/** 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 { + 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 new file mode 100644 index 0000000..4d1d8e1 --- /dev/null +++ b/src/lib/aws/lstk-aws.test.ts @@ -0,0 +1,139 @@ +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. 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", () => { + 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; + let workdir: string; + let localstack: http.Server; + let localstackPort: number; + const seen: string[] = []; + const saved = { ...process.env }; + + 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.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(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 }); + }); + + 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); + // 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); + + 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", + }); + for (const name of ["AWS_PROFILE", "AWS_ENDPOINT_URL_S3", "LSTK_ENDPOINT_URL"]) { + expect(out.env).not.toHaveProperty(name); + } + }, 10_000); + + 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 new file mode 100644 index 0000000..1546d4e --- /dev/null +++ b/src/lib/aws/lstk-aws.ts @@ -0,0 +1,119 @@ +import { runCommand, type CommandResult } from "../../core/command-runner"; +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, withoutFollowingSymlinks } from "./local-paths"; + +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/; + +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; + // 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; +} + +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. 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[], + options: { checkLocalPaths?: boolean } = {} +): Promise { + assertTargetsLocalStack(args); + const { workdir, error } = awsWorkdir(); + if (error) throw new Error(error); + const dirs = privateDirs(); + if (options.checkLocalPaths) { + assertLocalPathsAllowed(args, workdir, { cwd: dirs.tmpDir, privateHome: dirs.homeDir }); + args = withoutFollowingSymlinks(args); + } + + 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, + }, + }, + }); + 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: 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() || + result.error?.message || + `lstk aws exited with code ${result.exitCode}` + ); +} 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/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..770b842 --- /dev/null +++ b/src/tools-tests/localstack-aws-client.test.ts @@ -0,0 +1,225 @@ +// 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"; +import { resetLstkAwsDependencyCheck } from "../lib/aws/lstk-aws"; + +// 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") { + if (command === "aws") return awsInstalled ? ok("aws-cli/2.40.4 Python/3.14.8") : missing(); + return ok("lstk 1.4.4"); + } + 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(); + resetLstkAwsDependencyCheck(); + 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(); + resetLstkAwsDependencyCheck(); + 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("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 3f5ea24..3adcc84 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. 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", }, @@ -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 +209,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 +319,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 && result.blocked.length === 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..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 @@ -19,7 +21,8 @@ const PREFIX = "mcp-tools"; const BUCKET = `${PREFIX}-bucket`; const QUEUE = `${PREFIX}-queue`; // Unique per run and attempt, so a re-run never meets a pod an aborted attempt left behind. -const POD = `mcp-tools-test-${process.env.GITHUB_RUN_ID ?? Date.now()}-${process.env.GITHUB_RUN_ATTEMPT ?? 1}`; +const RUN = `${process.env.GITHUB_RUN_ID ?? Date.now()}-${process.env.GITHUB_RUN_ATTEMPT ?? 1}`; +const POD = `mcp-tools-test-${RUN}`; async function callRaw(mcp, name, args) { const result = await mcp.client.callTool({ name, arguments: args }, undefined, { @@ -54,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"; @@ -82,6 +126,51 @@ 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 }) => { + // 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", + 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(queue); + } finally { + await call(mcp, "localstack-deployer", { action: "delete-stack", stackName }); + } + 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 }) => { const state = await call(mcp, "localstack-state-management", { action: "inspect" }); expect(state).toContain("## LocalStack State Inspect");