IaC-Guard-V

Paper

IaC-Guard-V: A Verification Framework for LLM-Generated Infrastructure-as-Code Repairs

Accepted as a regular paper at QRS 2026.

• Preprint: arXiv:2609.28488
• Artifact: this repository
• Software archive: Zenodo concept DOI 10.5281/zenodo.22088272; v1.0.0 DOI 10.5281/zenodo.22926372

IaC-Guard-V is a fail-closed verifier for declared infrastructure invariants over protected, deterministically materialized infrastructure as code. Version 1.0 supports an exact set of 18 native properties. It does not claim universal IaC correctness, deployment safety, live-cluster behavior, or equivalence among security scanners.

The verifier is offline in native-property and contract modes. It does not call model providers, cloud APIs, or a Kubernetes cluster. Missing, ambiguous, unsupported, or incomplete evidence never becomes success.

Version 1.0.1 corrects Git tree ancestor validation; see the maintenance release notes.

Install

IaC-Guard-V 1.0 supports Python 3.10, 3.11, 3.12, and 3.13. Python 3.14 is not in the 1.0 support matrix.

python -m pip install 'iac-guard-v==1.0.1'
iac-guard --version
iac-guard doctor --mode native --format json
iac-guard properties list

First Kubernetes result

The packaged quickstart checks whether a rendered Deployment is selected by a NetworkPolicy. Copy the examples/quickstart/kubernetes/satisfied directory, then run:

python -m iac_guard_v.native_properties \
  --config examples/quickstart/kubernetes/satisfied/native-request.json \
  --format json \
  --output kubernetes-report.json

The result is SATISFIED. The adjacent violated and not-evaluated examples show a definite failed predicate and an unresolved named-port relationship:

python -m iac_guard_v.native_properties \
  --config examples/quickstart/kubernetes/violated/native-request.json \
  --format console
python -m iac_guard_v.native_properties \
  --config examples/quickstart/kubernetes/not-evaluated/native-request.json \
  --format console

Non-success is intentional. The native module returns 0 for all satisfied, 1 for a violation, 3 for not evaluated or unsupported, 4 for an evaluation error, and 2 for an invalid invocation. Contract commands use their separately frozen 0, 10, 11, 12, 20, and 21 mapping. Do not translate uncertainty into success.

First Terraform result

The Terraform quickstart checks one exact source-local reference. It does not run terraform init, evaluate providers, resolve remote modules, or infer a plan.

python -m iac_guard_v.native_properties \
  --config examples/quickstart/terraform/native-request.json \
  --format json \
  --output terraform-report.json

OpenTofu uses the distinct opentofu_source artifact class and IACGV_OPENTOFU_REFERENCE_RESOLVES_V1, including the documented .tofu and JSON precedence rules. Terraform V1 remains .tf-only.

Declared contracts

Projects can place a contract at .iac-guard-v/contracts.yaml or supply one explicitly. Version 1.0 accepts both the existing iac-guard-v.io/v1alpha1 form and the stable iac-guard-v.io/v1 form. Existing v1alpha1 consumers do not need to rewrite contracts.

iac-guard contract lint --contract .iac-guard-v/contracts.yaml
iac-guard contract plan --contract .iac-guard-v/contracts.yaml \
  --project-root . --contract-root rendered --format json
iac-guard verify --contract .iac-guard-v/contracts.yaml \
  --project-root . --contract-root rendered --format json \
  --output iac-guard-contract-report.json
iac-guard explain iac-guard-contract-report.json

Contract provenance is not inferred from a successful result. Use PROJECT_AUTHORED only when repository evidence supports project-owned intent.

Result model

Scanner-based before/after repair verification retains its established VERIFIED, FAILED, and INCONCLUSIVE result model and exit codes. See Compatibility.

Scanner authority

Native properties independently adjudicate their declared semantics. Checkov 3.3.0 is authoritative only on reviewed property and target paths with complete affirmative evidence. Trivy and KICS are advisory by default. Empty or missing scanner output is never a pass, and scanners are never majority-voted. See Scanner authority.

CI example

This example is read-only, uses no secrets or cluster, and pins both Python and the package. Replace the render step and contract with project-owned inputs.

name: IaC relationship verification
on:
  pull_request:
permissions:
  contents: read
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
        with:
          python-version: "3.12"
      - run: python -m pip install --no-compile 'iac-guard-v==1.0.1'
      - run: iac-guard doctor --mode native --format json
      - run: iac-guard contract lint --contract .iac-guard-v/contracts.yaml
      - run: ./project-owned-deterministic-render-command
      - run: |
          iac-guard verify --contract .iac-guard-v/contracts.yaml \
            --project-root . --contract-root rendered --format json \
            --output iac-guard-contract-report.json
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
        if: always()
        with:
          name: iac-guard-report
          path: iac-guard-contract-report.json

Do not use pull_request_target to execute untrusted pull-request content. Local Helm, Kustomize, and native execution are reduced-isolation modes for operator-controlled input, not hostile-code sandboxes.

Stable support boundary

• Supported scope
• Security model
• Compatibility policy
• Native properties
• Scanner authority
• Support policy
• Migration from 0.1.0b1
• 1.0 release notes

More detailed materializer documentation remains in docs/. The frozen QRS research artifact is historical evidence and is not required to understand or use the product.

Citation and license

For the paper, cite arXiv:2609.28488. For the evolving software, use the Zenodo concept DOI; for the exact 1.0.0 archive, use the version DOI. Machine-readable 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 licenses and trademarks.