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.0a10 technical alpha · declared intent contracts, native semantic verification, and reviewed Checkov-authoritative paths · 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.0a10
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 and local client-side Helm rendering. 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. 0.1.0a4 adds optional Helm materialization evidence. Consumers using a vendored older schema must update to the schema shipped with 0.1.0a4 before validating Helm reports. 0.1.0a5 adds a distinct candidate_acceptance result and multi-chart Helm-universe evidence. It uses SATISFIED, VIOLATED, or INCONCLUSIVE properties and never labels a head-only result FIXED. Its closed evidence distinguishes the complete governed inventory from scanner-primary addresses and the resources relevant to each requested property. Older repair reports retain their existing semantics. 0.1.0a6 adds protected Helm namespace provenance plus bounded action, tpl, and exactly resolvable dynamic include/template evidence. Unsupported expressions and unresolved scanner addressability remain fail-closed and INCONCLUSIVE. 0.1.0a7 corrects known cluster-scoped resource identity to model API-server namespace normalization while retaining any emitted metadata.namespace as governed evidence. Duplicate normalized identities and unresolved custom-resource scope remain fail-closed.

0.1.0a8 adds scanner-neutral protected-artifact, target, property-observation, and evidence contracts while retaining Checkov as the only authoritative scanner path. It also adds bounded Helm dependency aliases and nested local dependency closure, Helm-compatible dependency-version binding, equivalent duplicate named-template handling, bounded namespace-provenance improvements, and deterministic local Kustomize materialization. These are closed contracts: general Helm interpretation, remote dependency/resource resolution, lookup or other live-cluster state, and unsupported dynamic semantics are not supported and remain fail closed.

0.1.0a9 adds witness-first, scanner-independent native property contracts over the same protected deterministic artifacts. The bounded inventory covers Kubernetes identity and selectors, NetworkPolicy selection/isolation/closure, Service and port resolution, NetworkPolicy path composition, reviewed ServiceMonitor/PodMonitor composition, RBAC identity/scope relationships, and exact source-local Terraform references. Native results are SATISFIED, VIOLATED, NOT_EVALUATED, UNSUPPORTED, or ERROR; every result carries a mechanically validated witness. Mechanical property violations do not automatically establish project defects or runtime behavior.

0.1.0a10 adds declared infrastructure intent contracts over those immutable a9 properties. The one .iac-guard-v/contracts.yaml convention binds verifier-derived provenance, protected typed activation values, explicit include/exclude denominators, non-vacuous cardinality, responsibility metadata, exact compiled native requests, and witness-first aggregate results. Contract violations remain mechanical declared-intent results, not automatic project-defect or runtime claims.

KICS and Trivy remain advisory/future adapter work; OpenTofu, kubeconform, TFLint, and multi-scanner consensus remain experimental, advisory, or future work. Candidate acceptance is limited to explicitly selected properties under a complete protected universe; it is not a generic claim that newly introduced infrastructure is safe. These boundaries 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
• Helm materialization
• Kustomize materialization
• Candidate acceptance
• Native semantic properties
• Declared infrastructure intent contracts
• Example walkthrough
• Public reproduction packet guidance
• Security policy
• Contributing
• Roadmap
• Changelog

Cite IaC-Guard-V

For the evolving software project, cite the Concept DOI 10.5281/zenodo.22088272.

The current release is IaC-Guard-V 0.1.0a10. Its immutable GitHub, PyPI, artifact, and version-DOI identities are recorded in the public release record after all services agree. It remains part of the evolving-software Concept DOI record above.

Machine-readable citation metadata is available in CITATION.cff.

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.

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