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.

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 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:

1. Run extract_tf_info_wrapper.sh to get provider list
2. For each provider (e.g., "aws", "google", "azurerm"):
   a. Call: mcp__context7__resolve-library-id with "terraform-provider-{name}"
   b. Call: mcp__context7__query-docs with the resolved ID
   c. Note version-specific features and constraints
3. Include relevant provider guidance in validation report

Example for AWS provider:

mcp__context7__resolve-library-id("terraform-provider-aws")
mcp__context7__query-docs(context7CompatibleLibraryID, "best practices")

Context7 Fallback to WebSearch (REQUIRED)

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

1. If mcp__context7__resolve-library-id returns no results or provider not found:
   a. Use WebSearch with query: "terraform-provider-{name} hashicorp documentation"
   b. For specific version: "terraform-provider-{name} {version} documentation site:registry.terraform.io"
2. Common providers NOT in Context7 (use WebSearch directly):
   - random (hashicorp/random)
   - null (hashicorp/null)
   - local (hashicorp/local)
   - time (hashicorp/time)
   - tls (hashicorp/tls)
3. Document in report: "Provider docs via WebSearch (not in Context7)"

WebSearch Fallback Example:

# If Context7 fails for random provider:
WebSearch("terraform-provider-random hashicorp documentation site:registry.terraform.io")

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

1. Parse extract_tf_info_wrapper.sh output
2. Get providers from "providers" array (explicit)
3. Get resources from "resources" array
4. For EACH resource type:
   a. Extract prefix (e.g., "random" from "random_id")
   b. Check if already in providers list
   c. If NOT in providers: add as implicit provider
5. Perform Context7 lookup for ALL providers (explicit + implicit)

Example

If extract_tf_info_wrapper.sh returns:

{
  "providers": [{"name": "aws", ...}],
  "resources": [
    {"type": "aws_instance", ...},
    {"type": "random_id", ...}
  ]
}

You MUST lookup BOTH:

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

Quick Reference Commands

Format and Lint

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

# Apply formatting
terraform fmt -recursive .

# Run tflint (requires .tflint.hcl config)
tflint --init              # Install plugins
tflint --recursive         # Lint all modules
tflint --format compact    # Compact output

TFLint Configuration: See TFLint Ruleset documentation for plugin setup.

Validate Configuration

# Initialize (downloads providers and modules)
terraform init

# Validate syntax
terraform validate

# Validate with JSON output
terraform validate -json

Security Scanning

MUST use wrapper script:

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

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

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

### Security Issue: [Check ID]

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

**Reference:** security_checklist.md - "[Section Name]"

**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.

Dry-Run Testing

# Generate execution plan
terraform plan

# Save plan to file
terraform plan -out=tfplan

# Plan with specific var file
terraform plan -var-file="production.tfvars"

# Plan with target resource
terraform plan -target=aws_instance.example

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)

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

Tool-Specific Recovery

If checkov is missing:

1. Inform: "Checkov is not installed. It's required for security scanning."
2. Ask: "Would you like me to install it? I'll use: bash scripts/install_checkov.sh install"
3. If yes: Run install script, then rerun security scan

If tflint is missing:

1. Inform: "TFLint is not installed. It provides advanced linting beyond terraform validate."
2. Ask: "Would you like me to install it?"
3. Provide: brew install tflint (macOS) or installation script (Linux)

If python-hcl2 is missing:

The extract_tf_info_wrapper.sh script handles this automatically by creating
or reusing a cached venv. No user action required.

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

1. MUST: bash scripts/extract_tf_info_wrapper.sh main.tf
2. MUST: Context7 lookup for each provider detected
3. MUST: Read references/security_checklist.md
4. MUST: Read references/best_practices.md
5. RUN: terraform fmt -check main.tf
6. RUN: terraform init (if needed) && terraform validate
7. MUST: bash scripts/run_checkov.sh -f json main.tf
8. Report issues with remediation from references
9. If custom providers: WebSearch for documentation

Example 2: Full Module Validation

1. Identify all .tf files in directory
2. MUST: bash scripts/extract_tf_info_wrapper.sh ./modules/vpc/
3. MUST: Context7 lookup for ALL providers
4. MUST: Read references/security_checklist.md
5. MUST: Read references/best_practices.md
6. RUN: terraform fmt -recursive
7. RUN: tflint --recursive (or note as skipped if unavailable)
8. RUN: terraform init && terraform validate
9. MUST: bash scripts/run_checkov.sh ./modules/vpc/
10. Analyze findings against security_checklist.md
11. Validate structure against best_practices.md
12. Provide comprehensive report with references

Example 3: Production Dry-Run

1. Verify terraform initialized
2. MUST: Read references/security_checklist.md (production focus)
3. RUN: terraform plan -var-file="production.tfvars"
4. Analyze for unexpected changes
5. Highlight create/modify/destroy operations
6. Flag security concerns (compare with security_checklist.md)
7. Recommend whether safe to apply

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.

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

Terraform Validator