--- name: Well-Architected Guardrails slug: well-architected-guardrails category: DevOps description: Well-Architected Guardrails generates preventive and detective AWS controls from an assessment or codebase. Use it to enforce best practices in CI, at deploy time, and continuously so misconfigurations and drift are blocked or flagged. github: "https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/main/skills/wa-guardrails" language: Python stars: 256 forks: 42 install: "npx degit https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/main/skills/wa-guardrails ~/.claude/skills/wa-guardrails" installs_to: ~/.claude/skills/wa-guardrails source_path: skills/wa-guardrails/SKILL.md collection_size: 6 category_size: 828 collection_url: "https://dirskills.com/collections/aws-samples/sample-well-architected-skills-and-steering" added: 2026-09-02T05:20:40.161Z last_synced: 2026-09-02T05:20:40.161Z canonical_url: "https://dirskills.com/skills/well-architected-guardrails" --- # Well-Architected Guardrails Well-Architected Guardrails generates preventive and detective AWS controls from an assessment or codebase. Use it to enforce best practices in CI, at deploy time, and continuously so misconfigurations and drift are blocked or flagged. **Install:** ```bash npx degit https://github.com/aws-samples/sample-well-architected-skills-and-steering/tree/main/skills/wa-guardrails ~/.claude/skills/wa-guardrails ``` ## README # Well-Architected Guardrails This skill generates **preventive and detective controls** that keep a workload Well-Architected over time. Unlike the assessment skills (which find gaps) or remediation (which fixes a specific finding once), guardrails codify best practices so non-compliant changes are blocked or flagged automatically — in CI, at deploy time, and continuously in the account. **What you'll produce:** ready-to-commit control files (Config rules, SCPs, CI policy checks, alarms), each tied to the WA Question/Best Practice ID it enforces, with a note on whether the control is **preventive** (blocks the bad change) or **detective** (flags it after the fact). ## Step 1: Gather context Ask the user (skip any already provided or inferable from the codebase): > I can generate guardrails to keep your workload Well-Architected. Let me know: > - **Workload name** and code packages/directories (IaC, CI/CD configs) > - **IaC dialect**: CDK (which language), CloudFormation, Terraform, SAM, or mixed > - **Source of controls**: a prior `/aws-well-architected-framework-review` or assessment output, specific concerns, or "scan and propose" > - **Enforcement points available**: CI pipeline (which one), AWS Organizations/SCPs, AWS Config, account-level admin — so controls target what you can actually deploy > - **Pillars to prioritize** (optional; default: Security and Reliability) If you are in a codebase, proceed directly and infer the IaC dialect and CI system from the files present. ## Step 2: Discovery — what to enforce Determine the controls to generate from one of two inputs: **Path A — From an assessment (preferred):** parse the prior review for findings, their pillar, severity, evidence (file:line), and the Best Practice IDs cited. Each High/Critical finding becomes a candidate guardrail so the same gap cannot recur. **Path B — Standalone scan:** analyze the IaC and identify the control-worthy configurations actually in use — storage encryption, public access, IAM scope, multi-AZ, backups, logging, TLS, tagging. Map each to the WA Best Practice it relates to. Produce a **control candidate list**: for each, record the pillar, the WA Question/BP ID, the resource type it applies to, the current state (compliant / non-compliant / absent), and the **enforcement point** that fits (CI check, Config rule, SCP, alarm). ## Step 3: Select preventive vs. detective for each control For every candidate, choose the strongest control the user's enforcement points allow. Prefer **preventive** (stops the bad change before it ships) over **detective** (catches it afterward). Use this decision guidance: - Can the misconfiguration be caught in IaC before deploy? → **CI policy check** (CDK Aspect, `cfn-guard`/`cfn-lint`, Terraform OPA/Sentinel). Strongest and cheapest. - Must it be blocked org-wide regardless of who deploys? → **SCP or permission boundary**. - Is it only observable on the live resource (e.g. drift, runtime state)? → **AWS Config rule** (detective; add auto-remediation only if the user confirms). - Is it a continuous reliability/cost/performance signal? → **CloudWatch metric + alarm**. If a control cannot be enforced with the available points, say so explicitly rather than emitting a control that won't run. ## Step 4: Generate the controls Generate every selected control as ready-to-commit code in the workload's existing dialect and conventions. Each control MUST: - Cite the WA Question/BP ID it enforces (e.g. `SEC 8`, `REL 9`) - Be labeled 🛡️ Preventive or 🔍 Detective - Include a one-line statement of what it blocks/flags and why it matters Cover, as applicable to the workload: **Security (SEC)** — examples: `s3-bucket-server-side-encryption-enabled`, `s3-bucket-public-read-prohibited`, `iam-policy-no-statements-with-admin-access` (Config); SCP denying creation of unencrypted resources or disabling CloudTrail; a CDK Aspect failing synth on a security group open to `0.0.0.0/0` on non-web ports. **Reliability (REL)** — `rds-multi-az-support`, `dynamodb-pitr-enabled`, `db-instance-backup-enabled` (Config); a `cfn-guard` rule requiring `DeletionProtection` on stateful resources; an alarm on DLQ depth. **Operational Excellence (OPS)** — a CI check requiring tags (owner, cost-center, environment); a Config rule for required CloudWatch log retention; an SCP preventing manual changes outside IaC. **Cost (COST)** — a CI check flagging instance types or capacity modes outside an approved list; a budget/anomaly alarm. **Performance / Sustainability (PERF/SUS)** — a CI check preferring Graviton/managed services where applicable. Provide each control's snippet in a fenced code block with the target filename, so the user can commit it directly. Match the workload's dialect — examples of the three most common forms: **Detective — AWS Config managed rule (SEC 8, encryption at rest), CloudFormation:** ```yaml # guardrails/config-rules.yaml Resources: S3EncryptionEnabled: # 🔍 Detective — flags any S3 bucket without SSE Type: AWS::Config::ConfigRule Properties: ConfigRuleName: s3-bucket-server-side-encryption-enabled Source: { Owner: AWS, SourceIdentifier: S3_BUCKET_SERVER_SIDE_ENCRYPTION_ENABLED } ``` **Preventive — CDK Aspect (SEC 5, no open security groups), TypeScript:** ```typescript // guardrails/no-open-sg.aspect.ts import { IAspect, Annotations } from "aws-cdk-lib"; import { CfnSecurityGroupIngress } from "aws-cdk-lib/aws-ec2"; import { IConstruct } from "constructs"; // 🛡️ Preventive — fails `cdk synth` on 0.0.0.0/0 ingress to non-web ports export class NoOpenIngress implements IAspect { visit(node: IConstruct): void { if (node instanceof CfnSecurityGroupIngress && node.cidrIp === "0.0.0.0/0" && ![80, 443].includes(Number(node.fromPort))) { Annotations.of(node).addError(`SEC 5: security group open to 0.0.0.0/0 on port ${node.fromPort}`); } } } ``` **Preventive — cfn-guard rule (REL 9, stateful resources need deletion protection):** ``` # guardrails/reliability.guard # 🛡️ Preventive — blocks RDS instances without Multi-AZ + deletion protection AWS::RDS::DBInstance { Properties { MultiAZ == true DeletionProtection == true } } ``` ## Step 5: Produce the guardrails plan Output a structured deliverable: ```markdown # Well-Architected Guardrails: {Workload Name} ## Summary - **IaC dialect**: {CDK/CloudFormation/Terraform/SAM} - **Enforcement points used**: {CI / Config / SCP / alarms} - **Source**: {prior review / standalone scan} - **Controls generated**: {N} ({P} preventive, {D} detective) across {pillars} ## Controls by pillar ### {Pillar} — {WA Question/BP ID} - **Control**: {name} | 🛡️ Preventive / 🔍 Detective | Enforcement: {CI / Config / SCP / alarm} - **Blocks/flags**: {what, and why it matters} - **File**: `{path}` ```{lang} {ready-to-commit snippet} ``` - **Coverage gap** (if any): {what this control does NOT catch} ## Rollout plan | Order | Control | Enforcement | Risk of false-positive | Notes | |-------|---------|-------------|------------------------|-------| {Start in warn/log mode for preventive CI checks and SCPs, then promote to block once clean.} ## Verification {How to confirm each control works — e.g. attempt a known-bad change in a branch and confirm CI fails; check Config rule compliance status.} ## Not covered {Controls the available enforcement points cannot implement, and what would be needed.} ``` ## Step 6: Offer a governance steering doc Beyond machine-enforced controls, offer to capture the same standards as a **human- and agent-readable governance doc** — the prose counterpart to the guardrails. This is useful for the standards a control can't fully express (design conventions, review expectations) and for teams that want an always-on policy their AI coding agent will follow. Generate it on request as a steering file the agent loads automatically (e.g. `.kiro/steering/`, `CLAUDE.md`, `.cursor/rules/`), structured as: ```markdown # {Workload} — Well-Architected Guardrails (Governance) ## Enforced automatically {One line per machine control, linking the rule file and its WA BP ID — so readers know what is already gated in CI/Config.} ## Conventions to follow (not auto-enforced) - {Pillar} — {convention}, because {WA BP ID rationale}. {How a reviewer/agent checks it.} ## When proposing or reviewing changes to this workload - {Standing instruction, e.g. "new data stores MUST set encryption + backups before merge (SEC 8 / REL 9)"} ``` Keep each statement tied to a WA Question/BP ID, and keep the doc short enough to live in always-on context without bloat. ## Step 7: Offer follow-up > Would you like me to: > - Generate the CI workflow wiring (GitHub Actions / CodePipeline step) to run the policy checks? > - Produce a governance steering doc (`CLAUDE.md` / `.cursor/rules/` / `.kiro/steering/`) capturing these standards for your AI agent? > - Add auto-remediation to a detective Config rule (with safety review)? > - Fix the existing violations these guardrails would block (remediate the current code)? > - Tighten a control from warn mode to block mode? ## Calibration Guidance - Prefer **preventive** controls (catch in CI/IaC) over **detective** — they're cheaper and stop the problem before it ships; only fall back to detective when the issue is only visible on the live resource. - Never emit a control for an enforcement point the user doesn't have — say it's not enforceable and what's needed instead. - **Roll out preventive controls in warn/log mode first.** Recommending a hard `block` or `Deny` SCP on day one risks breaking existing pipelines — flag this and stage it. - Auto-remediation is **destructive**: only generate it when the user explicitly asks, and include a safety/rollback note. - Tie every control to a WA Question/BP ID so the builder can trace the rationale — a guardrail without a "why" gets disabled the first time it's inconvenient. - Don't over-generate: a focused set of high-value controls that the team will keep beats 50 noisy rules they'll mute. - Respect the workload's existing dialect and conventions — emit CDK Aspects for a CDK app, `cfn-guard` for CloudFormation, OPA/Sentinel for Terraform; don't mix paradigms. - The governance steering doc complements controls, it doesn't replace them — prefer a machine-enforced control whenever one exists, and use the doc for what code can't express. Keep it concise enough for always-on context.