/terraform-validator

name: terraform-validator
description: Validate, lint, audit, or plan Terraform/.tf/HCL files; runs tflint, checkov, terraform validate.

Terraform Validator

Comprehensive toolkit for validating, linting, and testing Terraform configurations with automated workflows for syntax validation, security scanning, and intelligent documentation lookup.

⚠️ Critical Requirements Checklist

**STOP: You MUST complete these steps in order. Do NOT skip any REQUIRED step.**

| Step | Action | Required | |------|--------|----------| | 1 | Run `bash scripts/extract_tf_info_wrapper.sh <path>` | ✅ REQUIRED | | 2 | Context7 lookup for **ALL** providers (explicit AND implicit); **WebSearch fallback if not found** | ✅ REQUIRED | | 3 | **READ** `references/security_checklist.md` | ✅ REQUIRED | | 4 | **READ** `references/best_practices.md` | ✅ REQUIRED | | 5 | Run `terraform fmt` | ✅ REQUIRED | | 6 | Run `tflint` (or note as skipped if unavailable) | Recommended | | 7 | Run `terraform init` (if not initialized) | ✅ REQUIRED | | 8 | Run `terraform validate` | ✅ REQUIRED | | 9 | Run `bash scripts/run_checkov.sh <path>` | ✅ REQUIRED | | 10 | Cross-reference findings with `security_checklist.md` sections | ✅ REQUIRED | | 11 | Generate report citing reference files | ✅ REQUIRED | | 12 | Run regression tests (`bash tests/test_regression.sh`) | ✅ REQUIRED | | 13 | Run lightweight CI checks (`bash -n`, `py_compile`, smoke) | ✅ REQUIRED |

> **IMPORTANT:** Steps 3-4 (reading reference files) must be completed BEFORE running security scans. The reference files contain remediation patterns that MUST be cited in your report.

> **Context7 Fallback:** If Context7 does not have a provider (common for: random, null, local, time, tls), use WebSearch: `"terraform-provider-{name} hashicorp documentation"`

When to Use This Skill

• Working with Terraform files (`.tf`, `.tfvars`, `.tfstate`)
• Validating Terraform configuration syntax and structure
• Linting and formatting HCL code
• Performing dry-run testing with `terraform plan`
• Debugging Terraform errors or misconfigurations
• Understanding custom Terraform providers or modules
• Security validation of Terraform configurations

External Documentation

| Tool | Documentation | |------|---------------| | **Terraform** | [developer.hashicorp.com/terraform](https://developer.hashicorp.com/terraform/docs) | | **TFLint** | [github.com/terraform-linters/tflint](https://github.com/terraform-linters/tflint) | | **Checkov** | [checkov.io](https://www.checkov.io/1.Welcome/Quick%20Start.html) | | **Trivy** | [aquasecurity.github.io/trivy](https://aquasecurity.github.io/trivy) |

Validation Workflow

**IMPORTANT:** Follow this workflow in order. Each step is REQUIRED unless explicitly marked optional.

1. Identify Terraform files in scope
   ├─> Single file, directory, or multi-environment

2. Extract Provider/Module Info (REQUIRED)
   ├─> MUST run: bash scripts/extract_tf_info_wrapper.sh <path>
   ├─> Parse output for providers and modules
   └─> Use for Context7 documentation lookup

3. Lookup Provider Documentation (REQUIRED)
   ├─> For EACH provider detected:
   │   ├─> mcp__context7__resolve-library-id with "terraform-provider-{name}"
   │   ├─> mcp__context7__query-docs for version-specific guidance
   │   └─> If NOT found in Context7: WebSearch fallback (see below)
   └─> Note any custom/private providers for WebSearch

4. Read Reference Files (REQUIRED before validation)
   ├─> MUST READ: references/security_checklist.md (before security scan)
   ├─> MUST READ: references/best_practices.md (for structure validation)
   └─> Reference common_errors.md if errors occur

5. Format and Lint (REQUIRED)
   ├─> MUST run: terraform fmt -recursive (auto-fix formatting)
   ├─> MUST run: terraform fmt -check -recursive (verify no drift)
   ├─> RUN: tflint (or note as skipped if unavailable)
   └─> Report formatting issues

6. Syntax Validation (REQUIRED)
   ├─> MUST run: terraform init (if not initialized)
   ├─> MUST run: terraform validate
   └─> Report syntax errors (consult common_errors.md)

7. Security Scanning (REQUIRED)
   ├─> MUST run: bash scripts/run_checkov.sh <path>
   ├─> Analyze policy violations against security_checklist.md
   └─> Suggest remediations from reference

8. Dry-Run Testing (if credentials available)
   ├─> terraform plan
   ├─> Analyze planned changes
   └─> Report potential issues

9. Regression and Wrapper Determinism Checks (REQUIRED)
   ├─> MUST run: bash tests/test_regression.sh
   ├─> Confirms parser error handling returns non-zero
   ├─> Confirms implicit provider detection for docs lookup
   ├─> Confirms wrapper argument handling is deterministic
   └─> Confirms checkov wrapper preserves scanner exit code

10. Lightweight CI Checks (REQUIRED)
   ├─> MUST run: bash -n scripts/*.sh
   ├─> MUST run: python3 -m py_compile scripts/*.py
   ├─> MUST run: smoke check for extract wrapper on sample fixture
   └─> Record command outputs and exit codes

11. Generate Comprehensive Report
   ├─> Include all findings with severity
   ├─> Reference best_practices.md for recommendations
   └─> Offer to fix issues if appropriate

Required Reference File Reading

**You MUST read these reference files during validation:**

| When | Reference File | Action | |------|----------------|--------| | **Before security scan** | `references/security_checklist.md` | Read to understand security checks and remediation patterns | | **During validation** | `references/best_practices.md` | Read to validate project structure, naming, and patterns | | **If errors occur** | `references/common_errors.md` | Read to find solutions for specific error messages | | **If using Terraform 1.10+** | `references/advanced_features.md` | Read to understand ephemeral values, actions, list resources |

Required Script Usage

**You MUST use these wrapper scripts instead of calling tools directly:**

| Task | Script | Command | |------|--------|---------| | **Extract pro