terraform-validator skill by akin-ozer

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
TFLint	github.com/terraform-linters/tflint
Checkov	checkov.io
Trivy	aquasecurity.github.io/trivy

Validation Workflow

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

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 provider/module info	`extract_tf_info_wrapper.sh`	`bash scripts/extract_tf_info_wrapper.sh <path>`
Run security scan	`run_checkov.sh`	`bash scripts/run_checkov.sh <path>`
Install checkov (if missing)	`install_checkov.sh`	`bash scripts/install_checkov.sh install`

Note: extract_tf_info_wrapper.sh automatically handles the python-hcl2 dependency. If system Python lacks python-hcl2, it creates/reuses a cached virtual environment under ~/.cache/terraform-validator/ by default.

Script Run Context (REQUIRED)

Default working directory: devops-skills-plugin/skills/terraform-validator
If running from elsewhere, use absolute script paths:
- bash /absolute/path/to/terraform-validator/scripts/extract_tf_info_wrapper.sh <path>
- bash /absolute/path/to/terraform-validator/scripts/run_checkov.sh <path>
- bash /absolute/path/to/terraform-validator/scripts/install_checkov.sh install

Context7 Provider Documentation Lookup (REQUIRED)

For EVERY provider detected, you MUST lookup documentation via Context7:

Example for AWS provider:

Context7 Fallback to WebSearch (REQUIRED)

If Context7 does not find a provider, you MUST fall back to WebSearch:

WebSearch Fallback Example:

Note: HashiCorp utility providers (random, null, local, time, tls, archive, external, http) may not be indexed in Context7. Always fall back to WebSearch for these.

Detecting Implicit Providers (REQUIRED)

IMPORTANT: Providers can be used without being declared in required_providers. You MUST detect ALL providers:

Detection Methods

Explicit Providers: Listed in required_providers block (from extract_tf_info_wrapper.sh output)
Implicit Providers: Inferred from resource type prefixes

Common Implicit Provider Patterns

Resource Type Prefix	Provider Name	Context7 Lookup
`random_*`	`random`	`terraform-provider-random`
`null_*`	`null`	`terraform-provider-null`
`local_*`	`local`	`terraform-provider-local`
`tls_*`	`tls`	`terraform-provider-tls`
`time_*`	`time`	`terraform-provider-time`
`archive_*`	`archive`	`terraform-provider-archive`
`http` (data source)	`http`	`terraform-provider-http`
`external` (data source)	`external`	`terraform-provider-external`

Workflow for Complete Provider Detection

Example

If extract_tf_info_wrapper.sh returns:

You MUST lookup BOTH:

terraform-provider-aws (explicit)
terraform-provider-random (implicit - detected from random_id resource)

Quick Reference Commands

Format and Lint

TFLint Configuration: See TFLint Ruleset documentation for plugin setup.

Validate Configuration

Security Scanning

MUST use wrapper script:

Detailed Security Scanning: You MUST read references/security_checklist.md before running security scans to understand the checks and remediation patterns.

Security Finding Cross-Reference (REQUIRED)

When reporting security findings, you MUST cite specific sections from security_checklist.md:

Cross-Reference Mapping

Checkov Check Pattern	security_checklist.md Section
`CKV_AWS_24` (SSH open)	"Overly Permissive Security Groups"
`CKV_AWS_260` (HTTP open)	"Overly Permissive Security Groups"
`CKV_AWS_16` (RDS encryption)	"Encryption at Rest"
`CKV_AWS_17` (RDS public)	"RDS Databases"
`CKV_AWS_130` (public subnet)	"Network Security"
`CKV_AWS_53-56` (S3 public access)	"Public S3 Buckets"
`CKV_AWS_*` (IAM)	"IAM Security"
`CKV_AWS_79` (IMDSv1)	"ECS/EKS"
Hardcoded passwords	"Hardcoded Credentials"
Sensitive outputs	"Sensitive Output Exposure"

Report Template for Security Findings

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.

Dry-Run Testing

Plan Output Symbols:

+ Resources to be created
- Resources to be destroyed
~ Resources to be modified
-/+ Resources to be replaced

Handling Missing Tools

When validation tools are not installed, follow this recovery workflow:

Recovery Workflow (REQUIRED)

Tool-Specific Recovery

If checkov is missing:

If tflint is missing:

If python-hcl2 is missing:

Required tools: terraform fmt, terraform init, terraform validate Required for full security validation: checkov Optional but recommended: tflint

Scripts

Script	Purpose	Usage
`extract_tf_info_wrapper.sh`	Parse Terraform files for providers/modules (auto-handles dependencies)	`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`

Reference Documentation

MUST READ during validation workflow:

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

Workflow Examples

Example 1: Validate Single File

Example 2: Full Module Validation

Example 3: Production Dry-Run

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.

MUST 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

Notes

Always run validation in order: extract info → lookup docs → read refs → format → lint → validate → security → plan
MUST use wrapper scripts for extract_tf_info and checkov
MUST run bash tests/test_regression.sh after script changes
MUST run lightweight CI checks: bash -n scripts/*.sh and python3 -m py_compile scripts/*.py
MUST read reference files before relevant validation steps
MUST lookup provider docs via Context7 for ALL providers
MUST offer recovery/rerun when tools are missing
Never commit without running terraform fmt
Always review plan output before applying
Use version constraints for all providers and modules
Use remote state for team collaboration
Enable state locking to prevent concurrent modifications

Done Criteria

Validation instructions are executable end-to-end with one deterministic command path.
Wrapper scripts behave predictably in both success and failure paths (including propagated non-zero exits).
Regression tests cover parser error handling, implicit provider detection, wrapper argument handling, and checkov exit-code behavior.
Lightweight CI checks (bash -n, py_compile, smoke checks) pass before final reporting.