Terraform / OpenTofu Evidence Adapter — Adapter Validation Suite
Terraform / OpenTofu Evidence Adapter — Adapter Validation Suite
Status: active · Class: modernization · Mission: integration · Phase: phase-1
Canon source: canon/modernization-registry.yaml (propagated by uiao/tools/sync_canon.py).
The YAML frontmatter and this banner are regenerated from canon on every sync. Do not hand-edit. Author new material only below the ## Overview heading.
This document is the first active instantiation of the UIAO_121 Adapter Conformance Test Plan and the UIAO_123 Adapter Integration Test Plan for a passing-tier-1 adapter. Roadmap §2.6.
The adapter clears the conformance gate today: 30 / 30 conformance criteria PASS, 55 unit + behavioral tests green, and the adapter is wired into the UIAO_100 scheduler with end-to-end OSCAL SAR / POA&M / SSP coverage. Phase 4 acceptance against a live cloud backend is gated on real vendor credentials (deferred).
Overview
This Adapter Validation Suite documents the testing methodology, conformance criteria, and pass/fail evidence for the Terraform / OpenTofu Evidence Adapter. The adapter has been validated against realistic fixture data (v4 state files, plan JSON, HCL configurations) and proven end-to-end through the OSCAL SAR pipeline.
Test coverage: 55 tests (37 type-contract + 18 behavioral against fixtures). 7 end-to-end OSCAL pipeline tests. 30/30 conformance criteria PASS.
Scope
Target surfaces / subsystems: terraform-state, terraform-plan, hcl-configuration
Validated capabilities: State extraction, plan consumption, HCL parsing, three-way drift detection, evidence bundling, OSCAL SAR generation. Fixture files: terraform.tfstate (5 resources, 2 providers), terraform-plan.json (4 changes), example.tf (3 resource blocks with variables). NOT validated: Real S3/TFC backend auth, terraform CLI invocation, live system drift comparison.
Controls
NIST SP 800-53 Rev 5 controls this adapter supports: CM-2, CM-3, CM-6, CM-8, CA-7.
| Control | Adapter role | Notes |
|---|---|---|
| CM-2 Baseline Configuration | primary | The adapter’s extract_terraform_state + parse_hcl_config together establish the canonical configuration baseline (state file ↔︎ HCL declarations). The output terraform-claim-manifest.json carries the per-resource baseline as object-keyed claims. |
| CM-3 Configuration Change Control | primary | consume_terraform_plan ingests terraform plan -json output and emits a structured DriftReport keyed by resource action (create / update / destroy). This is the change-control surface for Terraform-managed infrastructure. |
| CM-6 Configuration Settings | supporting | The HCL parser surfaces variable + locals scopes; baseline configuration settings are emitted as part of the per-resource claim, but vendor-recommended baselines (e.g., CIS) are out-of-scope. |
| CM-8 System Component Inventory | supporting | Resource inventory derives from the state file. This is a snapshot, not a continuous discovery — change events only land via plan dispatch, not via a polling loop. |
| CA-7 Continuous Monitoring | evidence-only | Three-way drift detection (live ↔︎ state ↔︎ HCL) produces evidence consumed by UIAO_113 Evidence Graph; the adapter does not itself constitute the monitoring program. |
All five controls are implemented and CI-gated. No NEW (Proposed) flags.
Operational profile
| Field | Value |
|---|---|
| Runtime | python-3.12 |
| Runtime pin | TBD |
| Runner class | github-hosted |
| Tenancy | per-customer |
| Evidence class | baseline |
| Retention | 3 year(s) |
Canon invariants
gcc-boundary: gcc-moderatessot-mutation: nevercertificate-anchored: trueobject-identity-only: true
Notes from canon
Status transitions reserved → active when the adapter ships in uiao (separate PR gated on this registry entry landing, per uiao/.claude/rules/canon-consumer.md). Proposed adapter surface: extract_terraform_state, parse_hcl_config, consume_terraform_plan, detect_terraform_drift, generate_terraform_evidence — layered on the seven canonical domains of DatabaseAdapterBase.
References
- UIAO-CANON-003
- https://www.terraform.io
- https://opentofu.org
Generated by uiao/tools/sync_canon.py. See uiao/ARCHITECTURE.md §4 for the cross-repo sync contract. See uiao-docs/_quarto.yml for rendering configuration.
Conformance Matrix
Per uiao/canon/specs/adapter-conformance-test-plan-template.md v1.0. Adapter: terraform · Class: modernization · Mission: integration · Tier: T1
| Domain | Criterion | Status |
|---|---|---|
| 2.1.1 | connect() returns ConnectionProvenance | PASS |
| 2.1.2 | identity contains adapter-specific identifier | PASS |
| 2.1.3 | endpoint matches configured backend | PASS |
| 2.1.4 | auth_method reflects auth mechanism | PASS |
| 2.1.5 | timestamp is UTC | PASS |
| 2.2.1 | discover_schema() returns SchemaMappingObject | PASS |
| 2.2.2 | vendor_schema has adapter-relevant fields | PASS |
| 2.2.3 | canonical_schema has UIAO identity pattern | PASS |
| 2.2.4 | unmapped_fields is non-empty | PASS |
| 2.2.5 | version_hash is deterministic | PASS |
| 2.3.1 | execute_query() returns QueryProvenance | PASS |
| 2.3.2 | vendor_query has adapter-native syntax | PASS |
| 2.3.3 | execution_plan_hash is deterministic | PASS |
| 2.4.1 | normalize([]) returns empty ClaimSet | PASS |
| 2.4.2 | normalize([one]) produces 1 ClaimObject | PASS |
| 2.4.3 | claim_id follows adapter:… pattern | PASS |
| 2.4.4 | source == ADAPTER_ID | PASS |
| 2.4.5 | provenance_hash non-empty, deterministic | PASS |
| 2.4.6 | multiple records produce unique claim_ids | PASS |
| 2.5.1 | detect_drift() returns DriftReport | PASS |
| 2.5.2 | drift_type has adapter-specific prefix | PASS |
| 2.5.3 | details contains adapter key | PASS |
| 2.6.1 | collect_evidence() returns EvidenceObject | PASS |
| 2.6.2 | ksi_id preserved | PASS |
| 2.6.3 | source == ADAPTER_ID | PASS |
| 2.6.4 | provenance dict non-empty | PASS |
| 2.7.1 | collect_and_align() returns dict | PASS |
| 2.7.2 | adapter_id matches ADAPTER_ID | PASS |
| 2.7.3 | vendor field non-empty | PASS |
| 2.7.4 | metadata has last_collected timestamp | PASS |
| 4.1 | ADAPTER_ID matches canon registry id | PASS |
| 4.2 | registered in init.py all | PASS |
Extension Methods
| Method | Status | Notes |
|---|---|---|
| (adapter-specific methods) | IMPLEMENTED | All extension methods have real implementations (zero stubs remaining) |
Matrix updated 2026-04-16. All extension methods implemented, zero stubs. 330/330 conformance CI-gated.
Integration Test Plan
Per uiao/canon/specs/adapter-integration-test-plan.md v1.0.
Vendor API: Local file parsing (tfstate/plan/HCL) Authentication: File system access Fixture files: terraform.tfstate, terraform-plan.json, example.tf Runner class: github-hosted Controls: CM-2, CM-3, CM-6, CM-8, CA-7
Phase 4: Acceptance Test Cases
| # | Test | Input | Expected Output |
|---|---|---|---|
| A1 | Parse real state file | Production .tfstate from S3 | ClaimSet with all managed resources |
| A2 | Parse real plan output | terraform plan -json output |
DriftReport with create/update/delete actions |
| A3 | Parse real HCL config | .tf files with modules + variables | ClaimSet matching state shape |
| A4 | Three-way drift | Live + state + HCL | DriftReport identifying misalignments |
Current Phase Status
| Phase | Status | Evidence |
|---|---|---|
| 1. Unit | PASS | 30/30 conformance + behavioral tests |
| 2. Integration | PASS | OSCAL SAR/POA&M/SSP pipeline proven |
| 3. System | PASS | CI-gated (adapter-conformance.yml) |
| 4. Acceptance | PENDING | Requires real vendor credentials |
| 5. Production | PENDING | Requires Phase 4 + runner deployment |