continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity
Files
016068fd4614a91a52c629a7ad6f5fd18654022e
acdl/adapters/README.md
T
Jon Chery 7585c828f0
acdl-ci / Lint (push) Successful in 7s
Details
acdl-ci / Test (push) Successful in 23s
Details
acdl-ci / Platform check-only (offline) (push) Successful in 8s
Details
docs(P48): vision gaps + badge system + substrate→engine + CR format + agentic tags 
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---
2026-07-23 14:58:29 +00:00

3.4 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink