Skip to main content

IaC-Guard-V

This branch contains the unpublished 1.0.4 cancellation-fix candidate. Version-pinned index installation below applies after owner-approved publication; candidate validation installs the reviewed non-editable wheel directly.

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. Version 1.0.3 adds exactly Checkov 3.4.3 with Terraform CKV_AWS_3; all other properties on that version remain unqualified. Existing 3.3.0–3.3.30 profiles are unchanged.

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

Cooperative cancellation

The 1.0.4 candidate CLI handles SIGINT and SIGTERM with bounded cleanup of its owned scanner group before returning nonzero. The runner requires default SIGCHLD and exclusive ownership of its child waits. Linux and macOS are exercised; native Windows descendant cleanup is not qualified. SIGKILL, a crashed/unresponsive verifier, and machine failure cannot promise cooperative cleanup. A report must always be interpreted with its process exit; a report written just before an interruption is not an accepted result. Hook integrations quarantine interrupted reports in their own invocation directories.

Metadata

Release files for iac-guard-v 1.0.4

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.4
File Size Uploaded Provenance Actions
iac_guard_v-1.0.4.tar.gz 496.4 kB With provenance Details for iac_guard_v-1.0.4.tar.gz

Built distribution (wheel)

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

Total release size: 985.3 kB

Release files / iac_guard_v-1.0.4.tar.gz

Download URL iac_guard_v-1.0.4.tar.gz
Size 496.4 kB
Tags Source
SHA-256 checksum
How to use checksums
3c1e37e4206acdb74c4aad5f0ac266cb9843d6fc1f68d4d9443e810c27743a06
BLAKE2b-256 checksum
How to use checksums
c407c26f21acd35da352fe4b5c4c61b2101e46ed9e3694b1675677156e7abd56
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 Nov 8, 2026.

Transparency log

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

Download URL iac_guard_v-1.0.4-py3-none-any.whl
Size 488.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6155ec76424b18b51d1d604ec7d161c963bc35ba3ea0500c6b251b695b4b8972
BLAKE2b-256 checksum
How to use checksums
d5f2fd7f2d7c86122ba73e32067d765503ec289ddb84f2d978bde8f390717ba0
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 Nov 8, 2026.

Transparency log

Security for iac-guard-v 1.0.4

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.4.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 Nov 8, 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