Skip to main content

maf-sandbox-terraform

PyPI Python License

Experimental. Releases before 1.0 may change or remove APIs. Importing this package emits MafSandboxTerraformExperimentalWarning.

Validate Terraform or OpenTofu projects offline. Optional formatting tools return changed file contents for the model to save through host file tools.

Requires Python 3.12–3.14. The Python package does not include the Terraform or OpenTofu CLI.

pip install maf-sandbox-terraform

Attach the tools

from maf_sandbox_terraform import make_terraform_tools

tools = make_terraform_tools(
    router,
    file_store,
    "infrastructure-agent",
    context,
    engine="terraform",
    image="terraform-sandbox:local",
    formatting=False,
)

The host supplies a router, file store and CallerContext. It chooses engine="terraform" or engine="opentofu" and a matching image. With no configured backend the factory returns [].

Engine Validation tool Optional formatting tool
Terraform terraform_validate terraform_format
OpenTofu opentofu_validate opentofu_format

The model supplies files: list[str] and root_module: str = ".". It cannot select CLI flags, an image or an engine.

Build images using the image guide. The usage guide provides runnable examples and dependency preparation.

Inputs

Supply a complete manifest of configuration files, local modules and referenced text assets. Every name must appear in the caller's listing. Completeness checks cover only files that the host exposes there.

Terraform accepts .tf and .tf.json. OpenTofu also accepts .tofu and .tofu.json, using its native precedence rules. The root must contain recognized configuration. Upload names cannot traverse with ..; valid relative module references inside files are preserved.

State, plans, CLI credentials, plugin binaries and reserved directories are refused. Variable-value files (.tfvars, .tfvars.json) are staged when the manifest names them, and are never required beside the configuration. Inputs are text only, with limits of 64 files, 8 MiB per file and 32 MiB total.

The model chooses the manifest from the host's visible file listing. Expose variable files there only when their contents may enter tool results: engine diagnostics can quote values, and the optional formatter can return whole changed files. Closed egress and integrity labels do not redact secrets; the host controls file visibility and result confidentiality.

Validation

The fixed launcher runs these commands without interaction or terminal color:

  1. init -backend=false, using prepared modules and a filesystem provider mirror.
  2. validate -json, checking the verdict, diagnostic counts and exit status.
  3. fmt -check -recursive, reporting formatting separately.

A supplied root lock file is read-only during initialization. Without one, a generated lock exists only inside the disposable guest. No command writes back to the host store.

Initialization failure or malformed, inconsistent, truncated or oversized output means incomplete validation. Use the fixed completion and verdict to interpret a hidden report. Successful validation does not prove that a deployment will succeed.

Completed validation also returns a readable terraform_diagnostics JSON summary for either engine. Each entry pairs a fixed input reference such as files[0] with error or warning. Entries indicate presence, not counts; duplicates collapse and the 64-file input limit bounds the summary to 128 pairs. unattributed_diagnostics: true signals findings without a matching staged input. Hidden filenames, engine prose, expressions and source positions stay out of this summary.

Terraform and OpenTofu do not expose stable rule IDs in their validation JSON. The summary identifies where to inspect, but cannot identify the rule, explain the error or prescribe a repair. The verdict comes from the complete checked report, so an empty summary is not evidence of validity. See the summary contract.

Formatting

Set formatting=True to attach the separate formatting tool. It runs fmt -recursive -no-color without initialization or validation, so a base image without providers is sufficient.

The report maps store-relative paths to complete changed file contents. Unchanged files are omitted. Saving them is a separate host file-write call with the host's approval policy.

All changed files are returned together, or none are. CLI output and returned file bytes share a 128 KiB budget. The complete JSON report, including escaping and metadata, must also fit 128 KiB.

A timeout, formatter failure or overflow returns Formatting INCOMPLETE without partial text. Use a smaller complete manifest if possible. A single changed file over the limit cannot be returned. Hidden argument names also withhold file text and locations.

Execution and labels

The kind requires POSIX, EXEC, FILES_IN, at least container isolation, closed network access and a separate sandbox per call. Disposal is mandatory. There is no direct-download fallback for missing dependencies.

All phases share exec_timeout_seconds: 120 by default, finite and at most 600. Host execution adds five seconds for transport and cleanup. Cancellation waits for bounded execution before disposal.

Providers execute native code and may read other guest paths. Use a dedicated image without credentials, sensitive files or host mounts. This tool exposes no plan, apply, destroy, import or state operations.

Both tools use the SandboxResult contract. Core renders separate content items for completion, an optional verdict, trusted output, untrusted output and standing guidance. Trusted output holds the validation summary or fixed failure reasons. Validation exposes valid or invalid; formatting exposes changed or unchanged. An incomplete call reports completed=False, no verdict and no diagnostic summary.

Completion, declared verdicts, diagnostic summaries, fixed reasons and guidance remain readable while FIDES may hide engine reports, session exception details and formatted file contents. All items retain effective confidentiality; a summary never restores an already-untrusted conversation. Formatting-check details within a validation report remain untrusted. The host supplies confidentiality and later-tool policy. See the kind guide for the complete contract.

The random profile is live-verified with Terraform and OpenTofu on Linux amd64 Docker and ACAS using published wheels. See the kind guide's measurements for the tested versions and evidence. WSLC execution remains unverified. When the launcher changes, rebuild both base and prepared images; prepared-image receipts bind to its reader_sha256.

Metadata

Release files for maf-sandbox-terraform 0.9.0

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

Source distribution (sdist)

Source distribution for maf-sandbox-terraform 0.9.0
File Size Uploaded Provenance Actions
maf_sandbox_terraform-0.9.0.tar.gz 15.0 kB With provenance Details for maf_sandbox_terraform-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maf-sandbox-terraform 0.9.0
File Interpreter ABI Platform Actions
maf_sandbox_terraform-0.9.0-py3-none-any.whl Python 3 none any Details for maf_sandbox_terraform-0.9.0-py3-none-any.whl

Total release size: 32.4 kB

Release files / maf_sandbox_terraform-0.9.0.tar.gz

Download URL maf_sandbox_terraform-0.9.0.tar.gz
Size 15.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ba3a8ee8a7b3eb904f021cef652ddf2b716abe47a581a177b2d5bb2f88b0ff7f
BLAKE2b-256 checksum
How to use checksums
a75611e6f3108eaa43ad0f50e1b350d01560bb71b80deee54c0750f8aff02edb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 20, 2026.

Transparency log

Release files / maf_sandbox_terraform-0.9.0-py3-none-any.whl

Download URL maf_sandbox_terraform-0.9.0-py3-none-any.whl
Size 17.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
26fed3a5ec8e8c6586c50be679493b5a6d18ce766e23158a7e648df7c30e6b1a
BLAKE2b-256 checksum
How to use checksums
ccd506da716bcdbf44250815d52e026d157eb64b702bc759ddeeaa93cfe856ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 20, 2026.

Transparency log

Security for maf-sandbox-terraform 0.9.0

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 maf_sandbox_terraform-0.9.0.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 20, 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