aws-emulator-awslocal-traffic-leak

Answer

Root cause. awslocal is a thin shim that appends --endpoint-url=http://localhost:4566 to aws invocations. But botocore's endpoint resolution precedence is: AWS_ENDPOINT_URL_<SVC> env → AWS_ENDPOINT_URL env → shared-config endpoint_url → client/CLI value. The env vars therefore silently override the localhost flag, and AWS_PROFILE additionally injects real-cloud credentials plus any profile-level endpoint override. Result: "local" commands hit real AWS. The fix is a preflight wrapper installed as the venv awslocal, which strips both leak vectors with warnings before exec'ing the real entry point (renamed to awslocal-upstream by make install-test).

1. scripts/awslocal — the preflight wrapper (source of truth in repo):

#!/usr/bin/env python3
"""
awslocal preflight wrapper.
botocore resolves endpoint_url as: AWS_ENDPOINT_URL_<SVC> env, AWS_ENDPOINT_URL env,
shared-config endpoint_url, then client/CLI value. So ambient AWS_ENDPOINT_URL /
AWS_PROFILE silently override awslocal's localhost flag -> real-cloud traffic.
This wrapper unsets both (with warnings) before exec'ing awslocal-upstream.
"""
import os
import sys

HERE = os.path.dirname(os.path.realpath(__file__))
UPSTREAM = os.path.join(HERE, "awslocal-upstream")
LEAK_VARS = ("AWS_ENDPOINT_URL", "AWS_PROFILE")

def preflight() -> None:
    for var in LEAK_VARS:
        value = os.environ.get(var)
        if value is not None:
            del os.environ[var]
            print(f"awslocal: warning: unset {var} (was {value!r}) "
                  "to keep traffic on localhost:4566", file=sys.stderr)

def main() -> int:
    preflight()
    if not os.path.isfile(UPSTREAM):
        print(f"awslocal: error: upstream entry point not found at {UPSTREAM}; "
              "run `make install-test`", file=sys.stderr)
        return 2
    python = os.path.join(HERE, "python3")          # same venv interpreter
    if not os.path.exists(python):
        python = sys.executable                      # bare-PATH fallback
    os.execv(python, [python, UPSTREAM, *sys.argv[1:]])
    return 0  # unreachable

if __name__ == "__main__":
    sys.exit(main())

Key properties: upstream is resolved via realpath(__file__) (CWD/symlink-proof); interpreter is taken from the same venv with a sys.executable fallback so a stripped PATH still works; os.execv preserves argv/exit codes.

2. Makefile — install-test wires the wrapper in:

VENV := .venv
BIN := $(VENV)/bin

.PHONY: install-test
install-test: ## (re)build test venv with awslocal preflight wrapper
    $(BIN)/python -m pip install -U pip
    $(BIN)/python -m pip install -e ".[test]" awslocal
    # Rename the pip-installed entry point once (idempotent); the awslocal
    # module stays in site-packages, only the console script is renamed.
    @if [ ! -x $(BIN)/awslocal-upstream ] && [ -x $(BIN)/awslocal ]; then \
        mv $(BIN)/awslocal $(BIN)/awslocal-upstream; \
    fi
    cp scripts/awslocal $(BIN)/awslocal
    chmod +x $(BIN)/awslocal
    @echo "installed awslocal preflight wrapper -> $(BIN)/awslocal (upstream: awslocal-upstream)"

The rename is guarded so re-running make install-test never double-renames (awslocal-upstream-upstream can't appear).