terraform-validator

# 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 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 1. **Explicit Providers:** Listed in `required_providers` block (from extract_tf_info_wrapper.sh output) 2. **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: ```json { "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 ```bash # 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](https://github.com/terraform-linters/tflint/blob/master/docs/user-guide/plugins.md) for plugin setup. ### Validate Configuration ```bash # Initialize (downloads providers and modules) terraform init # Validate syntax terraform validate # Validate with JSON output terraform validate -json ``` ### Security Scanning **MUST use wrapper script:** ```bash # 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 ```markdown ### Security Issue: [Check ID]