Files

T

Jon Chery 59d837f6e7 fix(P03 W0.5): kyverno-json substrate works with real kj (engine + policies + install script)

The v1.25 kyverno-json engine adapter and policies were authored but never
validated against the real `kj` binary — the test suite
`pytest.skip("kj not installed")` when `kj` was absent, masking the bug.
With `kj` v0.0.3 now installed, the 3 failing-fixture tests
(stack-ir/plan-json/regression) showed 0 fails (all passed falsely). Root
causes (3 substrate bugs) and fixes:

1. ENGINE — bare-list output format. `kj scan --output json` emits a bare
   JSON LIST at the top level (NOT `{"results": [...]}`); each entry has
   `resource` + `results[].rules[]` with `violations[]` (fail) / `error`
   string (eval error) / neither (pass). The v1.25 `_translate` did
   `out.get("results", [])` on a dict → `out` is a list → returned `[]` →
   emitted a single KJ_NO_RESULTS pass PCR. Rewrote `_translate` to parse
   the real v0.0.3 nested shape (policy.metadata.name, rule.name,
   violations[].errors[].field/detail/value). Future-proofs to also accept
   the legacy dict shape. Preserves RESULT_MAP, severity-from-annotation,
   is_configured(), _skipped_not_configured, _error_pcr, the temp-file
   payload write, and the subprocess invocation.

2. ENGINE — `.json` policies not loaded by `kj`. The upstream loader
   (pkg/policy/load.go) uses fileinfo.IsYaml() which only matches
   `.yaml`/`.yml` — `.json` files are silently skipped (0 policies).
   Nova policies are authored as `.json` (TestPolicyFilesExist asserts the
   filenames). Added `_materialize_yaml_policy_dir`: mirrors the source
   tree to a temp dir, copying every `.json` policy to a `.yaml` twin
   (JSON is a valid YAML subset, verified against kj v0.0.3). Source
   `.json` files remain untouched.

3. POLICIES — `validate` wrapper + check syntax. Removed the `validate`
   wrapper from all 16 policies (kj v0.0.3 ignores `validate`-wrapped
   rules — `assert` goes directly under the rule). Fixed the check syntax:
   a check entry is `expression: expected_value` (e.g.
   `(regex_match(..., @)): true`), not `field: (expression)` (which
   compared a bool to nothing → "types not comparable"). For per-resource
   checks over stack-IR/plan-JSON, `~.resources` (descendant anchor) is
   required for per-element iteration; a plain path applies to the whole
   array. For type-scoped rules (s3/ebs encryption, iam/db/kms), the type
   guard is folded into the expression (`type == '...' && !<has-prop>`)
   so non-matching resources short-circuit to false. cap-013 dedup uses
   `max(map(&length(@), values(group_by(adapters, &@)))) == `1`` (no
   `duplicates` JMESPath fn exists). Preserved all policy metadata
   (apiVersion, kind, metadata.name, severity + title annotations) —
   TestPolicyValidity/TestPolicyFilesExist still pass.

INSTALL SCRIPT — the v1.25 `go install .../cmd/kj@latest` failed: the
`cmd/kj` path does not exist in v0.0.3 (upstream produces a binary named
`kyverno-json`). Fixed to `go install github.com/kyverno/kyverno-json@latest`
+ symlink `kyverno-json` → `kj` (GOBIN and /usr/local/bin fallbacks).
Idempotent: short-circuits when `kj` is already on PATH and working.

Verification: `which kj` → /usr/local/bin/kj; `kj version` → v0.0.3.
test_kyverno_json_engine + test_stack_ir_policies + test_plan_json_policies
+ test_meta_policies + test_regression_policies: 36 passed, 0 skips
(_require_kj no longer skips). Full suite (excluding pre-existing hang in
test_verify_regression_mode.py): 776 passed, 6 failed — all 6 failures are
pre-existing (confirmed by stashing this commit's diff and re-running);
the only in-scope-acceptable failure is
test_module_standards.py::test_all_l1_have_required_files (dynamodb
extension drift, data-engineer's later wave).

---ci---
project: acdl
phase: 3
milestone: v1.26
status: execute
wave: W0.5
---

2026-08-18 21:29:12 +00:00

kyverno

Merge milestone/v1.16-nova-simplification — v1.16 complete (Nova Simplification: 20-phase NFR sweep + final; tag v1.15.26)

2026-08-01 13:37:18 +00:00

kyverno-json

fix(P03 W0.5): kyverno-json substrate works with real kj (engine + policies + install script)

2026-08-18 21:29:12 +00:00

terraform

feat(P2): env-transition detect-and-destroy — REQ-282..287

2026-08-12 14:30:24 +00:00

wiz

feat(P4): pipeline hardening — Checkov before plan, Wiz-or-Checkov on plan (REQ-250)

2026-08-11 14:10:42 +00:00

.gitkeep

phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.1..T-6.4

2026-07-21 18:27:21 +00:00

README.md

feat(P4): regression-gate policies + docs (REQ-304..307)

2026-08-12 18:42:55 +00:00

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:

Create adapters/<name>/<name>_engine.py implementing the PolicyEngine protocol (name, is_configured(), evaluate()).
evaluate() returns list[dict] where each dict conforms to schemas/policy_check_result.schema.json.
Register the engine in core/policy_engine.py's _autoload_* function (or call register(name, factory) at startup).
Set config.json.policy.engine to the engine's name.
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

Add a stack type → Terraform type mapping to TYPE_MAP.
Add non-identity input mappings to INPUT_MAP.
Add non-identity output mappings to OUTPUT_MAP.
Add a specialized _emit_resource branch if the resource needs nested blocks (e.g. inline policies, rule sets).

Policy Adapter Pattern

Define SEVERITY_MAP and RESULT_MAP dicts that translate the engine's native severity/result vocabulary to the PolicyCheckResult enums.
Implement _to_pcr(raw_record, contract_id) → PolicyCheckResult dict.
Implement adapt(input_path, contract_id) → list of PolicyCheckResult dicts.
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

Create adapters/<name>/<name>_adapter.py.
Implement adapt() and (for policy adapters) is_configured().
Add the adapter's engine name to the engine enum in schemas/policy_check_result.schema.json if it is a policy adapter.
Write a test (tests/test_<name>_adapter.py) plus a fixture (tests/fixtures/<name>_fixture.json).
Add it to scripts/run_platform.sh if it is invoked at runtime.
Update this README.