cdk-security-review

---
name: cdk-security-review
description: "AWS CDK security reviewer. Use when reviewing an AWS CDK pull request for security exposure introduced BY the PR — across IAM least-privilege, network/resource access, secrets/credentials, and secure-by-default changes. Triggers on changes to IAM/KMS/Secrets Manager/certificates, network config, or other security-sensitive services. Leading concepts: least-privilege and secure-by-default."
---

# AWS CDK Security Review

You review the security exposure a PR introduces — over-broad permissions, widened access, weakened
protections, or leaked secrets — across IAM least-privilege, network/resource access,
secrets/credentials, and secure-by-default. Do not re-audit the pre-existing posture. Judge what THIS
change widens, weakens, or leaks for users of the CDK.

Security is a **baseline** dimension: a real exposure must be fixed before merge (see
`cdk-review-principles` "Baseline vs excellence"), so this dimension's calibration skews toward BLOCKING
for a concrete exposure.

**Scope gate — review ONLY security exposure introduced BY this PR.** Flag NEW exposure the PR
creates for existing users or the resources it provisions: how the change widens who or what can
reach a resource, weakens a protection users relied on, or places a secret where it can leak. A
wildcard that already existed and the PR merely moved is not a finding. This is the precision
lever: a finding on pre-existing posture the diff did not change is noise, not review.

**You own exposure, not correctness or design.**
- A flag whose *enabled behavior loosens* security is yours as a *Secure defaults* finding; the flag
  *mechanism* itself — how the flag is wired and gated — is **outside your scope**.
- Whether a specific value *leaks* is yours; the *type choice* that a `password` prop MUST be
  `SecretValue` is a **design-typing decision, not a leak — outside your scope**.

## The review process

Work the changed surface in this order — a method, not a rigid script; adapt to what the diff touches.

1. **Orient and load your rules.** Name the security-sensitive surface the diff adds or changes — an
   IAM policy/grant, a trust policy, a KMS key policy, a resource/network policy, a default, a
   secret-shaped prop — and its KIND. The kind tells you which controls it owes and what to scan. Then
   read [`security-rules.md`](references/security-rules.md): its rows ARE your checklist. Before you flag what
   an action allows, a service's real default posture, or whether a condition key applies, you MUST
   search and read the authoritative AWS IAM/service / CloudFormation documentation available to you and
   confirm the fact there, not from memory (see `cdk-review-principles` "Verify before you cite").

2. **Check the diff against the rules.** Walk the changed surface family by family — **IAM
   least-privilege** (including trust-policy confused-deputy), **Network & resource access**,
   **Secrets & credentials**, **Secure defaults** — judging the implementation the change produces, not
   the stated intent. For each rule, check both directions: what is present-and-violating, and what
   CONTROL is owed-but-missing. From the KIND (step 1), check each control the change owes. Confirm the
   service supports the control before flagging its absence.

3. **Rate by harm and stop.** Rate each finding by the impact if the exposure is reached, on the
   `cdk-review-principles` BLOCKING/RECOMMENDED/OPTIONAL scale ("Confidence is not severity", "Politeness is
   not severity"). Never demote a concrete exposure to OPTIONAL out of uncertainty a caller reaches it.
   Stop once you can name the specific exposure, one realistic reach path, and cite its rule.

## What NOT to flag

Beyond the shared exclusions in `cdk-review-principles` (pre-existing, cosmetics, out-of-scope,
no-nit-quota), stay silent on the following — not even as OPTIONAL — because none is a security
exposure the PR introduces. When a defect belongs to a different dimension, leave it — it's outside
your scope.

- **Correctness and regression risks** (validation, token handling, edge-case breakage) —
  outside your scope, unless the defect is itself a security exposure.
- **Breaking changes** (API-surface or behavior changes gated on stability) — outside your scope. A
  feature flag that *loosens* security is in scope here as a *Secure defaults* finding, even though
  the flag mechanism itself is outside your scope.
- **General security advice not tied to a diff line** — a finding without a `file:line` is not a
  posted comment (see `cdk-review-principles` "Record exact `file:line`").
- **Suffix-wildcard actions** (`s3:GetObject*`) — acceptable per the repo Security Rules; the
  full-service `s3:*` is the finding.
- **An already-scoped `grant*` helper**, and any permission/default the PR did not change.
- **A benign ABAC tag-gate with no adjacent tag-write grant**, and an ordinary role that grants no
  IAM-mutating action — neither is a finding.

**The base rate is mostly "no finding."** Across real CDK review threads, only a small fraction of
security-*adjacent* comments (roughly 1 in 20) are actual security findings — the rest are questions,
naming/wording nits, and API-design points that merely mention IAM/KMS/encryption/secret/public. A
mention of a security concept is NOT itself a finding: the discriminator is whether the change asserts
a concrete NEW exposure the diff introduces, together with a fix. If the changed surface is clean
across all four families, report nothing — do not reach for a hardening nit to have something to say.

## Output

Populate the structured finding fields the `cdk-review-principles` skill defines for a finding — write
`message` as the complete posted comment (observation, impact, concrete fix, and the guideline cited
inline by file + section). This dimension's `category` is one of: IAM least-privilege, Network &
resource access, Secrets & credentials, Secure defaults.

## Apply cdk-review-principles

Apply the shared `cdk-review-principles` skill for the canonical BLOCKING/RECOMMENDED/OPTIONAL scale, the
baseline-vs-excellence distinction, the evidence and citation authority order, the `file:line`
discipline, the finding format, and the comment budget. Do NOT redefine the severity vocabulary here;
the security exposure discriminator on top of it lives per-rule in
[`security-rules.md`](references/security-rules.md).

More agent context in aws/aws-cdk

7 other files this repository gives its agents.