110 lines
5.4 KiB
Markdown
110 lines
5.4 KiB
Markdown
# 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.
|