terraform-validator

name	terraform-validator
description	Comprehensive toolkit for validating, linting, testing, and automating Terraform configurations and HCL files. Use this skill when working with Terraform files (.tf, .tfvars), validating infrastructure-as-code, debugging Terraform configurations, performing dry-run testing with terraform plan, or working with custom providers and modules.

Terraform Validator

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

When to Use This Skill

Use this skill when you need to:

• Validate .tf or .tfvars files for syntax, provider-schema, and type correctness.
• Lint Terraform against style and correctness rules with tflint.
• Run a security scan (Checkov/Trivy) and produce an evidence-cited findings report.
• Dry-run a change with terraform plan before it is applied.
• Diagnose a validation or provider error against a known-error database.

When NOT to use this skill:

• Generating new Terraform from scratch — use terraform-generator instead.
• Applying changes to real infrastructure (terraform apply) — validation stops at plan; apply is an operator decision, not a validation step.
• Non-Terraform IaC (CloudFormation, Pulumi, Bicep) — the parsers and rule sets here are Terraform-specific.

Mindset

• Fail closed on required steps. A step marked Required is a gate, not a suggestion. If a required tool is unavailable, surface it and ask before continuing rather than silently skipping.
• Evidence over assertion. Every finding cites an exact file:line and the reference-file section that explains it. Never report an untraceable warning.
• Validate from the root, not the module. A module that passes in isolation can still fail when called with the root's real inputs; test the way it is actually consumed.
• Machines gate the known-bad; humans judge the risk. Automated scanners block known violations, but HIGH and CRITICAL findings route to a human before merge.

Validation Workflow

Execute these steps in order. Steps marked Required must not be skipped.

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

Steps 3–4 (reading reference files) must be completed before running security scans. The reference files contain remediation patterns that must be cited in the report.

External Documentation

Tool	Documentation
Terraform	developer.hashicorp.com/terraform
TFLint	github.com/terraform-linters/tflint
Checkov	checkov.io
Trivy	aquasecurity.github.io/trivy

Scripts Reference

Use these wrapper scripts instead of calling tools directly:

Script	Purpose	Command
extract_tf_info_wrapper.sh	Parse Terraform files for providers/modules (auto-handles python-hcl2 via temporary venv)	bash scripts/extract_tf_info_wrapper.sh <path>
extract_tf_info.py	Core parser (requires python-hcl2)	Use wrapper instead
run_checkov.sh	Wrapper for Checkov scans with enhanced output	bash scripts/run_checkov.sh <path>
install_checkov.sh	Install Checkov in isolated venv	bash scripts/install_checkov.sh install

Provider Documentation Lookup

Detection and lookup workflow:

1. Run extract_tf_info_wrapper.sh to get provider list
2. Collect explicit providers from "providers" array
3. Detect implicit providers from resource type prefixes:
   - Extract prefix (e.g., "random" from "random_id")
   - Common implicit: random, null, local, tls, time, archive, http, external
4. For each provider (explicit + implicit):
   a. Call: mcp__context7__resolve-library-id with "terraform-provider-{name}"
   b. Call: mcp__context7__get-library-docs with the resolved ID
   c. If Context7 fails: WebSearch("terraform-provider-{name} hashicorp documentation site:registry.terraform.io")
5. Include relevant provider guidance in validation report

Note: HashiCorp utility providers (random, null, local, time, tls, archive, external, http) are often not indexed in Context7 — use WebSearch directly for these.

Required Reference Files

Read these files at the specified points in the workflow:

When	Reference File	Content
Before security scan	references/security_checklist.md	Security checks, Checkov/Trivy usage, remediation patterns
During validation	references/best_practices.md	Project structure, naming conventions, module design, state management
When errors occur	references/common_errors.md	Error database with causes and solutions
If Terraform >= 1.10	references/advanced_features.md	Ephemeral values (1.10+), Actions (1.14+), List Resources (1.14+)

Security Finding Reports

When reporting security findings from Checkov/Trivy scans, cross-reference specific sections from security_checklist.md. The security checklist contains:

• Checkov check ID to section mappings
• Remediation patterns with code examples
• Severity guidelines

Report Template for Security Findings

### Security Issue: [Check ID]

**Finding:** [Description from checkov]
**Resource:** [Resource name and file:line]
**Severity:** [HIGH/MEDIUM/LOW]

**Reference:** security_checklist.md - "[Section Name]" (see relevant section for check ID)

**Remediation Pattern:**
[Copy relevant code example from security_checklist.md]

**Recommended Fix:**
[Specific fix for this configuration]

Example Cross-Referenced Report

### Security Issue: CKV_AWS_24

**Finding:** Security group allows SSH from 0.0.0.0/0
**Resource:** aws_security_group.web (main.tf:47-79)
**Severity:** HIGH

**Reference:** security_checklist.md - "Overly Permissive Security Groups"

**Remediation Pattern (from reference):**
```hcl
variable "admin_cidr" {
  description = "CIDR block for admin access"
  type        = string
}

resource "aws_security_group" "app" {
  ingress {
    description = "SSH from admin network only"
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = [var.admin_cidr]
  }
}

Recommended Fix: Replace cidr_blocks = ["0.0.0.0/0"] with a variable or specific CIDR range.

## Handling Missing Tools

When a validation tool is not installed:

1. Inform user what is missing and why it's needed
2. Provide the installation command
3. Ask: "Would you like me to install [tool] and continue?"
4. If yes: run installation and rerun the validation step
5. If no: note as skipped in report, continue with available tools

**If checkov is missing:** Ask to install via `bash scripts/install_checkov.sh install`, then rerun security scan.

**If tflint is missing:** Ask to install (`brew install tflint` on macOS or equivalent), note as skipped if the user opts out.

**If python-hcl2 is missing:** `extract_tf_info_wrapper.sh` handles this automatically via a temporary venv — no user action required.

**Required tools:** `terraform fmt`, `terraform validate`  
**Optional but recommended:** `tflint`, `checkov`

## Advanced Features

Terraform 1.10+ introduces ephemeral values for secure secrets management. Terraform 1.14+ adds Actions for imperative operations and List Resources for querying infrastructure.

Read `references/advanced_features.md` when:
- Terraform version >= 1.10 is detected
- Configuration uses `ephemeral` blocks
- Configuration uses `action` blocks
- Configuration uses `.tfquery.hcl` files

## Integration with Other Skills

- **k8s-yaml-validator** — For Terraform Kubernetes provider validation
- **helm-validator** — When Terraform manages Helm releases
- **k8s-debug** — For debugging infrastructure provisioned by Terraform

## Anti-Patterns

### NEVER skip `terraform validate` before `tflint`

- **WHY**: `terraform validate` checks provider schema compliance and catches type errors that tflint rules cannot detect; without it, tflint may produce misleading or incomplete output.
- **BAD**: Run only `tflint --recursive` and treat a clean result as validation complete.
- **GOOD**: Always run `terraform init -backend=false && terraform validate` first, then `tflint --recursive`.

### NEVER ignore `tflint` warnings for missing variable declarations

- **WHY**: Undeclared variables are silently treated as null by Terraform, masking misconfiguration that only surfaces as a runtime error at apply time.
- **BAD**: Dismiss `terraform_required_variables` warnings from tflint as non-critical.
- **GOOD**: Declare every variable in `variables.tf` with type and description; run `terraform validate` to confirm no undeclared references remain.

### NEVER use Checkov or `tfsec` results as the sole security gate

- **WHY**: These tools flag known-bad rule violations but cannot reason about your organization's specific threat model; automated exit codes alone are insufficient for high-severity findings.
- **BAD**: Automate all security approval or denial decisions solely on Checkov exit code with no human review.
- **GOOD**: Use Checkov to automatically block known-bad patterns; route HIGH and CRITICAL findings to a human review step before merging.

### NEVER validate modules in isolation without testing from the calling root configuration

- **WHY**: A module that validates cleanly in isolation can still fail when integrated with incompatible variable types or missing required inputs from the root.
- **BAD**: Run `terraform validate` inside `modules/network/` independently and skip root-level testing.
- **GOOD**: Validate from the root configuration that calls the module using realistic variable values (e.g., via a `terraform.tfvars` fixture).

## References

### Format and Lint

```bash
# Check formatting (dry-run)
terraform fmt -check -recursive .

# Apply formatting
terraform fmt -recursive .

# Run tflint
tflint --init              # Install plugins
tflint --recursive         # Lint all modules
tflint --format compact    # Compact output

Validate Configuration

terraform init             # Downloads providers and modules
terraform validate         # Validate syntax
terraform validate -json   # JSON output

Security Scanning

# Use the wrapper script
bash scripts/run_checkov.sh ./terraform

# With specific options
bash scripts/run_checkov.sh -f json ./terraform
bash scripts/run_checkov.sh --compact ./terraform

Dry-Run Testing

terraform plan                               # Generate execution plan
terraform plan -out=tfplan                   # Save plan to file
terraform plan -var-file="production.tfvars" # Plan with var file
terraform plan -target=aws_instance.example  # Plan specific resource

Plan output symbols: + create · - destroy · ~ modify · -/+ replace