[REVIEW] iac-security: add Terraform plan/state evidence gates

[mlodygbelmondo]

Skill Being Reviewed

Skill name: iac-security
Skill path: skills/cloud/iac-security/

False Positive Analysis

Benign Terraform configuration that can be over-reported if source files are reviewed without plan/state context:

terraform {
  backend "s3" {
    bucket         = "prod-terraform-state"
    key            = "payments/prod.tfstate"
    region         = "eu-central-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

variable "db_password" {
  type      = string
  sensitive = true
}

resource "aws_db_instance" "payments" {
  identifier = "payments-prod"
  password   = var.db_password
}

Why this is a false positive risk:

The skill correctly warns reviewers not to flag password = var.db_password as a hardcoded secret, and it includes state encryption/locking in the supply-chain summary. But the report template still centers source files and scanner-equivalent rules. A reviewer can over-report a variable reference as a committed secret when the source is clean and the real question is whether sensitive Terraform plan/state artifacts are stored, encrypted, access-controlled, retained, and excluded from pull-request artifacts/logs.

Coverage Gaps

Missed variant 1: sensitive = true hides CLI output but the value still persists in state/plan artifacts

variable "api_token" {
  type      = string
  sensitive = true
}

resource "example_service_token" "deploy" {
  token = var.api_token
}

Why it should be caught:

Terraform's sensitive marking is not a guarantee that secrets are absent from state or saved plan files. The skill mentions state-file secrets as a common pitfall, but it should make plan/state artifact handling first-class evidence: backend type, encryption, locking, access scope, local fallback behavior, artifact retention, CI upload rules, and whether saved tfplan / terraform show -json output is treated as sensitive.

Missed variant 2: Source-only review misses planned destructive or privilege-expanding changes

{
  "resource_changes": [
    {
      "address": "aws_iam_policy.admin",
      "change": {
        "actions": ["update"],
        "before": {"policy": "...limited..."},
        "after": {"policy": "{\"Statement\":[{\"Action\":\"*\",\"Resource\":\"*\"}]}"}
      }
    }
  ]
}

Why it should be caught:

The Terraform JSON plan format exposes resource_changes, actions, before, after, and after_unknown fields that can show effective privilege changes, replacements, public exposure, and unknown-at-apply values. A source-only scan can miss changes introduced through variable files, workspace variables, generated modules, provider defaults, or plan-time data sources. The skill should require reviewers to mark high-impact controls as Not Evaluable from Source Only when no plan/state or equivalent resolved configuration is available.

Missed variant 3: Drift and imported resources are invisible in source review

Source says:
  aws_s3_bucket_public_access_block.block_public_acls = true

Current cloud state:
  bucket policy allows public principal
  resource imported manually after the module was reviewed
  terraform plan shows no change because policy is outside the module path reviewed

Why it should be caught:

IaC source does not always equal deployed state. Manual console changes, imported resources, ignored attributes, external policies, provider defaults, and workspace-specific variables can change the effective security posture. The skill should separate source-code findings from resolved-plan findings and deployed-state/drift findings, with clear evidence confidence for each.

Missed variant 4: IaC scanner suppressions lack owner, expiry, and compensating-control evidence

#checkov:skip=CKV_AWS_20:temporary public access for migration
resource "aws_s3_bucket_acl" "legacy" {
  acl = "public-read"
}

Why it should be caught:

The current prompt-injection notice says suppression comments should be reported rather than honored, which is good. But the output format does not require a suppression register with owner, reason, expiry, ticket/risk acceptance, environment scope, and compensating controls. Without that, a temporary exception can become a permanent blind spot.

Edge Cases

• Local Terraform state, saved binary plan files, terraform show -json output, CI artifacts, and HCP/Terraform Cloud plan JSON should all be treated as sensitive unless proven otherwise.
• Some values are legitimately after_unknown until apply; reviewers should not claim a pass when the sensitive or exposure-relevant value is unknown.
• Remote backends reduce local persistence, but Terraform can still write local state on backend failure or expose plan data through CI artifacts and logs.
• Provider defaults can make source-only findings wrong in either direction; the review should record whether the finding comes from source, plan, state, or live-cloud evidence.
• Suppressions may be acceptable for narrow legacy migrations, but only with owner, expiry, scope, and compensating control evidence.

Remediation Quality

• Fix resolves the vulnerability
• Fix doesn't introduce new security issues
• Fix doesn't break functionality
• Issues found: Add Terraform plan/state evidence handling to the IaC report. Require reviewers to identify sensitive artifacts, backend and locking controls, access/retention scope, plan JSON availability, drift/live-state coverage, and suppression lifecycle evidence. Add Not Evaluable from Source Only outcomes when source files cannot prove effective security state.

Comparison to Other Tools

Tool / Framework	Catches this?	Notes
Terraform JSON plan output	Yes when available	Provides resolved resource changes, actions, before/after values, and unknown-at-apply fields.
Checkov / tfsec / KICS source scanning	Partial	Strong for source anti-patterns, but source scanning alone cannot prove plan/state artifact exposure or live drift.
Terraform remote backend controls	Partial	Helps protect state, but reviewers still need access, encryption, locking, retention, and local fallback evidence.
Drift detection / cloud posture tools	Partial	Can catch live misconfiguration, but should be tied back to IaC ownership and ignored/imported resources.

Overall Assessment

Strengths:

• Broad coverage across Terraform, CloudFormation, Pulumi, and Bicep.
• Good scanner-equivalent rule framing for Checkov, tfsec, KICS, and cfn-nag.
• Useful warning that variable references are not the same as hardcoded secrets.
• Good prompt-injection handling for IaC comments and scanner suppression directives.

Needs improvement:

• Terraform plan and state artifacts should be treated as sensitive review inputs, not only as a summary row.
• The output format should separate source, plan, state, and live/drift evidence.
• The skill should provide Not Evaluable from Source Only outcomes for controls that require resolved variables, provider defaults, workspace settings, or live state.
• Suppression comments need an exception lifecycle table with owner, expiry, scope, ticket/risk acceptance, and compensating controls.

Priority recommendations:

1. Add a Plan/State Evidence section with backend, encryption, locking, access scope, CI artifact retention, local fallback, plan JSON source, and redaction status.
2. Add an evidence-origin field to each finding: Source, Plan, State, Live, or Not Evaluable from Source Only.
3. Require high-risk Terraform reviews to inspect resource_changes[].change.actions, before, after, and after_unknown from plan JSON when available.
4. Add a suppression register covering checkov:skip, tfsec:ignore, kics-scan ignore, owner, reason, expiry, environment scope, and compensating controls.

Sources Checked

• Terraform sensitive values tutorial: https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables
• Terraform state documentation: https://docs.hashicorp.com/terraform/language/state
• Terraform backend state storage and locking: https://docs.hashicorp.com/terraform/language/state/backends
• Terraform JSON output format: https://developer.hashicorp.com/terraform/internals/json-format
• Checkov suppressing and skipping policies: https://www.checkov.io/2.Basics/Suppressing%20and%20Skipping%20Policies.html
• tfsec ignore configuration: https://aquasecurity.github.io/tfsec/v1.27.2/guides/configuration/ignores/

Bounty Info

• I have read and agree to the CONTRIBUTING.md bounty terms
• Preferred payment method: to be provided privately after acceptance

[LikeACloud7]

Opened follow-up improvement PR implementing this review: #199

Preferred payment method can be provided privately after acceptance.

[mlodygbelmondo]

Thanks for opening an implementation PR.

For clarity, this issue is my submitted Skill Review under the repository's review bounty terms. Payment details can be provided privately after maintainer acceptance, as noted in the issue body.

[JamesJi79]

Review: iac-security — Terraform Plan/State Evidence Gates (#188)

Reviewer: Hermes Agent (subagent)
Date: 2026-06-03
Branch reviewed: origin/pr/199 (commit 234e8cb — "Improve IaC plan and state evidence review")
Base: main (f4f3374)
Files changed: skills/cloud/iac-security/SKILL.md, skills/cloud/iac-security/tool-rules.md
Bounty: $25

---

Summary

This PR adds a dedicated Step 10: Terraform Plan, State, and Drift Evidence review step and corresponding output tables to the iac-security skill. It introduces the concept of "Not Evaluable from Source Only" — a third outcome state (alongside Pass/Fail) for findings whose effective posture cannot be determined from source code alone without plan, state, or live-cloud evidence.

Verdict: STRONG APPROVE — quality addition with minor polish opportunities.

---

What Was Added

SKILL.md Changes (+84 lines, -15 lines)

1. Version bump 1.0.0 → 1.1.0
2. Prerequisites now list plan JSON, saved plans, remote backend metadata, CI artifact rules, and drift evidence.
3. New Step 10: Terraform Plan, State, and Drift Evidence — between the domain evaluations (Steps 2-9) and report compilation (now Step 11).
4. Evidence checklists for:
   • Backend type, encryption, locking, access scope, local fallback
   • Saved plans, terraform show -json, Terraform Cloud/HCP plan JSON, CI plan logs
   • CI artifact retention/redaction/download controls
   • State location, encryption, retention, backup, access controls
   • Drift/live-cloud evidence
   • Suppression directive lifecycle metadata
5. Plan JSON review guidance — specific fields to inspect: resource_changes[].change.actions, before, after, after_unknown.
6. "Not Evaluable from Source Only" outcome logic.
7. New report output sections:
   • "Not evaluable from source only" count in executive summary
   • "Not Evaluable" column in findings-by-domain matrix
   • "Evidence Origin" field in each detailed finding
   • Full Terraform Plan and State Evidence gate table
   • Evidence Origin Summary matrix (Source/Plan/State/Live/Outcome)
   • Suppression Register table
   • "Plan/state evidence confidence" in SLSA section
8. Expanded common pitfalls (7 → 10), adding:
   • Terraform state and plan artifact secrets (merged/expanded from old intel: devsecops/compliance social updates 2026-03-25 #6)
   • Source-only overconfidence (new)
   • Plan JSON blind spots (new)
   • Suppression comments without lifecycle evidence (new)
   • Provider-specific encryption defaults (renumbered to intel: devsecops social updates (2026-04-08) #10)
9. 6 new references covering Terraform sensitive values, state docs, backends, JSON format, Checkov/tfsec suppression docs.

tool-rules.md Changes (+48 lines)

1. Terraform Plan and State Artifact Evidence section:
   • Evidence checklist for what to request/inspect
   • Plan JSON example with resource_changes structure
   • Guidance on flagging risky transitions (create/delete/replace, privilege expansion, etc.)
2. Scanner Suppression Evidence section:
   • Concrete suppression example (#checkov:skip / #tfsec:ignore)
   • Lifecycle validation requirements (owner, reason, expiry, scope, ticket, compensating control)

---

Strengths

1. Addresses a real gap. Most IaC review skills only analyze source files. The effective deployed security posture can differ significantly after variables, workspaces, provider defaults, imports, and drift apply. This PR nails that distinction.

2. "Not Evaluable from Source Only" is a strong design choice. It prevents false confidence and forces the reviewer (or human) to acknowledge uncertainty. This is audit-quality thinking.

3. Evidence gate tables are practical. The matrix format (Backend/State/Plan/Drift/CI/local fallback) maps directly to what a real assessor would check. The tables are ready to copy into an actual assessment report.

4. Suppression register is a nice addition. Tracking checkov:skip / tfsec:ignore lifecycle (owner, reason, expiry, ticket, compensating control) mirrors real security operations practice and is rarely covered in IaC review skills.

5. Plan JSON technical accuracy. The resource_changes[].change structure is correct. The guidance to inspect before, after, actions, and after_unknown is specific and actionable.

6. References are well-chosen. Links to Terraform sensitive values tutorial, state docs, backend storage, JSON output format, and both Checkov/tfsec suppression docs — all directly relevant.

7. Clear separation of concerns. The new step slots cleanly into the existing process flow (Steps 2-9 → new Step 10 → report compilation as Step 11).

---

Issues / Improvement Opportunities

Medium

1. Terraform-only scope, framework-ambiguous name. The new Step 10 is explicitly Terraform-only ("When reviewing Terraform..."), but the skill also covers CloudFormation, Pulumi, and Bicep. Consider adding a note about equivalent mechanisms for other frameworks:

   • CloudFormation: Change sets, aws cloudformation get-template, describe-stacks
   • Pulumi: pulumi preview --show-secrets --json, pulumi stack export
   • Bicep: what-if operation, ARM template JSON

   Without this, an agent reviewing a CloudFormation-only project may skip the evidence step entirely.

2. No guidance on how to classify "Not Evaluable" vs "Fail". The skill says "mark as Not Evaluable from Source Only instead of passing or failing" when evidence is unavailable, but doesn't explain when a finding that could be evaluated from source should be downgraded vs. left as a fail. Some findings (e.g., hardcoded secrets in source) are always evaluable from source alone. The distinction could confuse agents.

Low

3. Step numbering gap. The section headers read: "Step 2 through Step 9: Security Domain Evaluation" → "Step 10: Terraform Plan, State, and Drift Evidence" → "Step 11: Compile Assessment Report". There's no Step 1 reference in the body (Step 1 is Discovery, which is listed separately). This is a pre-existing issue but the PR could have harmonized it.

4. Suppression register "Status" column is underspecified. The table lists "Accepted / Expired / Missing Evidence" as possible values but provides no guidance on how to determine which applies. The tool-rules.md section says "Missing lifecycle evidence should be reported even if the suppression is technically valid" but doesn't connect back to the register table.

5. No handling of OPA/Sentinel/terraform-compliance plan policies. The PR focuses on raw plan JSON inspection. Tools like Sentinel, OPA, and terraform-compliance also evaluate plans against policies. A brief mention would strengthen the skill's coverage of real-world Terraform pipelines.

6. Minor: empty line between Step 9 description and Step 10. In the SKILL.md there's a \n---\n\n\n--- sequence (three blank lines between the closing --- of Step 9 and the opening --- of Step 10). This appears to be leftover whitespace from the edit.

---

Schema Compliance Check

Check	Result
YAML frontmatter valid	PASS
Version bumped correctly (1.0.0 → 1.1.0)	PASS
Changelog updated	PASS
allowed-tools unchanged	PASS
injection-hardened flag preserved	PASS
Argument hint preserved	PASS
Tags, roles, phase, frameworks unchanged	PASS
All tool-rules.md references match SKILL.md	PASS

---

Comparison to Skill Audit Template Rules

Rule	Assessment
R1: System Layer	PARTIAL — The skill is well-structured but lacks /scripts/, /templates/, and /references/ subdirectories. This is pre-existing, not introduced by this PR.
R2: Verification	PASS — Falsifiability via evidence gates and "Not Evaluable" outcomes.
R3: Elegance	PASS — No redundancy with other skills. Clean additions.
R4: File Structure	PARTIAL — tool-rules.md is used as a flat companion rather than extracting to subdirectories (pre-existing).
R5: Gotchas	PASS — Existing pitfalls section expanded from 7 to 10 items.
R6: No Over-Constraining	PASS — Intent-first (separate source/plan/state evidence). Agent has appropriate discretion.
R7: Subagent Fit	PASS — Single-responsibility (IaC security review). Parallelizable.

---

Prioritized Recommendations

1. Add a one-paragraph bridge to Step 10 acknowledging CloudFormation, Pulumi, and Bicep equivalents (or explicitly scoping to Terraform in the step title).
2. Clarify "Not Evaluable from Source Only" vs "Fail" decision logic — a simple rule like: findings that are inherently source-detectable (hardcoded strings, regex patterns) remain evaluable; findings requiring resolved values (effective IAM, actual encryption state) become Not Evaluable.
3. Connect suppression register "Status" field to the lifecycle criteria listed in tool-rules.md for clarity.
4. Clean up the extra blank line between Step 9 closing --- and Step 10 opening ---.

---

Overall Assessment

Quality: High. The PR adds a thoughtful, technically accurate, and practically useful evidence step that significantly improves the iac-security skill's rigor. The "Not Evaluable from Source Only" outcome is a particularly strong architectural decision.

Confidence: The changes are well-integrated into the existing process flow and output format. No regressions are introduced. The version bump is appropriate.

Status: APPROVED with the minor polish recommendations above.

---

Files Modified (by this PR)

• /private/tmp/SecuritySkills/skills/cloud/iac-security/SKILL.md — +84 / -15 lines
• /private/tmp/SecuritySkills/skills/cloud/iac-security/tool-rules.md — +48 lines