# ACDL 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.