Motivation

Terraform scans previously treated local module calls as call-site blocks only. A rule could inspect a module block's inputs and map a subset of them back to expected resource attributes via get_module_equivalent_key, but the scanner never materialized the resources inside a local module with the caller's values. So a misconfiguration that only exists because of what the caller passed in was invisible to any rule that didn't carry a bespoke module-mapping branch.

This PR instantiates local modules during scans: it binds caller inputs to the module's variables (→ defaults → unknown), evaluates locals/functions/conditionals, recurses into nested local modules, and emits the resolved resources into the scan payload. Rules then run against real resources (e.g. aws_s3_bucket) with no module-awareness required.

Related Ticket: K9CODESEC-2306

Before / After

# main.tf (root)
module "logs" {
  source      = "./modules/bucket"
  bucket_name = "app-logs"
  acl         = "public-read"   # insecure, set by the caller
}

# modules/bucket/main.tf
variable "bucket_name" {}
variable "acl" { default = "private" }

resource "aws_s3_bucket" "this" {
  bucket = var.bucket_name
  acl    = var.acl
}

Before: the root saw the module "logs" call-site, and modules/bucket/main.tf was scanned standalone with acl = var.acl unresolved. The public ACL was only catchable if the S3 rule had a get_module_equivalent_key branch, most don't, so it was missed.

After: the module is instantiated with acl = "public-read", materialized as aws_s3_bucket.this, and the normal "S3 bucket must not be public" rule fires on the resolved value. The called body file is suppressed and the local call-site stripped, so there is exactly one finding.

Implementation

• New evaluator package pkg/parser/terraform/tfeval (module-instance tree: input binding, variable defaults, locals fixed-point, nested local modules with depth + cycle guards, output up-propagation).
• Engine wiring in pkg/engine/module_resolve.go + Inspect: instantiate local modules, inject synthetic resource documents, suppress called bodies, strip instantiated local call-sites.

Things reviewers should know

• Unknown values use a placeholder (__DD_TFEVAL_UNKNOWN__) so attribute keys stay present. This prevents MissingAttribute false-positives from treating an unresolved expression as absent. Trade-off: value-equality rules see the sentinel rather than a concrete value (i.e. this swaps potential MissingAttribute FPs for potential IncorrectValue FPs).
• Finding attribution shifts for local modules. Findings now report at the module's resource definition (file + line) with the call chain, not at the call site. This changes findingId, which matters for suppression and ticket continuity in hosted scans.
• Dedup model: called module body files are suppressed; only instantiated local call-sites are stripped from root docs; remote/registry call-sites are left intact so existing Rego branches still fire; uncalled modules are still scanned standalone. Call-sites are only stripped when the module contributed synthetic docs (never remove coverage without a replacement).
• Resilience: evaluation is wrapped in recover() (a bad module logs and is skipped, scan continues); if every root fails to evaluate, no suppression/stripping is applied.
• Root *.tfvars / *.auto.tfvars feed module inputs; root-module resources themselves are unchanged (still scanned via the standard converter).

Out of scope (follow-ups)

• Remote / registry modules: unchanged; still treated as call-site blocks. It will come in the future.
• count / for_each expansion to N>1: only the disable case (count = 0, for_each = {}) is handled; otherwise a block is materialized once, and count.index / each.key resolve to unknown. Incoming in the next PR.
• Cross-resource references (x = aws_y.z.id, data sources): resolve to unknown. Incoming in the next PR.
• Multiple calls to the same module directory / per-instance attribution: distinct instances can collapse to one synthetic doc (same defining file/line).
• Retiring get_module_equivalent_key: kept running in parallel; removal is a later PR once instantiated coverage is proven.

Followup ticket

Blast radius

All Terraform scans: local modules are evaluated and merged into the OPA payload. Remote and registry modules are unchanged.

Testing / QA

1. go test ./pkg/parser/terraform/tfeval/... ./pkg/engine/...
2. test-rules (authoritative): confirm no regressions and net-new coverage on local-module fixtures; watch the unknown-placeholder FP rate.
3. Scan a fixture that calls a local module and confirm findings target instantiated resources with caller-resolved attributes; confirm remote/registry module call-sites are unchanged and there are no duplicate findings (stripped call-site + instantiated resource).

I submit this contribution under the Apache-2.0 license.