feat(casan): establish assurance kernel and harden control plane
This commit is contained in:
thanhnv
@@ -0,0 +1,126 @@
|
||||
# CASAN Assurance Kernel Migration
|
||||
|
||||
## Scope
|
||||
|
||||
This migration preserves existing native and Agentic Bridge protocols while
|
||||
adding canonical kernel envelopes and changing unsafe defaults. It is designed
|
||||
for incremental adoption; no big-bang H1–H7 rewrite is required.
|
||||
|
||||
## Behavior changes
|
||||
|
||||
1. H2 registry enforcement defaults on in enforce mode.
|
||||
2. A missing or failed H2 dependency denies in enforce mode.
|
||||
3. High-impact action classes use deterministic risk floors and require actor,
|
||||
approval and evidence.
|
||||
4. Failed side-effecting single-step execution defaults to halt in enforce or
|
||||
production mode.
|
||||
5. Enforce/production sandbox execution refuses timeout/static-only fallback.
|
||||
6. Networked/production Control Plane startup requires verified JWT identity;
|
||||
`CASAN_CP_TRUST_AUTH_PROXY` no longer authorizes header trust.
|
||||
7. Production certification requires an external signing provider and external
|
||||
immutable anchor.
|
||||
8. Canonical schema `1.0.0` is dual-emitted with legacy runtime records.
|
||||
|
||||
## Development migration
|
||||
|
||||
Existing loopback development works with:
|
||||
|
||||
```text
|
||||
CASAN_PROFILE=development
|
||||
CASAN_CP_AUTH_MODE=local
|
||||
CP_BIND=127.0.0.1
|
||||
```
|
||||
|
||||
For short-lived compatibility testing only, H2 can be bypassed explicitly:
|
||||
|
||||
```text
|
||||
CASAN_H2_REGISTRY=0
|
||||
CASAN_AGENTIC_H2_REGISTRY=0
|
||||
```
|
||||
|
||||
The bypass is high-severity, observe-only/non-certifiable and rejected in
|
||||
production. Prefer registering the tool instead of retaining this setting.
|
||||
|
||||
Failure handling can be selected with
|
||||
`CASAN_SINGLE_STEP_FAILURE_POLICY=halt|quarantine|require_approval|record_only`.
|
||||
Production side effects reject `record_only` and fail closed to `halt`.
|
||||
|
||||
## Production Control Plane migration
|
||||
|
||||
1. Export the enterprise IdP's RS256 public key.
|
||||
2. Configure issuer, audience, claim names and bounded clock skew in
|
||||
`runtime.env` using `infra/production/runtime.env.example`.
|
||||
3. Configure oauth2-proxy to pass access tokens and authorization headers.
|
||||
4. Set `CASAN_CP_IDP_PUBLIC_KEY` in `casan-prod.env` for the read-only mount.
|
||||
5. Add a digest-pinned `CASAN_CP_OAUTH2_PROXY_IMAGE`.
|
||||
6. Remove `CASAN_CP_TRUST_AUTH_PROXY` from every environment.
|
||||
7. Configure Vault/KMS and Object Lock provider variables.
|
||||
8. Run `production-preflight.sh` before starting Compose.
|
||||
9. Run managed endpoint smoke with an authenticated enterprise session.
|
||||
|
||||
The current API loads a static public key at startup. Coordinate IdP rotation by
|
||||
installing the next public key and restarting the API after token overlap has
|
||||
been handled operationally. Automated JWKS rollover is not yet implemented.
|
||||
|
||||
## Adapter migration
|
||||
|
||||
The native harness and Agentic Bridge already dual-emit to
|
||||
`CASAN_STATE_ROOT/logs/kernel/`. Existing consumers can keep reading legacy
|
||||
records. New consumers should:
|
||||
|
||||
1. Require `schema_version=1.0.0`.
|
||||
2. Run the common verifier.
|
||||
3. Respect the four separate outcome fields.
|
||||
4. Reject observed-only certification.
|
||||
5. Treat runtime extensions as optional namespaced data.
|
||||
6. Avoid certifying legacy runs that have no canonical evidence.
|
||||
|
||||
For a new runtime, implement an adapter and pass the complete 10-invariant
|
||||
conformance matrix before advertising kernel conformance.
|
||||
|
||||
## Audit compatibility
|
||||
|
||||
New H5 audit records use v2 hashing with action class and risk factors. The
|
||||
audit verifier and head signer support v1 and v2 records. This is compatibility,
|
||||
not claim upgrading: v1 records do not gain v2 risk evidence retroactively.
|
||||
|
||||
## Verification commands
|
||||
|
||||
```bash
|
||||
python3 packages/casan-harness/tests/assurance-kernel-tests.py
|
||||
python3 packages/casan-harness/tests/assurance-upgrade-integration-tests.py
|
||||
bash packages/casan-harness/tests/phase-assurance-upgrade-tests.sh
|
||||
bash packages/casan-harness/tests/phase-agentic-bridge-tests.sh
|
||||
npm --workspace packages/casan-control-panel/backend test
|
||||
npm --workspace packages/casan-control-panel/backend run build
|
||||
npm --workspace packages/casan-control-panel/frontend run build
|
||||
bash packages/casan-harness/tests/phase-production-preflight-tests.sh
|
||||
```
|
||||
|
||||
Redirect `CASAN_STATE_ROOT` to a temporary directory for legacy suites that
|
||||
write runtime evidence.
|
||||
|
||||
## Rollback
|
||||
|
||||
Code rollback can restore the previous adapters because legacy emission remains
|
||||
present. Before rollback:
|
||||
|
||||
1. Stop new runs and preserve canonical/audit evidence.
|
||||
2. Record the last v2 audit head and external anchor.
|
||||
3. Roll back API, UI, Nginx and oauth2-proxy as one deployment unit.
|
||||
4. Do not restore trusted-header identity on a networked deployment.
|
||||
5. Do not disable production registry, isolation or trust-root requirements.
|
||||
6. If operational continuity requires emergency local trust, use the explicit
|
||||
break-glass override, retain the critical evidence and do not certify runs.
|
||||
|
||||
A rollback that reintroduces production header trust, missing-gate allow, or
|
||||
silent sandbox/trust fallback is not a safe compatibility rollback.
|
||||
|
||||
## Expected warnings
|
||||
|
||||
- Development registry bypass: high severity and non-certifiable.
|
||||
- Missing H2 in observe mode: degraded assurance.
|
||||
- Local signer/local ledger: permitted locally, untrusted for production.
|
||||
- Unsupported runtime intervention: explicit `unsupported`.
|
||||
- Legacy evidence without kernel envelope: compatibility-readable but not
|
||||
kernel-validated.
|
||||
Reference in New Issue
Block a user