acdl/adapters

Nova Adapters

Overview

Adapters translate the engine-agnostic Target Stack IR to engine-specific formats. The Terraform adapter is the primary adapter (IR → HCL). Policy adapters translate security tool output into normalized PolicyCheckResult records that the confidence signal consumes in an engine-agnostic way.

Existing Adapters

Adapter	Path	Input	Output	Purpose
Terraform adapter	adapters/terraform/adapter.py	Stack instance JSON	Terraform HCL (main.tf, terraform.tf, providers.tf)	Compiles IR to Terraform
Checkov adapter	adapters/terraform/policy/checkov_adapter.py	Checkov JSON	PolicyCheckResult records	Translates Checkov results
Wiz adapter	adapters/wiz/wiz_adapter.py	Wiz API issues JSON	PolicyCheckResult records	Translates Wiz security findings
Kyverno adapter	adapters/kyverno/kyverno_adapter.py	Kyverno PolicyReport JSON	PolicyCheckResult records	K8s-native policy translation

How to Write an Adapter

Terraform Adapter Extension

1. Add a stack type → Terraform type mapping to TYPE_MAP.
2. Add non-identity input mappings to INPUT_MAP.
3. Add non-identity output mappings to OUTPUT_MAP.
4. Add a specialized _emit_resource branch if the resource needs nested blocks (e.g. inline policies, rule sets).

Policy Adapter Pattern

1. Define SEVERITY_MAP and RESULT_MAP dicts that translate the engine's native severity/result vocabulary to the PolicyCheckResult enums.
2. Implement _to_pcr(raw_record, contract_id) → PolicyCheckResult dict.
3. Implement adapt(input_path, contract_id) → list of PolicyCheckResult dicts.
4. Implement is_configured() → bool (env var check) so the platform can skip the adapter when credentials are absent.

How to Wire an Adapter

• Terraform adapter — invoked by scripts/run_platform.sh Step 3 (terraform-plan).
• Checkov adapter — invoked by scripts/run_platform.sh Step 5 (checkov).
• Wiz / Kyverno adapters — optional Steps 5b/5c, run only when the relevant env vars are set.
• All policy adapters output records that are validated against schemas/policy_check_result.schema.json.

Dependencies

• jsonschema, pyyaml — used by all adapters for loading and validating inputs.
• boto3 — used by the Wiz adapter for AWS API access.
• checkov — used by the Checkov adapter to run policy scans.
• No external deps for the Terraform adapter (pure Python).

How to Test Adapters

• tests/test_adapter.py — Terraform adapter (TYPE_MAP, resource emission, refs, outputs).
• tests/test_checkov_adapter.py — Checkov adapter.
• tests/test_wiz_adapter.py — Wiz adapter.
• tests/test_kyverno_adapter.py — Kyverno adapter.
• All adapter tests load fixtures from tests/fixtures/ and use moto for AWS mocking.

Where to Write Tests

• tests/test_<adapter_name>.py paired with tests/fixtures/<adapter>_fixture.json.

Adding a New Adapter

1. Create adapters/<name>/<name>_adapter.py.
2. Implement adapt() and (for policy adapters) is_configured().
3. Add the adapter's engine name to the engine enum in schemas/policy_check_result.schema.json if it is a policy adapter.
4. Write a test (tests/test_<name>_adapter.py) plus a fixture (tests/fixtures/<name>_fixture.json).
5. Add it to scripts/run_platform.sh if it is invoked at runtime.
6. Update this README.