Jon Chery
3562f6f771
---ci--- project: acdl phase: 36 milestone: v1.8 status: execute ---/ci--- - schemas/README.md: how to write schemas, wire into platform, test in CI, dependencies, existing catalog, adding a new schema. - pipelines/README.md: how to write pipeline contracts, wire into workflows, test, dependencies, existing catalog, adding a new pipeline. - adapters/README.md: how to write adapters (Terraform + policy patterns), wire into platform, test, dependencies, existing catalog, adding a new adapter. - tests/test_docs_coverage.py: 6 tests validating all 3 READMEs exist with required sections. Tests: +6 (344 -> 350). All pass.
65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# ACDL Adapters
|
|
|
|
## Overview
|
|
|
|
Adapters translate the substrate-agnostic Target Stack IR to substrate-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. |