Jon Chery
7585c828f0
9 requirements implemented across presentation decks and project docs: 1. DX closing slide: added 'Infrastructure as a utility, not a craft' bullet to convey the full vision (infrastructure consumed, not maintained; platform compounds value over time). 2. PW Problem slide: 'moving a merged change' → 'promoting a change'. 3. PW Problem slide: added 'Red tape' and 'Scalability without increasing headcount' bullets (4 frictions, not 2). 4. PW Roadmap slide: redesigned with side-by-side HTML table layout (Testing | Planned), 16px font, no overflow. 5. PW deck: added new slide 'What This Platform Is — and Isn't' after North Star (sovereign boundary, infrastructure as utility, 4 anti-goals). PW deck now 16 slides (was 15). 6. Maturity nomenclature: 'Available today'/'shipped' → 'Testing' across both decks + source markdown. New .testing badge (blue/teal #DBEAFE). Roadmap title: 'Testing vs. Planned'. The platform has 0 consumer adoption — 'shipped' was inaccurate. 7. Global: 'substrate' → 'engine' across entire project (88 matches, 30+ files including .ciagent/, docs/, modules/, adapters/, schemas/, code). 8. Presentation files only: 'forge' → 'VCS' / 'version control system' (6 occurrences in 4 files). 'forge' retained in all technical docs and code as the industry-standard term. 9. New .agentic badge (purple/violet #EDE9FE) appended to agentic features in both decks: confidence signal, autonomous dev, pattern recognition, dynamic module creation, citizen developer surface, auto-promotion. Also: Change Request ID format changed from 'CR-2026-001' to 'CHG0678912' across presentation files, consumer guide, and test fixtures. HTML re-rendered. PPTX rendered for release upload. ---ci--- phase: 48 milestone: v1.9 status: complete requirements: covered: [] partial: [] ---/ci---
65 lines
3.4 KiB
Markdown
65 lines
3.4 KiB
Markdown
# 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. |