feat(casan): establish assurance kernel and harden control plane

2026-08-02 23:24:51 +07:00
parent 8b477f3800
commit 5745519126
51 changed files with 4076 additions and 180 deletions
@@ -0,0 +1,109 @@
+# CASAN Trust Boundaries
+
+## Trust model
+
+CASAN separates enforcement, evidence, identity, execution isolation and
+external trust. Passing one boundary never implies that another passed.
+
+| Boundary | Development/local | Production/strict |
+|---|---|---|
+| Control Plane identity | Explicit loopback local identity | In-process RS256 JWT verification required |
+| H2 tool authority | Enforce defaults on; explicit bypass is high-severity/non-certifiable | Enforce on; bypass configuration rejected |
+| H5 high-impact action | Approval and actor required by action floor | Strict signed approval plus external trust requirements |
+| Tool isolation | Static fallback only when explicitly enabled in dev/test | Container isolation required; unavailable backend denies |
+| Audit signing | Local OpenSSL permitted and labelled local | Vault/KMS external signing required |
+| Immutable anchor | Local hash chain permitted and labelled local | External Object Lock/WORM provider required |
+| Certification | Local/observed limitations disclosed | Unsafe fallback or emergency override cannot normally certify |
+
+## H2 enforcement dependency
+
+H2 returns a structured `PolicyDecision`, never a boolean-only decision. Missing
+file, unreadable file, timeout, malformed protocol, missing runtime and internal
+execution errors have stable reason codes. In enforce mode all dependency
+errors deny. In observe mode the operation may be observed, but assurance is
+degraded and certification is forbidden.
+
+Registry enforcement defaults on for side-effecting native and Agentic Bridge
+paths. `CASAN_H2_REGISTRY=0` or `CASAN_AGENTIC_H2_REGISTRY=0` is an explicit
+unsafe development/test bypass. Production treats the bypass as invalid.
+
+## H5 governance and action risk
+
+`config/action-classes.json` is the common policy source. Effective risk is the
+maximum of content, action, resource, identity and environment factors.
+Deployment, release, migration, database mutation, delete,
+identity/permission modification and infrastructure modification cannot be
+downgraded by benign wording. Credential access and unknown commands are also
+high-risk. High-impact operations require actor identity, approval and
+evidence.
+
+Production governance requires strict approval and external signing/anchor
+capability. Governance audit format v2 binds action class, risk factors and
+evidence requirements into the hash. The verifier continues to recognize
+legacy v1 records without upgrading their claims.
+
+## Execution isolation
+
+`sandbox-run.sh` detects its selected capability and writes structured sandbox
+evidence. In enforce/production mode a side-effecting path requires the
+container backend. If Docker or the required backend is unavailable, execution
+is denied with `sandbox_isolation_backend_unavailable`; there is no silent
+timeout/static fallback.
+
+The implemented container contract uses:
+
+- Read-only root filesystem.
+- Explicit workspace bind mount as the writable scope.
+- Network disabled by default.
+- Non-root container user.
+- Dropped Linux capabilities and `no-new-privileges`.
+- PID, memory, CPU and timeout limits.
+- Restricted working directory and filtered environment.
+- Output-size and exit-code capture at the harness boundary.
+- Rootless Docker requirement in production.
+
+CASAN does not claim AppArmor, SELinux, a custom seccomp profile, per-domain
+network allowlisting or complete host isolation where those mechanisms are not
+configured. Development static fallback is policy filtering, not isolation.
+
+## Control Plane identity boundary
+
+Arbitrary `X-CASAN-*`, `X-Forwarded-User` and similar headers are untrusted.
+Nginx removes them, oauth2-proxy provides a signed access token, and the API
+verifies the token before creating `VerifiedClaims`. A non-loopback local mode
+or an invalid production verifier refuses startup.
+
+## Signing and immutable evidence boundary
+
+Local SHA-256 chains and evidence digests provide tamper detection under the
+local host's trust. They are not externally trusted immutability. Normal
+production certification requires both:
+
+1. `CASAN_SIGNING_PROVIDER=vault_kms` (or another explicitly supported external
+   trust provider) with an HTTPS endpoint and short-lived credential.
+2. `CASAN_IMMUTABLE_ANCHOR_PROVIDER=s3_object_lock` (or an explicitly supported
+   external WORM provider) with bucket and KMS configuration.
+
+The packaged production path verifies Vault Transit readiness and performs an
+S3 Object Lock COMPLIANCE anchor write. It does not provision either service.
+
+`CASAN_TRUST_EMERGENCY_OVERRIDE=1` is break-glass behavior. It emits critical
+evidence, keeps readiness failed and makes the run non-certifiable. It is not a
+normal production fallback.
+
+## Secret and evidence handling
+
+- Raw JWTs and authentication secrets are not logged.
+- Tool and prompt evidence remains subject to existing redaction/scanning.
+- Authentication evidence records identity metadata and stable reason codes.
+- Canonical evidence digests detect local metadata tampering, while external
+  signing/anchoring supplies production trust.
+- A successful evidence append never changes a failed execution into success.
+
+## Infrastructure not proven by repository tests
+
+Repository-local tests use cryptographic fixtures and narrow service stubs.
+Docker isolation tests are skip-aware when Docker is absent. Real enterprise
+OIDC traffic, Vault policy enforcement, KMS/HSM custody, S3 retention policy,
+rootless Docker host hardening and managed network controls require deployment
+evidence before production claims are made.