acdl/adapters/README.md

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
kyverno-json engine	adapters/kyverno-json/kyverno_json_engine.py	Any JSON/YAML payload	PolicyCheckResult records	v1.25 primary policy engine (swappable via PolicyEngine protocol)

Policy Engine Protocol (v1.25)

The core/policy_engine.py module defines the swap boundary between Nova and its policy engines. A PolicyEngine Python Protocol (PEP 544) with three members (name, is_configured(), evaluate()) is the contract; a PolicyEngineRegistry selects the active engine from config.json's policy.engine key. The confidence signal and pipeline never import an engine directly — they go through the registry.

Implementations:

• KyvernoJsonEngine (adapters/kyverno-json/) — shells to the kj CLI; the v1.25 default.
• NullEngine (core/policy_engine.py) — fallback when the policy key is absent (emits SKIPPED).
• Future: OpaEngine — implements the same protocol, shells to opa eval. The OPA-equivalent surface is documented in .ciagent/RESEARCH.md §4.2.

How to add a new engine:

1. Create adapters/<name>/<name>_engine.py implementing the PolicyEngine protocol (name, is_configured(), evaluate()).
2. evaluate() returns list[dict] where each dict conforms to schemas/policy_check_result.schema.json.
3. Register the engine in core/policy_engine.py's _autoload_* function (or call register(name, factory) at startup).
4. Set config.json.policy.engine to the engine's name.
5. Add the engine to the engine enum in schemas/policy_check_result.schema.json if it needs a distinct enum value (v1.25 reuses "kyverno" — see D-116).

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.