Skip to main content

IaC-Guard-V

PyPI Python compatibility License DOI arXiv

Paper

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

Accepted as a regular paper at QRS 2026.

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.

Version 1.0.2 adds qualified Checkov profiles and shared installation support.

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.2'
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

Native or contract result Meaning
SATISFIED The selected mechanical property is proven over the protected evidence.
VIOLATED The protected evidence proves the selected property false.
NOT_EVALUATED Required evidence is missing, ambiguous, incomplete, or not applicable.
UNSUPPORTED The request is outside the declared supported semantics.
ERROR Evaluation could not complete safely.

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

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 executables are not bundled in the installable wheel or sdist. Historical research/replay corpora in the source repository retain pinned tool artifacts for reproducibility; see the a8 Helm provenance qualification. Third-party tools retain their own licenses and trademarks.

Metadata

Release files for iac-guard-v 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for iac-guard-v 1.0.2
File Size Uploaded Provenance Actions
iac_guard_v-1.0.2.tar.gz 491.1 kB With provenance Details for iac_guard_v-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for iac-guard-v 1.0.2
File Interpreter ABI Platform Actions
iac_guard_v-1.0.2-py3-none-any.whl Python 3 none any Details for iac_guard_v-1.0.2-py3-none-any.whl

Total release size: 976.5 kB

Release files / iac_guard_v-1.0.2.tar.gz

Download URL iac_guard_v-1.0.2.tar.gz
Size 491.1 kB
Tags Source
SHA-256 checksum
How to use checksums
97e4a7a5a145766bacbc7f6ef0f58b25f3547cb8c7fc48c60c555285bf1a91d5
BLAKE2b-256 checksum
How to use checksums
0477b99eedbe2b366ff642217bbe1a671fda462992a193a21c251762974814ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Release files / iac_guard_v-1.0.2-py3-none-any.whl

Download URL iac_guard_v-1.0.2-py3-none-any.whl
Size 485.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a3d722c116dd95e1f9039ae03619789a542fa1d67573787d271c4030814ab3c8
BLAKE2b-256 checksum
How to use checksums
493ff1a01bc14d0d6acd5053b1350559135cd7f1bdd6b96d64015fe4a81e42f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Security for iac-guard-v 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for iac_guard_v-1.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page