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

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__get-library-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)
   ├─> 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. 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 by creating a temporary virtual environment if needed. The venv is automatically cleaned up on exit.

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__get-library-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__get-library-docs(context7CompatibleLibraryID, topic="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	Line Reference
`CKV_AWS_24` (SSH open)	"Overly Permissive Security Groups"	Lines 66-110
`CKV_AWS_260` (HTTP open)	"Overly Permissive Security Groups"	Lines 66-110
`CKV_AWS_16` (RDS encryption)	"Encryption at Rest"	Lines 141-175
`CKV_AWS_17` (RDS public)	"RDS Databases"	Lines 356-366
`CKV_AWS_130` (public subnet)	"Network Security"	Lines 62-140
`CKV_AWS_53-56` (S3 public access)	"Public S3 Buckets"	Lines 112-139
`CKV_AWS_*` (IAM)	"IAM Security"	Lines 217-308
`CKV_AWS_79` (IMDSv1)	"EC2/EKS Security"	Lines 382-389
Hardcoded passwords	"Hardcoded Credentials"	Lines 8-45
Sensitive outputs	"Sensitive Output Exposure"	Lines 47-61

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]" (lines X-Y)

**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" (lines 66-110)

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

```bash
# 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
a temporary venv. No user action required.

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

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

terraform-validator

Terraform Validator

⚠️ Critical Requirements Checklist