IaC-Guard-V

Verify that an infrastructure-as-code security fix actually fixed the intended finding without hiding evidence, deleting the target, or introducing a regression.

IaC-Guard-V works with changes written by people, AI coding agents, and remediation tools. It binds scanner evidence to the exact before/after files and resources, then fails closed when the evidence is incomplete or unverifiable.

Status: 0.1.0a3 technical alpha · Checkov-focused · trusted local input only. The hardened hostile-input container and GitHub Action are not released.

Why IaC-Guard-V?

A scanner can say, “this check passes now.” IaC-Guard-V asks the questions needed to trust that conclusion:

• Was this exact finding present before?
• Is the candidate evidence bound to the same file and resource?
• Did the finding actually become a passing evaluation?
• Was the target deleted, renamed, suppressed, or replaced?
• Did another finding or destructive change appear?
• Did the scanner, ruleset, parser, and coverage remain trustworthy?

Uncertainty is reported as INCONCLUSIVE, never as success.

Install and try it

Install the public package and run the deterministic offline demo:

python -m pip install iac-guard-v==0.1.0a3
iac-guard --version
iac-guard demo

IaC-Guard-V offline demo (illustrative; not verification evidence)
VERIFIED     target FIXED; scanner integrity PASS; policy VERIFIED; exit 0
FAILED       target STILL_PRESENT; policy FAILED; exit 1
SUPPRESSED   suppression visible; policy FAILED; exit 1
INCONCLUSIVE scanner or coverage evidence unavailable; exit 3

The offline demo needs neither Checkov nor Docker. It explains the result model but does not create verification evidence.

Verify a real change

Real Checkov verification uses separate protected product and scanner environments. Follow the tested real-verification installation, then run:

.venv-iac-guard/bin/iac-guard verify \
  --before ./before \
  --after ./after \
  --all-baseline-findings \
  --framework terraform \
  --local-trusted \
  --checkov-executable "$PWD/.venv-checkov330/bin/checkov" \
  --output ./iac-guard-report.json

A successful target-scoped repair looks like:

IaC-Guard-V: VERIFIED
exit_code: 0
target: CKV_AWS_53 aws_s3_bucket_public_access_block.example: FIXED
scanner integrity: PASS
regressions: none
policy: VERIFIED

Use an exact selector when you want one finding or when a resource occurs in more than one file:

.venv-iac-guard/bin/iac-guard verify \
  --before ./before \
  --after ./after \
  --target CKV_AWS_53=aws_s3_bucket_public_access_block.example \
  --framework terraform \
  --local-trusted \
  --checkov-executable "$PWD/.venv-checkov330/bin/checkov" \
  --output ./iac-guard-report.json

Real verification may remain quiet for several minutes while Checkov runs and the evidence is captured and validated. The validated conclusion is printed only after the evidence is complete.

Real-world example

IaC-Guard-V independently evaluated the privilege-hardening portion of Coder demo-env-templates PR #180:

Scanner integrity, Terraform parsing, and target-scoped regression gates passed, producing VERIFIED with exit 0. This is target-scoped evidence, not a whole-PR certification. See the immutable reproduction and report.

Main commands

Git-aware verification does not modify the current checkout, index, branch, or worktree:

.venv-iac-guard/bin/iac-guard pr \
  --repository . \
  --base-ref origin/main \
  --head-ref HEAD \
  --all-baseline-findings \
  --changed-only \
  --framework terraform \
  --local-trusted \
  --checkov-executable "$PWD/.venv-checkov330/bin/checkov" \
  --format sarif \
  --output ./iac-guard.sarif

Advanced pinned configuration, lock records, source builds, macOS uv setup, and the source-independent real demo are documented in Advanced installation and workflows.

Verdicts and exit codes

Supported scope

The supported path verifies Terraform and Kubernetes-related changes with the locked Checkov 3.3.0 environment and emits validated JSON, console, SARIF, Markdown, or JUnit reports. It includes bounded, fail-closed evidence for supported Checkov CKV2 graph findings. Native execution is reduced-isolation and must be used only with operator-controlled input.

0.1.0a2 extended the closed report-v1 schema with optional graph evidence and inventory-completion data. 0.1.0a3 adds an optional parsed file-coverage category so resource-free Terraform support files remain byte-bound and parser-governed without requiring a scanner resource identity. Consumers using a vendored older schema must update to the schema shipped with 0.1.0a3. Older non-graph reports remain valid.

KICS, Trivy, OpenTofu, kubeconform, TFLint, multi-scanner consensus, Helm materialization, and candidate-only new-IaC review remain experimental, advisory, or future work. They cannot silently change the final verdict.

See Supported scope and limitations for exact boundaries and Security model for the fail-closed trust architecture.

Documentation

• Advanced installation and workflows
• Supported scope and limitations
• Security model
• Example walkthrough
• Security policy
• Contributing
• Roadmap
• Changelog

Research snapshot

IaC-Guard-V grew from a QRS 2026 study of infrastructure-as-code repair verification. The frozen research artifact is historical evidence, not the current product. No benchmark inference or model-provider call occurs during product verification.

See RESEARCH_SNAPSHOT.md for the frozen manifest, replay contract, limitations, and offline reproduction. The pre-peer-review manuscript is awaiting a public arXiv identifier; the Springer Version of Record and DOI will be linked when available. No placeholder publication link is published.

Contributing, citation, and license

Small, test-backed documentation, compatibility, fixture, and adapter contributions are welcome. Start with CONTRIBUTING.md.

Citation metadata is in CITATION.cff. IaC-Guard-V is licensed under the Apache License 2.0. Third-party tools are not bundled and retain their own licences and trademarks.