--- name: iac-terraform-audit description: Audit Terraform, OpenTofu, Terragrunt, and Pulumi modules for state, provider pinning, security (Checkov/tfsec), module hygiene, environment separation, drift, and cost. One sub-agent per module. Static, live, and apply modes. argument-hint: [module-path-or-glob] allowed-tools: Read Grep Glob Write Edit Bash(bash:*) Agent effort: high paths: "**/*.tf" --- # IaC Terraform Audit ultrathink > **Output path directive (canonical — overrides in-body references).** > All file outputs from this skill MUST be written under `.anthril/audits/iac-terraform-audit/`. > Run `mkdir -p .anthril/audits/iac-terraform-audit` before the first `Write` call. > Primary artefact: `.anthril/audits/iac-terraform-audit/`. > Do NOT write to the project root or to bare filenames at cwd. > Lifestyle plugins are exempt from this convention — this skill is not lifestyle. ## When to use Run this skill when the user mentions: - Terraform review, IaC audit, infrastructure security - Checkov, tfsec, OpenTofu review, Pulumi audit - Pre-migration infra cleanup - State file concerns, provider pinning, module design Covers eight categories: state and backend configuration (remote state, encryption, locking, workspace separation), provider pinning (`required_providers` with version constraints, `required_version`), security (Checkov/tfsec taxonomy — public S3 ACLs, unencrypted RDS, open security groups, wildcard IAM, plaintext secrets in tfvars), module hygiene (variable validation, descriptions, types, outputs, sensitive flag), environment separation, drift risk, cost hotspots, and CI testing coverage. ## Before You Start 1. **Determine operating mode.** `--live` runs `terraform plan` against each module (refresh-only, no apply). `--apply` writes HCL patches. `--runtime` is not applicable (Terraform has no safe runtime test). 2. **Enumerate modules.** Run `scripts/list-modules.sh` — groups `.tf` files by directory. 3. **Sub-agent budget.** One agent per module. Warn above 10. 4. **Load `.iac-ignore`** for suppressions (pattern: `:` or `:*`). 5. **Live-mode requirements.** `terraform init` must succeed per module — warn the user if state backends require credentials and fall back to static audit for modules that can't initialise. ## User Context $ARGUMENTS Module inventory: !`bash "${CLAUDE_PLUGIN_ROOT}/skills/iac-terraform-audit/scripts/list-modules.sh"` Tools: !`which terraform tofu 2>/dev/null | head -1 || echo "terraform:unavailable"` · !`which checkov tfsec 2>/dev/null | head -1 || echo "checkov:unavailable"` --- ## Audit Phases ### Phase 1: Discovery & Mode Selection 1. Parse module inventory. Identify Terraform / OpenTofu / Terragrunt / Pulumi. 2. Confirm scope; warn if >10 modules. 3. Verify live-mode tools. Fall back per-module if `terraform init` fails. ### Phase 2: Per-Module Snapshot For each module, parse HCL (via `hcl2json` if available, else structural grep): - Providers (`required_providers`, version constraints, source) - Required Terraform version (`required_version`) - Backend config (type, encryption, locking) - Resources (by provider+type, name) - Variables (with type, default, description, sensitive, validation) - Outputs (with sensitive, description) - Locals - Data sources - Module calls (local / registry / Git, with version) - Lifecycle blocks In `--live` mode, additionally run `terraform plan -refresh-only` and capture the summary (additions / changes / destructions predicted). ### Phase 3: Cross-Module Topology 1. Build a module-dependency graph (who calls whom via `module.` blocks, who reads whose state via `terraform_remote_state`). 2. Detect shared backends (multiple modules writing to the same state key — usually a bug). 3. Emit Mermaid graph for the report. ### Phase 4: Parallel Sub-Agent Audit Spawn one `Agent(subagent_type=Explore)` per module in a single assistant message. Each walks categories A–H in `reference.md` §1: - **A. State & Backend** — remote backend, encryption at rest, state locking (DynamoDB / GCS / etc.), workspace separation, state file not in git - **B. Provider pinning** — `required_providers` with `~>` or exact, `required_version` set, source pinned to a hash registry URL - **C. Security (Checkov/tfsec)** — open SGs, public S3 ACLs, unencrypted RDS, IAM `*`, KMS missing, plaintext secrets, EBS/EFS encryption - **D. Module hygiene** — variables with `type` and `description`, `validation` blocks for bounded inputs, `sensitive = true` on secrets, outputs documented - **E. Environment separation** — workspace or directory per env, no cross-env refs, prod state isolated - **F. Drift risk** — `lifecycle.ignore_changes` abuse (should be targeted), `null_resource` for imperative work, `create_before_destroy` on resources that require it - **G. Cost hotspots** — oversized default instance types, unbounded autoscaling max, NAT Gateways when cheaper egress suffices, attached-but-unused EIPs - **H. Testing & CI** — `terraform fmt` / `validate` / `tflint` integration in CI, `terraform-docs` generation, pre-commit hooks Sub-agents MUST NOT run `terraform apply` / `terraform destroy` / state-mutating commands. Read-only plans only. ### Phase 5: Cross-Module Analysis - Duplicate resource patterns across modules → module extraction candidates - Cyclic dependencies via `terraform_remote_state` - Provider version drift (module A uses AWS ~>5, module B uses ~>4) - Missing `required_version` consistency ### Phase 6: Merge & Risk Register Consolidate findings. Dedupe via `.iac-ignore`. Apply severity adjustments: - Findings on production modules (determined via workspace name or directory convention) keep severity - Findings on non-prod modules downgrade one tier - Checkov/tfsec findings (if live tools available) cross-validated with sub-agent output Assign `IAC-001…` IDs. ### Phase 7: Remediation Drafting Emit commented HCL blocks to `iac-suggested.tf`. Rules: - **Every FK-like resource relationship** uses `depends_on = []` explicit when needed - **Every state change to sensitive resources** is commented with `# MANUAL REVIEW — STATE RISK` - **Provider pinning suggestions** include both the current pin and the recommended - **Module extraction suggestions** emit a minimal new module skeleton in a sub-block of the suggestion file ### Phase 8: Apply Mode (opt-in) When `--apply`, iterate findings with `[a]pply / [s]kip / [A]ll / [q]uit`. Any HCL change that would affect state (adding `lifecycle { prevent_destroy = true }`, changing a backend key) requires `DESTROY` confirmation. ### Phase 9: Reporting Write `iac-terraform-audit.md` + `iac-terraform-audit.json` + `iac-suggested.tf` (+ `terraform-plan.txt` in live mode). --- ## Scoring Weights: A=20, B=10, C=30, D=10, E=10, F=10, G=5, H=5 (sum 100). See `reference.md` §3. | Total | Verdict | |---|---| | 90+ | PASS | | 70–89 | PASS WITH WARNINGS | | 50–69 | CONDITIONAL | | <50 | FAIL | --- ## Important Principles - **State is the crown jewel.** Remote, encrypted, locked, and never in git. - **`~>` is a minor-version pin.** `~>5.0` allows 5.x; `~>5.0.0` allows 5.0.x. Know which you want. - **Security findings that are true on paper may be false in context.** A public S3 ACL on a static-site bucket is intentional. Flag but let the user suppress. - **`lifecycle.ignore_changes = all` is almost always wrong.** Target specific attributes. - **`null_resource` + `local-exec` is imperative.** Flag every occurrence. - **Cost findings are suggestions, never failures.** Use INFO severity. - **Australian English. DD/MM/YYYY. Markdown-first.** --- ## Edge Cases 1. **Terragrunt.** Parse `terragrunt.hcl` blocks (`include`, `dependency`, `generate`). Findings on generated files go to the `terragrunt.hcl` that generated them. 2. **Pulumi.** Parse `index.ts` / `__main__.py`. Map to the same A–H taxonomy. 3. **CDK (TypeScript/Python).** Skip — not in scope. Emit one finding: "CDK module detected; not covered by this skill." 4. **Remote module (`source = "git::..."` or `source = "terraform-aws-modules/..."`).** Audit the caller's reference and the version; do not recurse into the remote. 5. **`terraform init` fails in live mode.** Record as a module-level limitation; continue static audit. 6. **State encrypted with SSE-KMS but key is unmanaged.** Flag MEDIUM — "encrypted but key lifecycle unclear". 7. **Mono-repo with many modules.** Cluster by top-level directory; one sub-agent per cluster if counts are high. 8. **A module has only data sources, no resources.** Audit the providers and backend; skip C/F.