feat(casan): establish assurance kernel and harden control plane
This commit is contained in:
thanhnv
@@ -0,0 +1,221 @@
|
||||
# Assurance Kernel and Control Plane Upgrade — Implementation Log
|
||||
|
||||
Date: 2026-08-02
|
||||
|
||||
## Executive implementation result
|
||||
|
||||
All seven P0 items and all five requested P1 items were implemented with
|
||||
targeted regression coverage. The native harness remains operational. The
|
||||
Assurance Kernel now has a versioned canonical contract, deterministic shared
|
||||
policy, a native adapter, an Agentic Bridge adapter and a 10-invariant
|
||||
cross-runtime conformance suite. The Control Plane packages in-process RS256
|
||||
identity verification and refuses unsafe network startup.
|
||||
|
||||
P2 was intentionally limited: taxonomy and runtime capability negotiation were
|
||||
implemented, but new H4/H5/H2 report dossiers were not represented as
|
||||
data-backed because the shared evidence-query migration was not safe to finish
|
||||
within this change.
|
||||
|
||||
## Verified pre-existing behavior
|
||||
|
||||
- H4 already blocked injection/secrets before model execution.
|
||||
- The agent bridge already denied sensitive pre-tool adapter failures in many
|
||||
paths and disclosed observed-only degradation.
|
||||
- The native harness already propagated command exit status; the misleading
|
||||
completion gap was primarily in Agentic Bridge finalize semantics, where a
|
||||
later `Stop(completed)` could obscure a failed tool.
|
||||
- Container isolation already implemented read-only root, no network,
|
||||
non-root execution, capability dropping and resource bounds.
|
||||
- Production preflight already checked live Vault/S3 prerequisites, and
|
||||
`sign-audit-head.sh` already refused local fallback for `CASAN_PROFILE=prod`.
|
||||
- H6 already had a data-backed report and operational test suite; other report
|
||||
dimensions remained `contract_ready`.
|
||||
- H5 strict signed approval, separation of duties and OIDC approval fixtures
|
||||
already existed.
|
||||
|
||||
## Verified gaps
|
||||
|
||||
- Agentic H2 returned allow when the gate script was absent.
|
||||
- Agentic registry enforcement defaulted off.
|
||||
- H5 risk followed text risk, allowing benign deployment text to avoid the
|
||||
inherent action floor.
|
||||
- Agentic telemetry and finalization did not model failed execution separately
|
||||
enough to prevent misleading successful completion.
|
||||
- `sandbox-run.sh` could silently fall back to weaker timeout/static behavior.
|
||||
- Control Plane identity trusted forwarded identity headers when a flag was set.
|
||||
- Production governance/certification did not uniformly require both external
|
||||
signing and immutable anchoring capabilities.
|
||||
- No stable canonical execution contract or two-runtime conformance suite
|
||||
existed.
|
||||
- H1–H7 categories were structurally ambiguous.
|
||||
|
||||
## Code changed in this task
|
||||
|
||||
### P0.1 — H2 missing-gate behavior
|
||||
|
||||
Selected implementation: `evaluate_h2_gate` returns a structured
|
||||
`PolicyDecision` with stable reason codes. Missing file, permission denial,
|
||||
timeout, malformed response and internal exception deny in enforce mode.
|
||||
Observe mode yields `observe_only`, degraded and non-certifiable evidence.
|
||||
|
||||
Proof: kernel unit tests and Agentic Bridge integration tests cover every error
|
||||
class and both modes.
|
||||
|
||||
Residual: external shell gates remain a runtime dependency; the change makes
|
||||
dependency failure honest and safe rather than eliminating it.
|
||||
|
||||
### P0.2 — registry defaults
|
||||
|
||||
Selected implementation: both side-effecting native and Agentic Bridge paths
|
||||
use shared configuration validation and default registry enforcement on.
|
||||
Development/test bypass is explicit, high-severity and non-certifiable;
|
||||
production bypass is invalid.
|
||||
|
||||
Proof: unit, bridge integration and legacy Agentic Bridge suites.
|
||||
|
||||
### P0.3 — action-class risk floors
|
||||
|
||||
Selected implementation: `config/action-classes.json` is the deterministic
|
||||
source. Effective risk is the maximum of five factors. H5 governance and both
|
||||
adapters consume it; high-impact actions require actor, approval and evidence.
|
||||
|
||||
Proof: benign deployment regression in unit, bridge and shell integration
|
||||
tests. Existing H5 strict approval remains 12/12.
|
||||
|
||||
### P0.4 — single-step failure semantics
|
||||
|
||||
Selected implementation: kernel failure-policy selection plus bridge
|
||||
post-tool/finalize changes. Execution failure, telemetry recording, assurance
|
||||
continuation and certification are separate. Production side-effect
|
||||
`record_only` is rejected. Native phase failure emits a failed canonical bundle
|
||||
and preserves the original non-zero exit.
|
||||
|
||||
Proof: all four policy values, invalid/production configuration, Agentic failed
|
||||
write and native exit-7 regressions.
|
||||
|
||||
### P0.5 — isolation fallback
|
||||
|
||||
Selected implementation: enforce/production chooses container isolation and
|
||||
denies when unavailable. Static fallback requires an explicit dev/test flag.
|
||||
Capability evidence discloses the actual backend. Production requires a
|
||||
digest-pinned image and rootless Docker.
|
||||
|
||||
Proof: unavailable-backend and explicit-development-fallback tests. Existing
|
||||
container escape tests are present but were skipped locally because Docker was
|
||||
unavailable.
|
||||
|
||||
### P0.6 — Control Plane identity
|
||||
|
||||
Selected implementation: typed `AuthProvider`, RS256 JWT verification,
|
||||
`VerifiedClaims`, safe scope checks, audit evidence, header overwrite and
|
||||
startup validation. Nginx passes only the access token after removing identity
|
||||
headers. Production preflight verifies the packaged boundary.
|
||||
|
||||
Proof: missing/invalid/expired/wrong-audience/wrong-issuer tests, valid RS256,
|
||||
header spoofing and production startup refusal. Backend has 57 passing tests.
|
||||
|
||||
Residual: mounted static public key requires coordinated restart for rotation;
|
||||
JWKS discovery/automatic rollover is not yet implemented.
|
||||
|
||||
### P0.7 — trust-root enforcement
|
||||
|
||||
Selected implementation: shared capability evaluation, governance enforcement,
|
||||
Vault signing, Object Lock anchoring and certification restrictions. Production
|
||||
local fallback is refused. Emergency override is critical, readiness-failing
|
||||
and non-certifiable.
|
||||
|
||||
Proof: unit, bridge, shell and production configuration tests.
|
||||
|
||||
Residual: real Vault/KMS and S3 are customer infrastructure and were not
|
||||
provisioned or contacted in this local run.
|
||||
|
||||
### P1 — contract and adapters
|
||||
|
||||
Selected implementation: JSON Schema `1.0.0`, Python builders/verifier,
|
||||
namespaced extensions, dual emission, native compatibility adapter and Agentic
|
||||
Bridge adapter. Evidence integrity and bidirectional claim links use one
|
||||
verifier. Delegation depth/cycles are validated.
|
||||
|
||||
Proof: 30 kernel/unit/conformance tests, including the exact 10 cross-runtime
|
||||
invariants and evidence tampering.
|
||||
|
||||
### P1 — H taxonomy
|
||||
|
||||
Selected implementation: separate typed namespaces for runtime controls,
|
||||
readiness checks, report dimensions and certification claims. Structured
|
||||
readiness, report and certification evidence now includes a category/type.
|
||||
Legacy `Hn` remains a display mapping only.
|
||||
|
||||
Proof: cross-category unit test and additive Control Plane report tests.
|
||||
|
||||
### Limited P2 — runtime supervision
|
||||
|
||||
Selected implementation: conservative runtime capabilities and intervention
|
||||
negotiation. Unsupported actions are explicit, not silently successful.
|
||||
|
||||
Residual: no general scheduler, durable supervisor state, cross-process cancel,
|
||||
pause/resume implementation, budget service or rollback engine was added.
|
||||
|
||||
## Tests added
|
||||
|
||||
- `assurance-kernel-tests.py`: 30 unit and conformance tests.
|
||||
- `assurance-upgrade-integration-tests.py`: 7 Agentic Bridge integration tests.
|
||||
- `phase-assurance-upgrade-tests.sh`: 11 shell integration groups.
|
||||
- `auth-provider.test.ts`: JWT and production identity tests.
|
||||
- Existing auth-context/report tests extended for spoofing and taxonomy.
|
||||
- Production preflight tests extended to a full valid contract plus audience,
|
||||
local trust and missing-key failures.
|
||||
|
||||
## Verification results
|
||||
|
||||
| Suite | Result |
|
||||
|---|---:|
|
||||
| Kernel unit + two-adapter conformance | 30/30 pass |
|
||||
| Draft 2020-12 JSON Schema validation | pass for both adapters |
|
||||
| Agentic upgrade integration | 7/7 pass |
|
||||
| Assurance upgrade shell integration | 11/11 pass |
|
||||
| Existing Agentic Bridge acceptance/threat suite | 42/42 pass |
|
||||
| Control Plane backend | 57/57 pass |
|
||||
| Control Plane backend TypeScript build | pass |
|
||||
| Control Plane frontend typecheck/Vite build | pass |
|
||||
| Existing H5 approval identity | 12/12 pass |
|
||||
| Sandbox isolation suite | 8/8 accounted; live Docker cases skipped |
|
||||
| Production handoff | 8/8 pass |
|
||||
| Existing H6 AgentOps | 20/20 pass |
|
||||
| Readiness compatibility | 5/5 pass |
|
||||
| Production and local Compose config | pass |
|
||||
|
||||
Legacy suites that generated tracked audit/dashboard output were run with
|
||||
temporary state where supported; known generated artifacts were restored after
|
||||
verification. Existing user-owned `docs/evidence/` was not modified.
|
||||
|
||||
## Infrastructure-dependent work not possible locally
|
||||
|
||||
- Live rootless Docker isolation and network/filesystem escape tests.
|
||||
- Enterprise IdP login and real key-rotation behavior.
|
||||
- Live Vault Transit signing against a managed policy/token.
|
||||
- Live S3 Object Lock retention and organization SCP/IAM enforcement.
|
||||
- Managed TLS/DNS and external endpoint smoke.
|
||||
|
||||
The provider interfaces, fail-closed validation and deterministic local
|
||||
contract tests are implemented for each missing dependency.
|
||||
|
||||
## Remaining gaps
|
||||
|
||||
- H4/H5/H2 and remaining H1/H3/H7 dossiers still need a shared canonical
|
||||
evidence-query implementation before `contract_ready` can be removed.
|
||||
- Static RS256 key mount lacks JWKS rollover.
|
||||
- Kernel adoption is proven for two adapters, not every loop/graph/runtime.
|
||||
- Runtime supervision is capability negotiation, not a full durable supervisor.
|
||||
- External trust and production host hardening require deployment evidence.
|
||||
- Cross-runtime policy-bundle distribution and remote adapter admission are not
|
||||
yet centralized by the Control Plane.
|
||||
|
||||
## Current maturity and honest claims
|
||||
|
||||
After this change, CASAN is a strong assurance-enabled harness with an
|
||||
implemented framework-independent Assurance Kernel foundation and a packaged,
|
||||
production-capable Control Plane boundary. Framework independence is proven for
|
||||
two adapters under the canonical contract. Full platform-wide kernel adoption,
|
||||
universal supervision, complete dossiers and provisioned external trust remain
|
||||
future work.
|
||||
Reference in New Issue
Block a user