Docs: https://timpugh.github.io/lambda-powertools-reference/

This project contains source code and supporting files for a serverless application that you can deploy with the AWS CDK. It includes the following files and folders.

• app.py - CDK entry point; instantiates the WAF, backend, and frontend stacks and calls app.synth()
• lambda/ - Code for the application's Lambda function
• hello_world/hello_world_stack.py - The backend CDK stack (Lambda, API Gateway, DynamoDB, SSM, AppConfig)
• hello_world/hello_world_waf_stack.py - The WAF stack (CloudFront-scoped WebACL, always in us-east-1)
• hello_world/hello_world_frontend_stack.py - The frontend stack (S3 + CloudFront)
• hello_world/nag_utils.py - Shared cdk-nag suppression list for CDK-managed singleton Lambdas
• frontend/ - Static assets (index.html) deployed to the frontend S3 bucket
• events/event.json - A sample API Gateway proxy event for local SAM invocation
• tests/ - Unit and integration tests
• tests/conftest.py - Shared test fixtures (API Gateway event, Lambda context, mocks)
• docs/ - Sphinx documentation source files
• pyproject.toml - Consolidated tool configuration (ruff, mypy, pylint, pytest, coverage)
• .pre-commit-config.yaml - Pre-commit hook definitions (runs on every git commit)
• .bandit - Bandit security scanner configuration (excluded directories)
• .vscode/ - VS Code workspace settings and recommended extensions (ruff, mypy, pylint, pytest)
• .github/workflows/ - GitHub Actions workflows (ci.yml, docs.yml, dependency-audit.yml, dependabot-auto-merge.yml)
• .github/dependabot.yml - Dependabot configuration (weekly checks for GitHub Actions and all three Python requirements tiers)
• Makefile - Common development commands (make help to list all targets)
• LICENSE - Apache 2.0 license
• TODO.md - Outstanding work and deferred items

The application uses several AWS resources, including Lambda functions, an API Gateway API, a DynamoDB table, SSM parameters, AppConfig, an S3-backed CloudFront distribution, and a WAF WebACL. These resources are split across three stack files in hello_world/ (hello_world_stack.py for the backend, hello_world_waf_stack.py for WAF, and hello_world_frontend_stack.py for S3/CloudFront). The Lambda function uses AWS Lambda Powertools extensively — see the Lambda Powertools features section below for details. Note that Powertools Tracer currently depends on the aws-xray-sdk, which is approaching deprecation. There is an open RFC to replace it with OpenTelemetry as the tracing provider. You can update the stack to add AWS resources through the same deployment process that updates your application code.

The Lambda function in lambda/app.py uses the following Powertools utilities:

Structured JSON logging with @logger.inject_lambda_context. Automatically includes Lambda context fields (function name, request ID, cold start) in every log entry. Configured via POWERTOOLS_SERVICE_NAME and POWERTOOLS_LOG_LEVEL environment variables.

X-Ray tracing with @tracer.capture_lambda_handler on the entry point and @tracer.capture_method on route handlers. Creates subsegments for each traced method.

CloudWatch Embedded Metric Format (EMF) via @metrics.log_metrics(capture_cold_start_metric=True). The /hello route emits a HelloRequests count metric. Metrics are published under the HelloWorld namespace (set via POWERTOOLS_METRICS_NAMESPACE).

APIGatewayRestResolver provides Flask-like routing with @app.get("/hello"). It parses the API Gateway event and routes to the correct handler based on HTTP method and path.

The @idempotent decorator uses a DynamoDB table to prevent duplicate processing of the same request. It keys on requestContext.requestId and records expire after 1 hour. The CDK stack provisions the DynamoDB table with PAY_PER_REQUEST billing and a TTL attribute.

get_parameter() fetches the greeting message from SSM Parameter Store. The parameter path is set via the GREETING_PARAM_NAME environment variable. Values are cached automatically by Powertools to reduce API calls.

FeatureFlags reads from AWS AppConfig to toggle behavior at runtime. The enhanced_greeting flag controls whether the response includes extra text. The CDK stack provisions the AppConfig application, environment, configuration profile, and an initial hosted configuration version.

validate(event=response, schema=RESPONSE_SCHEMA) checks the route handler's return value against a JSON Schema before the resolver wraps it into the API Gateway proxy response. This catches malformed responses at the source rather than after serialization.

APIGatewayProxyEvent provides typed access to the incoming API Gateway event. Instead of raw dict access like event["requestContext"]["identity"]["sourceIp"], you get event.request_context.identity.source_ip with IDE autocomplete and type safety. Powertools includes data classes for many event sources:

• APIGatewayProxyEvent / APIGatewayProxyEventV2 — REST and HTTP API events
• S3Event — S3 bucket notifications
• SQSEvent — SQS messages
• DynamoDBStreamEvent — DynamoDB stream records
• EventBridgeEvent — EventBridge events
• SNSEvent, KinesisStreamEvent, CloudWatchLogsEvent, and more

These are available from aws_lambda_powertools.utilities.data_classes and require no extra dependencies.

Resources are split across three stacks. All resources in all stacks have RemovalPolicy.DESTROY so cdk destroy leaves nothing behind.

HelloWorldWaf-{region} (always in us-east-1):

HelloWorld-{region} (backend, target region):

HelloWorldFrontend-{region} (frontend, target region):

Just want to explore the code and run tests without deploying anything to AWS?

git clone https://github.com/timpugh/lambda-powertools-reference.git
cd lambda-powertools-reference
python3 -m venv .venv && source .venv/bin/activate
make install
make test

No AWS credentials or deployed stack required — unit tests mock all external dependencies.

If you open the project in VS Code, the .vscode/ directory pre-configures ruff (format on save), mypy, pylint, and pytest against pyproject.toml. The first time you open it, VS Code will prompt you to install the recommended extensions listed in .vscode/extensions.json.

Common commands are available via make. Run make help to see all targets:

make install        # set up venv with all dependencies and pre-commit hooks
make test           # run unit tests with coverage
make test-integration  # run integration tests (requires deployed stack)
make lint           # run all pre-commit hooks (ruff, mypy, pylint, bandit, xenon, pip-audit)
make format         # format code with ruff
make typecheck      # run mypy type checking
make security       # run bandit + pip-audit
make docs           # build Sphinx HTML docs
make docs-open      # build and open docs in browser
make compile        # regenerate all lock files from .in sources
make upgrade        # upgrade all dependencies (respects COOLDOWN_DAYS, default 7)
make clean          # remove build artifacts, caches, and coverage files

To use the CDK, you need the following tools.

• Node.js - Required to install the CDK CLI (npm install -g aws-cdk)
• AWS CDK CLI - Install the CDK CLI
• AWS SAM CLI - Install the SAM CLI - Required for local invocation and log tailing
• Python 3 installed
• Finch - Container runtime used for bundling Lambda dependencies and local invocation

This project uses Finch as the container runtime for bundling Lambda dependencies during synthesis. Set the CDK_DOCKER environment variable before running CDK commands (see the CDK GitHub issue where this was added):

export CDK_DOCKER=finch

To set up and deploy your application for the first time, run the following in your shell:

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install pip-tools first (needed for pip-sync)
pip install pip-tools

# Install dev dependencies (CDK, linting, type checking) via pip-sync
pip-sync requirements.txt

# Add test and Lambda dependencies on top (additive — does not remove dev deps)
pip install -r tests/requirements.txt -r lambda/requirements.txt

# Shortcut for the three steps above (after activating the venv):
# make install

# Make sure Finch is running
finch vm start

# Set Finch as the container runtime for CDK
export CDK_DOCKER=finch

# Bootstrap CDK in us-east-1 (always required — WAF stack always deploys here)
cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1

# Deploy all stacks to us-east-1 (default)
cdk deploy --all

The cdk synth and cdk deploy commands use Finch to build a container that installs the Lambda dependencies from lambda/requirements.txt into the deployment package. The first run will be slower as it pulls the SAM build image.

After deployment, CloudFormation outputs useful values directly in the terminal. Each stack exposes the following:

HelloWorldWaf-{region}:

• WebAclArn — WAF WebACL ARN (also used internally by the frontend stack)
• WebAclId — WAF WebACL logical ID
• WafLogGroupName — CloudWatch log group name for WAF access logs

HelloWorld-{region}:

• HelloWorldApiOutput — API Gateway endpoint URL (https://.../Prod/hello)
• HelloWorldFunctionOutput — Lambda function ARN
• HelloWorldFunctionIamRoleOutput — Lambda IAM role ARN
• IdempotencyTableName — DynamoDB table name
• GreetingParameterName — SSM parameter path
• AppConfigAppName — AppConfig application name
• CloudWatchDashboardUrl — Direct link to the CloudWatch monitoring dashboard

HelloWorldFrontend-{region}:

• CloudFrontDomainName — https:// URL to open in a browser
• CloudFrontDistributionId — Distribution ID for manual cache invalidations
• FrontendBucketName — S3 bucket name for direct asset inspection

Each target region must be bootstrapped before its first deploy. Bootstrap is a one-time step per region per account.

# Bootstrap the target region (in addition to us-east-1 which is always needed)
cdk bootstrap aws://YOUR_ACCOUNT_ID/ap-southeast-1

# Deploy all stacks — WAF stays in us-east-1, backend and frontend go to ap-southeast-1
cdk deploy --all -c region=ap-southeast-1

# Destroy the default us-east-1 deployment
cdk destroy --all

# Destroy a specific regional deployment (does not affect other regions)
cdk destroy --all -c region=ap-southeast-1

• cdk ls list all stacks in the app
• cdk synth emit the synthesized CloudFormation template
• cdk deploy --all deploy all stacks to us-east-1 (default)
• cdk deploy --all -c region=X deploy all stacks to region X
• cdk diff compare deployed stack with current state
• cdk destroy --all destroy all stacks in the default region

Synthesize your application to verify the CloudFormation template (requires Finch running):

export CDK_DOCKER=finch
cdk synth

You can invoke the Lambda function locally using the SAM CLI with the synthesized template:

sam local invoke HelloWorldFunction -t cdk.out/HelloWorld.template.json --event events/event.json

events/event.json is a sample API Gateway REST proxy event that simulates a GET /hello request. It includes realistic headers, a requestContext with a unique requestId (used by idempotency), and placeholder CloudFront fields. Use it as a starting point for local invocation — edit the httpMethod, path, or body fields to test different scenarios.

You can also emulate the API locally:

sam local start-api -t cdk.out/HelloWorld.template.json
curl http://localhost:3000/hello

Note: Local invocation requires Finch to be running:

finch vm start

You can use the SAM CLI to fetch logs from your deployed Lambda function:

sam logs -n HelloWorldFunction --stack-name "HelloWorld" --tail

This works for any AWS Lambda function, not just ones deployed with SAM. See the SAM CLI logging documentation for more on filtering and searching logs.

To add AWS resources, define new constructs in the appropriate stack file under hello_world/: backend resources (Lambda, API Gateway, DynamoDB, SSM, AppConfig) belong in hello_world_stack.py, frontend resources (S3, CloudFront) belong in hello_world_frontend_stack.py, and WAF rules belong in hello_world_waf_stack.py. The CDK provides high-level constructs for most AWS services. Browse available constructs in the AWS CDK API Reference. For resources without a dedicated CDK construct, you can use CloudFormation resource types directly via CfnResource.

Tests are defined in the tests folder in this project. Make sure dependencies are installed first (see Deploy the application).

Unit tests mock all external AWS dependencies so they run locally without credentials or a deployed stack. The key patterns used:

Shared fixtures via conftest.py — Reusable fixtures live in tests/conftest.py, including the API Gateway event, Lambda context mock, and the Lambda app module reference. The autouse mock that patches SSM Parameters and Feature Flags lives in tests/unit/conftest.py so it only applies to unit tests. Test files stay clean and focused on assertions.

Environment variables — All test env vars are centralized in pyproject.toml via pytest-env. This includes Powertools config, mock resource names, and the idempotency disable flag. No os.environ calls needed in test files.

Idempotency disabled via env var — POWERTOOLS_IDEMPOTENCY_DISABLED=true is set in pyproject.toml to tell Powertools to skip DynamoDB calls during tests. This is the recommended approach from Powertools docs. In production, this env var is not set, so idempotency is fully active.

Mocking external calls with pytest-mock — SSM Parameters and Feature Flags are mocked in tests/unit/conftest.py using mocker.patch.object():

mocker.patch.object(lambda_app, "get_parameter", return_value="hello world")
mocker.patch.object(lambda_app.feature_flags, "evaluate", return_value=False)

Lambda context via pytest-mock — A MagicMock provides the Lambda context object with realistic attributes (function name, ARN, request ID).

Import path isolation — The lambda/ directory is added to sys.path in tests/conftest.py before the root directory to ensure import app resolves to the Lambda handler (lambda/app.py) and not the CDK entry point (app.py).

python -m pytest tests/unit -v
# Shortcut: make test

Two suites of integration tests verify the live deployment:

API Gateway (tests/integration/test_api_gateway.py) — calls the live API Gateway endpoint and verifies the response body, content type headers, and response time (under 10 seconds, to account for Lambda cold starts with SSM and AppConfig initialization). The backend stack name is read from AWS_BACKEND_STACK_NAME in pyproject.toml (defaults to HelloWorld-us-east-1). Override for a different region:

AWS_BACKEND_STACK_NAME=HelloWorld-ap-southeast-1 pytest tests/integration/

CloudFront / S3 (tests/integration/test_frontend.py) — fetches the CloudFront distribution URL from the frontend stack outputs and verifies that the index page is served, config.json contains the injected API URL, HTTPS is enforced, security headers are present, and unknown paths fall back to index.html (SPA routing). The frontend stack name is read from AWS_FRONTEND_STACK_NAME in pyproject.toml (defaults to HelloWorldFrontend-us-east-1). Override for a different region:

AWS_FRONTEND_STACK_NAME=HelloWorldFrontend-ap-southeast-1 pytest tests/integration/

If either stack is not deployed, its tests skip automatically rather than failing — so the default pytest run stays green without a live deployment. Other test environment variables are configured in pyproject.toml via pytest-env (see the env key under [tool.pytest.ini_options]).

All test environment variables are centralized in pyproject.toml rather than scattered across test files. Note that POWERTOOLS_IDEMPOTENCY_DISABLED=true is only active during test runs — in production, this env var is not set, so idempotency is fully active against the DynamoDB table.

python -m pytest tests/integration -v
# Shortcut: make test-integration

Every test has a 30-second timeout enforced via timeout = 30 in pyproject.toml. Tests that exceed this are terminated and marked as failed. To override for a specific test, use the @pytest.mark.timeout(60) decorator.

pytest-randomly shuffles test execution order on every run to catch order-dependent bugs. It activates automatically when installed — no additional configuration needed. The seed is printed at the top of the output. To reproduce a specific order:

python -m pytest tests/ -p randomly -p no:randomly  # disable
python -m pytest tests/ --randomly-seed=12345        # replay a specific seed

Coverage runs automatically on every test run. Key flags set in pyproject.toml:

To open the HTML report after a test run:

open htmlcov/index.html

Tests run in parallel automatically via -n auto in addopts (pyproject.toml). pytest-xdist distributes tests across CPU cores. To disable it for debugging:

python -m pytest tests/ -n0

An HTML test report (report.html) is generated automatically on every test run via --html=report.html --self-contained-html in addopts (pyproject.toml). Open it in a browser to view detailed results.

This project uses several tools for code quality. Most are configured in pyproject.toml; bandit uses a separate .bandit file.

# Lint with ruff
ruff check .

# Format with ruff
ruff format .
# Shortcut for lint + format: make lint (runs all hooks) or make format (format only)

# Type check with mypy
mypy lambda/ hello_world/
# Shortcut: make typecheck

# Design and complexity checks with pylint
pylint lambda/ hello_world/

# Security scan with bandit
bandit -r lambda/ hello_world/

# Dependency vulnerability audit
pip-audit
# Shortcut for bandit + pip-audit: make security

# Code complexity with radon/xenon
radon cc lambda/ -a
xenon lambda/ -b B -m A -a A

# Run all of the above at once via pre-commit:
pre-commit run --all-files
# Shortcut: make lint

Bandit is a security-focused static analyzer that scans Python source code for common vulnerabilities. Its configuration lives in .bandit rather than pyproject.toml because the pre-commit bandit hook reads YAML config files by convention.

The .bandit file specifies which directories to exclude from scanning:

Everything outside these directories — lambda/ and hello_world/ — is scanned. That is the code you own and ship.

All tool configuration is consolidated in pyproject.toml. Here is a summary of the key settings in each section:

Ruff is configured with a broad set of rule groups. Each group targets a specific class of issue:

Structural complexity thresholds. Pylint fails if any function or class exceeds these limits. Complexity is also enforced by the xenon pre-commit hook (which uses radon under the hood).

Key flags in addopts:

log_cli = true and log_cli_level = "WARNING" stream log output in real time during the test run, showing only WARNING and above to reduce noise.

Security is enforced at three layers, each covering a different surface area:

These tools are complementary — no single one covers all three surfaces. Bandit catches code-level issues, pip-audit catches supply chain issues, and cdk-nag catches infrastructure misconfigurations.

Deprecated APIs are easy to ignore because they keep working — until the next major release removes them. There is no single command that catches every kind of deprecation, so this project uses a combination of approaches. Each one targets a different layer:

The first two are CDK-specific, the next two are Python-specific, and the last one is a general health check across all dependencies. None of them are mutually exclusive.

cdk synth no longer passes --no-notices (it used to, to keep CI output clean), so notices and CDK API deprecation warnings now print on every synth in both local and CI runs.

This project follows Conventional Commits. Format:

type: short description

Pre-commit runs a chain of hooks automatically on every git commit. Hooks are defined in .pre-commit-config.yaml. Set it up once after cloning:

pre-commit install

To run all hooks manually without committing (useful before pushing or after changing config):

pre-commit run --all-files

Four workflows are configured:

All three CI jobs must pass before anything can merge to main (branch protection).

The CI installs dependencies with pip-sync to match the local dev workflow exactly:

• quality job: pip-sync requirements.txt
• test job: pip-sync tests/requirements.txt lambda/requirements.txt
• cdk-check job: pip-sync requirements.txt (CDK) + pip install pytest pytest-mock (test runner, added separately to avoid the attrs version conflict between CDK and Lambda dependencies) + CDK CLI via npm install -g aws-cdk

The cdk-check job runs cdk synth to catch unsuppressed cdk-nag findings, then runs tests/cdk/test_stacks.py which uses aws_cdk.assertions.Template to verify key security properties of each synthesized stack (KMS encryption, DynamoDB PITR, API Gateway caching, CloudFront TLS version, etc.). These tests live under tests/cdk/ rather than tests/unit/ so the unit-test autouse fixture (which mocks Powertools internals) does not apply — the cdk-check job intentionally does not install Powertools to avoid the attrs version conflict. Asset bundling (Docker) is skipped via the aws:cdk:bundling-stacks context key so the job runs without Docker build time.

Dependabot is configured in .github/dependabot.yml to check for updates every Monday across two ecosystems:

For GitHub Actions patch and minor updates, the dependabot-auto-merge workflow:

1. Confirms the PR is a GitHub Actions ecosystem update
2. Checks that dependabot/fetch-metadata reports the update type as version-update:semver-patch or version-update:semver-minor
3. Approves the PR
4. Enables auto-merge — GitHub merges it automatically once CI passes

Major updates (e.g. actions/upload-artifact@v4 → @v7) intentionally fall through to manual review because they can contain breaking input/output changes and warrant a human glance at the changelog.

If CI fails on a Dependabot PR (any ecosystem), it stays open for investigation rather than merging.

Repo setting required for auto-merge to work. GitHub repositories ship with GitHub Actions blocked from approving pull requests by default. Until this is changed, the dependabot-auto-merge workflow will fail with GraphQL: GitHub Actions is not permitted to approve pull requests and even GitHub Actions PRs must be merged manually. Enable it once under Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests". This only needs to be done a single time per repo. Leave the Workflow permissions radio set to Read repository contents and packages permissions (the safer default) — every workflow in this repo declares its own explicit permissions: block, so the elevated Read and write permissions default is not needed. See "Least-privilege workflow permissions" in the supply-chain hardening section below.

The three Python requirements tiers are chained together via pip-compile constraint files:

lambda/requirements.in  →  lambda/requirements.txt
                           ↓ (-c constraint)
tests/requirements.in   →  tests/requirements.txt
                           ↓ (-c constraint)
requirements.in         →  requirements.txt

When a package shared across tiers changes version, all downstream lock files must be recompiled in order (lambda → tests → dev). The make compile target does this in one step.

Dependabot handles each directory independently and does not automatically re-run the downstream compiles. If Dependabot bumps a package in lambda/requirements.in, it regenerates lambda/requirements.txt correctly — but tests/requirements.txt and requirements.txt may still reference stale pins from the old lambda file. In practice, this only matters when the bumped package appears in the transitive tree of the downstream tiers.

Grouped updates collapse the PR volume. Each pip ecosystem entry in dependabot.yml defines groups: that bundle related packages into a single PR — aws-*/boto*/botocore always update together, pytest and its plugins update together, all other patch bumps roll into one weekly "patches" PR. Within a group, Dependabot regenerates the entire lock file in one shot, so the cross-package version skew that would otherwise hit boto3+botocore+aws-lambda-powertools (when each is bumped in isolation) cannot happen inside a single tier. Major and minor bumps that are not patches still get individual PRs so each changelog can be reviewed on its own.

Case 1 — single package confined to one tier. When a Dependabot PR bumps a package that only appears in one directory (e.g. ruff in /, pytest in /tests), merging it directly is enough — nothing downstream depends on it. These PRs go green on CI and can be squash-merged as-is.

Case 2 — a package that cascades down the chain. When Dependabot bumps a package in lambda/requirements.in that is also transitively present in tests/ or /, its PR regenerates only its own lock file — the downstream lock files still reference the stale pin. The 30-second fix is to recompile the downstream tiers locally:

gh pr checkout <PR-number>
make compile
git add lambda/requirements.txt tests/requirements.txt requirements.txt
git commit -m "chore: recompile downstream lock files"
git push

Case 3 — cross-cutting packages that Dependabot splits across directories. Packages like boto3 and botocore live as top-level pins in both lambda/requirements.in and tests/requirements.in. Dependabot opens one PR per directory (e.g. boto3 in lambda/, botocore in tests/), but pip-sync tests/requirements.txt lambda/requirements.txt in the CI test job refuses to install mismatched versions — so neither PR can land in isolation and both fail CI. gh pr checkout on either one doesn't fix the other.

The fix is to land them atomically from a single local commit rather than through Dependabot PRs at all:

# Close the stuck Dependabot PRs (they cannot be rebased into a consistent state)
gh pr close <boto3-PR> --comment "Superseded by local recompile"
gh pr close <botocore-PR> --comment "Superseded by local recompile"

# Bump the pin in each .in file, then recompile each tier in order
# (editing lambda/requirements.in and tests/requirements.in to the new version)
pip-compile --generate-hashes --upgrade-package boto3 --upgrade-package botocore \
    lambda/requirements.in -o lambda/requirements.txt
pip-compile --generate-hashes --allow-unsafe --upgrade-package boto3 --upgrade-package botocore \
    tests/requirements.in -o tests/requirements.txt
pip-compile --generate-hashes --allow-unsafe --upgrade-package boto3 --upgrade-package botocore \
    requirements.in -o requirements.txt

git add lambda/requirements.in lambda/requirements.txt tests/requirements.in tests/requirements.txt requirements.txt
git commit -m "build(deps): bump boto3 and botocore across all three lockfiles"
git push

Useful Dependabot commands. When a PR becomes stale relative to main (shown as BEHIND in gh pr view), comment @dependabot rebase on the PR to trigger a fresh rebase and CI run. Other useful commands include @dependabot recreate (regenerates the PR from scratch) and @dependabot ignore this version (skip a specific release). The full command list is at https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.

We intentionally leave the downstream-recompile step manual rather than automating it with a pull_request_target workflow: the manual path is ~30 seconds a few times a month, and a pull_request_target workflow that pushes back to PR branches carries a non-trivial security surface that is not worth the convenience trade-off for a solo reference project. If this repo ever takes external contributions, the calculus changes and the workflow becomes worth building.

attrs is pinned and ignored. The attrs package has an unresolvable version conflict between CDK (25.4.0) and Lambda Powertools (26.1.0). Dependabot is configured to ignore attrs in all three directories so it does not open unresolvable upgrade PRs — see the "attrs version conflict" note in Design decisions.

This repo layers six defenses against the supply-chain attack patterns described in GitGuardian's Renovate & Dependabot: the new malware delivery system:

1. Release cooldown. Every ecosystem in dependabot.yml carries a cooldown: block that makes Dependabot wait a few days after a release before opening a PR. Fresh releases are the window in which malicious versions (tag hijacks, compromised maintainer accounts, typo-squats, the xz-utils/nx/tj-actions/changed-files class of incidents) typically get caught and yanked. The tiered schedule is 3 days for patches, 7 for minors, 14 for majors — larger jumps wait longer to let bugs surface.

2. SHA-pinned GitHub Actions. Every uses: reference in .github/workflows/ is pinned to a 40-character commit SHA with the version in a trailing comment:

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2

Tag references are mutable — a compromised maintainer account can rewrite v6 to point at malicious code, and every workflow that said @v6 instantly runs the malicious version on the next trigger. This is exactly what happened to tj-actions/changed-files in March 2025, where attackers rewrote the v35 and v38 tags to exfiltrate CI secrets from thousands of repos within an hour. SHA pins are immutable — a re-tagged release becomes a new commit, and our pin simply ignores it until a human updates it. Dependabot still opens update PRs for SHA-pinned actions; the diff replaces both the SHA and the version comment in one shot.

3. Hash-locked pip installs. All three lock files are generated with pip-compile --generate-hashes, so every dependency is pinned to a SHA256. Even if an attacker uploads a malicious version under an existing version number (e.g. after yanking the legitimate one), pip install refuses to install it because the hash does not match.

4. Restricted auto-merge. Auto-merge is scoped to patch and minor GitHub Actions updates only (see above). pip updates never auto-merge, regardless of the update type, because they ship to production Lambda. Majors in either ecosystem require human review.

5. Local pip cooldown on make upgrade. Dependabot's cooldown protects every dependency change that lands via a PR, but make upgrade runs locally on a developer laptop and bypasses Dependabot entirely. The Makefile mirrors the same defense by passing pip's --uploaded-prior-to flag to pip-compile --upgrade, filtering out any package version uploaded in the last COOLDOWN_DAYS days (default 7). Override at the command line if you need to pull a fresher version: make upgrade COOLDOWN_DAYS=1. The cooldown is intentionally only applied to upgrade, not compile. compile reproduces decisions already encoded in the .in files and the existing lockfile — it cannot introduce a brand-new version, so cooldown is unnecessary and would actively conflict with freshly-bumped pins. upgrade is the only target where new versions enter the project and is the only place a fresh malicious release can land. Disable entirely with COOLDOWN_DAYS=0.

6. Least-privilege workflow permissions. Every workflow under .github/workflows/ declares an explicit permissions: block scoped to exactly what it needs, and the repo-level default (Settings → Actions → General → Workflow permissions) is set to read rather than write. The combination means that if a malicious dependency runs inside a CI job, the GITHUB_TOKEN it sees has the minimum authority necessary — ci.yml, dependency-audit.yml, and docs.yml's build job all run with contents: read and nothing else. Only two places escalate beyond read: docs.yml's deploy job adds pages: write + id-token: write for GitHub Pages OIDC deployment, and dependabot-auto-merge.yml adds contents: write + pull-requests: write so it can approve and merge Dependabot PRs (and is gated on github.actor == 'dependabot[bot]' plus a patch/minor update-type check). Permissions are declared at the job level wherever a workflow has heterogeneous needs (docs.yml's build vs deploy) and at the workflow level otherwise. The repo-level read default acts as defense-in-depth: if any future workflow is added without an explicit permissions: block, it inherits read instead of write-everything. The repo separately keeps can_approve_pull_request_reviews enabled — that toggle is independent of the default and is required for the auto-merge workflow's gh pr review --approve call to succeed.

What's intentionally not implemented: honeytokens. The article also recommends honeytokens as a detection layer, which this repo deliberately skips. A honeytoken is a fake credential — typically an AWS access key or GitHub token that looks completely real but is registered with a canary service (Thinkst, GitGuardian, AWS canarytokens.org). Nothing legitimate ever authenticates with it, so any use is by definition either an attacker or a misconfigured script that shouldn't exist. When someone tries it, the canary service alerts the owner with the timestamp, source IP, and which specific token fired — that last detail reveals where the attacker read it from (CI logs, a specific repo clone, a leaked .env, etc.), which makes incident scoping much faster.

Honeytokens are specifically effective against the CI-exfiltration pattern this hardening section guards against: a malicious dependency running inside a CI runner typically sweeps environment variables and filesystem paths for anything that looks like a credential and pipes it to an attacker-controlled endpoint. If a honeytoken is reachable from the same runner (e.g. planted in .github/workflows/ as a fake DEPLOY_KEY secret, or embedded in a committed .env.example file), the exfiltration tooling scoops it up alongside the real credentials and the alert fires within seconds of the breach — weeks before an attacker would otherwise tip their hand by actually using the stolen credentials.

Everything else in this section is prevention; honeytokens are detection. They do not stop attacks, they tell you an attack happened. The reason this repo skips them is not value but operational overhead: honeytokens are easy to plant (canarytokens.org generates one in about 30 seconds) but the alert routing is the real cost. You need somewhere for the alert to land (email you actually read, a Slack channel you watch, a pager), and you need a runbook for what to do when it fires. For a solo reference project with no production data, no customer PII, and CI secrets that can be rotated in 30 seconds, that plumbing is not worth standing up. For any repo running real workloads — production AWS accounts, customer data, deploy keys to anything that ships to users — honeytokens are a high-signal, low-noise addition that pays for itself the first time one fires, and GitGuardian's free ggshield CLI ships a generator that integrates with their alert console.

What's intentionally not implemented: machine inventory. The article recommends maintaining an inventory of every machine that runs unattended pip install / npm install, because each one is an exfiltration surface if a malicious package lands. At org scale this matters — dozens of build boxes, dev laptops with auto-updaters, and shared CI fleets each multiply the blast radius. For this repo the inventory is two items: one developer laptop and GitHub-hosted runners (which are ephemeral and Microsoft's problem). Writing that down as a doc would add a file to keep in sync with zero defensive value at this scale, so it is deliberately omitted. If this pattern is extended to a team or org repo, the inventory should be revisited and probably codified.

What's intentionally not implemented: a post-compromise rotation runbook. The article also recommends a written checklist for "assume a malicious dep ran in CI — what do I rotate, in what order, how fast?" The value of writing it down ahead of time is that during an actual incident, you are panicked and will forget steps. This repo deliberately skips the runbook because it currently has nothing to rotate: the only secret in use is the auto-scoped per-run GITHUB_TOKEN, which expires when each job ends. There are no AWS deploy keys, no API tokens, no secrets.* entries with real credentials. A runbook today would read "revoke nothing, there's nothing to revoke." The moment a real secret is added to this repo (an AWS deploy role, a Sentry DSN, anything in secrets.*), this section should become a runbook with the rotation order, who to notify, and the commands to run.

Renovate is an alternative to Dependabot that handles multi-file Python setups more gracefully. Specifically:

• Renovate understands pip-compile constraint chains natively and recompiles downstream lock files in the correct order automatically — no manual make compile step, no bespoke workflow.
• Renovate supports richer grouping (e.g., "group all AWS packages into one PR") and auto-merge rules scoped by update type (patch/minor/major).
• Renovate runs as a GitHub App, so it is zero-infrastructure.

This project uses Dependabot rather than Renovate because Dependabot is the GitHub-native default, already integrated into the repo for GitHub Actions updates, and the manual make compile step is a minor cost at the current scale. If you extend this pattern to a production repo with more frequent Python churn — or if you want auto-merge for non-major pip updates — Renovate is the lower-friction choice and worth evaluating. The configuration lives in renovate.json at the repo root; the GitHub App handles the rest.

All three stacks use cdk-nag with three rule packs applied to every resource at synth time. Any finding that is not suppressed fails cdk synth — infrastructure misconfigurations are caught before deployment, not after.

Checks run automatically on every cdk synth and cdk deploy. There is no separate command needed.

cdk-nag ships additional packs that are not enabled in this project. They can be added by importing and applying them the same way as the packs above:

Full rule documentation: github.com/cdklabs/cdk-nag/blob/main/RULES.md

Not every rule is appropriate for a sample application. Where a rule has been intentionally suppressed, the suppression lives in the stack file in either NagSuppressions.add_stack_suppressions (stack-wide) or NagSuppressions.add_resource_suppressions/add_resource_suppressions_by_path (targeted to a specific resource). Each entry includes a reason field explaining why it was suppressed rather than fixed.

Stack-level suppressions are reserved for findings that are genuinely stack-wide (e.g., no custom domain, no VPC by design). Everything else is suppressed at the resource level to keep the blast radius of each suppression as small as possible. CDK-managed singleton Lambdas (BucketDeployment provider, LogRetention, S3AutoDeleteObjects, AwsCustomResource) share a common suppression list defined in hello_world/nag_utils.py (CDK_LAMBDA_SUPPRESSIONS) and are targeted by their stable CDK construct IDs using add_resource_suppressions_by_path. AwsSolutions-IAM5 suppressions on HelloWorldFunction use the applies_to parameter to scope them to specific wildcard actions and resources rather than suppressing all IAM5 findings on the role.

What is encrypted with CMK: All CloudWatch log groups (Lambda, API Gateway access, API Gateway execution, WAF, auto-delete Lambda), DynamoDB, and the S3 frontend bucket use AWS KMS customer-managed keys with annual key rotation enabled. The S3 access logging bucket uses SSE-S3 because the S3 log delivery service does not support KMS-encrypted target buckets. SSM parameters cannot use CMK (CloudFormation limitation — SecureString is not supported). AppConfig hosted configurations use AWS-managed keys (no CMK option in CDK).

Current suppressions across all stacks:

Rules that were previously suppressed and have since been implemented are removed from this list. If you add a suppression, include a clear reason and consider whether the finding represents a genuine gap worth addressing in production.

The frontend is split across two CDK stacks — HelloWorldWafStack and HelloWorldFrontendStack — intentionally decoupled from the backend. This allows the frontend to be deployed and destroyed independently of the API, and demonstrates the standard CDK multi-stack and cross-region reference pattern.

Browser → CloudFront → S3 (private bucket)
               ↓
        WAF WebACL (us-east-1, always)

The browser calls GET /hello directly from JavaScript against the API Gateway URL — CloudFront only serves static assets, it does not proxy API requests.

This project uses three stacks, not two. WAF lives in its own stack because CloudFront-scoped WAF WebACLs are an AWS hard requirement to exist in us-east-1 — even if every other resource is in a different region. By isolating WAF into HelloWorldWafStack, the backend and frontend can be deployed to any region without duplicating the WAF or violating the constraint.

Each regional deployment gets its own set of three independently named stacks:

Deploying to us-east-1 (default):

cdk deploy --all

Deploying to a different region:

cdk deploy --all -c region=ap-southeast-1

WAF stays in us-east-1 (always). The backend and frontend deploy to the target region. CDK wires the WAF ARN across regions automatically — no manual steps.

Destroying a specific regional deployment:

cdk destroy --all -c region=ap-southeast-1

This tears down only the Singapore stack set (HelloWorldWaf-ap-southeast-1, HelloWorld-ap-southeast-1, HelloWorldFrontend-ap-southeast-1). Any other regional deployments are unaffected.

WAF cost note — Each regional deployment provisions its own WAF WebACL at $5/month. This keeps deployments fully independent, which is the right default for a reference architecture. In a production setup with multiple long-lived environments, you could share a single HelloWorldWaf stack across all regions and pass its ARN to each frontend stack, eliminating the per-deployment cost. That optimization is intentionally deferred here in favour of deployment independence.

When the frontend stack is in a different region from the WAF stack, CDK cannot pass the WAF ARN as a direct CloudFormation output (outputs only work within a single region). Instead, CDK uses cross_region_references=True on the frontend stack to bridge the value automatically:

1. During cdk deploy, CDK writes the WAF ARN into an SSM Parameter in us-east-1
2. A CDK-managed custom resource in the frontend stack's region reads that SSM parameter at deploy time
3. The WAF ARN is resolved and attached to the CloudFront distribution

This is entirely transparent — you pass waf.web_acl_arn in app.py just like any other stack property. The SSM parameters are CloudFormation-managed and are cleaned up on cdk destroy.

The backend exposes api_url as a stack property. The frontend stack injects it into config.json at deploy time via BucketDeployment. The browser fetches /config.json at runtime so the API URL is never hardcoded in source.

The static assets themselves live in the frontend/ directory at the project root. Currently this is just a single index.html that fetches config.json and calls the API — replace it with a built SPA bundle (e.g. the dist/ output from a Vite or Next.js export build) and the existing BucketDeployment will pick it up automatically.

The bucket is fully private — no public access of any kind. CloudFront reaches it exclusively via Origin Access Control (OAC), the current AWS-recommended successor to OAI. The bucket is encrypted with SSE-KMS (customer-managed key with annual rotation), has SSL enforced, server access logging enabled to a dedicated log bucket, versioning disabled (git is the source of truth), and auto_delete_objects=True so cdk destroy empties and deletes it cleanly.

The access log bucket uses SSE-S3 rather than SSE-KMS — the S3 log delivery service does not support writing to KMS-encrypted target buckets.

The WebACL sits in front of CloudFront and inspects every request before it reaches S3. Four rules are active, evaluated in priority order:

All rules emit CloudWatch metrics and sampled requests, so WAF activity is visible in the console without additional configuration.

WAF access logs are written to a CloudWatch Logs log group named aws-waf-logs-{stack_name} (the aws-waf-logs- prefix is an AWS requirement). The log group is KMS-encrypted with a customer-managed key and has 1-week retention.

The WAF WebACL lives in HelloWorldWafStack which is always pinned to us-east-1. This is an AWS hard constraint for CloudFront-scoped WebACLs. The cross-region reference pattern described above handles wiring the ARN to CloudFront automatically regardless of where the frontend stack is deployed.

Every resource in HelloWorldWafStack and HelloWorldFrontendStack has RemovalPolicy.DESTROY, including all CloudWatch log groups. cdk destroy --all leaves nothing behind in any region.

Note: CDK creates an internal singleton Lambda to empty the S3 bucket before deletion (Custom::S3AutoDeleteObjects). Its log group is explicitly declared in the stack so CloudFormation owns it and deletes it on destroy — following the same principle as the API Gateway execution log group in the backend stack.

The stack includes a cdk-monitoring-constructs MonitoringFacade that creates a CloudWatch dashboard with Lambda, API Gateway, and DynamoDB metrics out of the box.

Project documentation is generated from docstrings and markdown files using Sphinx with MyST-Parser. Source files are in docs/. All five modules are documented: lambda/app.py (Lambda handler), hello_world/hello_world_stack.py (backend), hello_world/hello_world_waf_stack.py (WAF), hello_world/hello_world_frontend_stack.py (frontend), and hello_world/nag_utils.py (shared suppression utilities). Doc builds are best run in CI/CD pipelines or manually before publishing, rather than on every commit.

# Build HTML docs
PYTHONPATH=lambda:. sphinx-build -b html docs docs/_build
# Shortcut: make docs

# Open in browser
open docs/_build/index.html
# Shortcut for build + open: make docs-open

Dependencies are managed with pip-tools. Each dependency group has a .in file (direct dependencies you maintain) and a .txt file (fully resolved with transitive dependencies and hashes, generated by pip-compile).

• requirements.in / requirements.txt — CDK, linting, static analysis, and dev tooling (constrained by tests/requirements.txt)
• tests/requirements.in / tests/requirements.txt — pytest and test plugins (constrained by lambda/requirements.txt)
• lambda/requirements.in / lambda/requirements.txt — Lambda runtime dependencies (packaged with the function at deploy time)

Constraint files (-c) ensure shared packages like boto3 resolve to the same version across all environments, preventing drift.

To regenerate the lock files after editing a .in file, compile in order (lambda → tests → dev):

pip-compile --generate-hashes lambda/requirements.in -o lambda/requirements.txt
pip-compile --generate-hashes --allow-unsafe tests/requirements.in -o tests/requirements.txt
pip-compile --generate-hashes --allow-unsafe requirements.in -o requirements.txt
# Shortcut: make compile

To upgrade all dependencies:

# Default: blocks any version uploaded to PyPI in the last 7 days (cooldown defense)
make upgrade

# Override the cooldown window
make upgrade COOLDOWN_DAYS=14   # stricter — only versions older than 14 days
make upgrade COOLDOWN_DAYS=1    # near-immediate — only the last 24 hours filtered
make upgrade COOLDOWN_DAYS=0    # disable cooldown entirely

make upgrade passes pip's --uploaded-prior-to flag to pip-compile --upgrade so brand-new PyPI releases (the window in which malicious versions typically get caught and yanked) are not pulled into the lockfiles. See "Local pip cooldown on make upgrade" in the supply-chain hardening section for the full rationale.

To install and keep your venv in sync with dev dependencies:

pip-sync requirements.txt
pip install -r tests/requirements.txt -r lambda/requirements.txt

pip-sync is used for the dev context because it removes stale packages not in the lock file. Test deps are added with pip install -r instead — using pip-sync for both contexts would remove dev packages, corrupting the venv. CI uses separate jobs so each runs pip-sync against a single context cleanly.

cdk.out/ is not committed — this directory contains the synthesized CloudFormation template and bundled Lambda assets generated by cdk synth. It is gitignored because it is always reproducible from source and can be large. Run cdk synth locally to regenerate it before deploying or invoking locally with SAM.

attrs version conflict — requirements.txt (dev) pins attrs==25.4.0 for CDK compatibility, while lambda/requirements.txt pins attrs==26.1.0 for Powertools. These two versions cannot coexist in a single environment. This is why the CI is split into separate quality and test jobs, and why local test deps are installed with pip install -r (additive) rather than pip-sync (destructive).

SSM parameter path is derived from the stack name — the greeting parameter is stored at /{stack_name}/greeting in SSM (e.g. /HelloWorld-us-east-1/greeting), so each regional deployment gets its own parameter automatically. This is intentional for a reference project but would likely be parameterised differently in a production stack.

CORS is open (allow_origin="*") — the Lambda handler configures APIGatewayRestResolver with CORSConfig(allow_origin="*") for simplicity. In production, restrict this to the specific CloudFront domain (e.g., allow_origin="https://d1234.cloudfront.net") and set allow_credentials=True if the API requires cookies or Authorization headers. Leaving CORS open in production allows any origin to call the API from a browser.

Error handling — the handler demonstrates the recommended pattern for production Lambda error handling. Critical downstream failures (SSM) return a 500 via InternalServerError so the API always responds with a meaningful HTTP status rather than a Lambda runtime error. Non-critical failures (AppConfig feature flags) fall back to a safe default rather than failing the whole request. As you extend this project, apply the same pattern to any new downstream calls: decide whether the failure is critical (raise InternalServerError) or non-critical (log a warning, use a default), and add a corresponding unit test for each path.

Explicit resource creation prevents dangling resources — AWS services sometimes create supporting resources outside of CloudFormation. The most common example is CloudWatch log groups: Lambda creates one automatically on first invocation, and API Gateway creates an execution log group (API-Gateway-Execution-Logs_{api-id}/{stage}) whenever execution logging is enabled. Neither is managed by CloudFormation, so neither is deleted when you run cdk destroy — they silently persist and accrue storage costs indefinitely.

Every resource in this stack is declared explicitly in CDK with removal_policy=RemovalPolicy.DESTROY so that cdk destroy leaves nothing behind. When you add new AWS services, check whether they create their own supporting resources (log groups, S3 buckets, parameter store entries, etc.) and declare those explicitly too. The pattern is: if AWS creates it, CDK should own it.

Application Insights dashboard — Application Insights automatically creates a CloudWatch dashboard named after its resource group when auto_configuration_enabled=True. This dashboard is created outside of CloudFormation and cannot be pre-declared in CDK. To ensure it is removed on cdk destroy, the backend stack includes a Lambda-backed custom resource (AppInsightsDashboardCleanup) that calls DeleteDashboards at destroy time, targeting the dashboard by the resource group name.

Note: If you ever rename the Application Insights resource group (e.g., by changing the stack name), the dashboard associated with the old name will be left behind because the old custom resource no longer knows about it. Clean it up manually:

# List Application Insights dashboards
aws cloudwatch list-dashboards --query "DashboardEntries[?contains(DashboardName, 'ApplicationInsights')]"

# Delete the old one
aws cloudwatch delete-dashboard --dashboard-names "ApplicationInsights-<old-resource-group-name>"

To delete the application and all associated AWS resources, run:

cdk destroy

Every resource in the stack — including all three CloudWatch log groups — is configured with RemovalPolicy.DESTROY, so a single cdk destroy leaves no dangling resources and no ongoing AWS costs.

See the AWS CDK Developer Guide for an introduction to CDK concepts and the CDK CLI.