Architecture
AXIS is a deterministic control layer for PostgreSQL write paths. It sits between applications or operators and the database: it classifies SQL, evaluates versioned policy, enforces the decision, and records durable evidence — all before execution-sensitive outcomes.
System overview
Components
| Component | Responsibility | Status |
|---|---|---|
| HTTP listener / gate | Exposes POST /query and the API surface; validates requests and size limits | Verified |
| SQL classifier | PostgreSQL dialect parsing, normalization, fingerprinting, operation detection, target extraction, scope estimation, risk signals | Verified |
| Session store | In-memory session_id-scoped prepared statement metadata for AXIS-side PREPARE / EXECUTE / DEALLOCATE enforcement | Implemented |
| Policy engine | Versioned policy evaluation producing ALLOW, BLOCK or REQUIRE_APPROVAL; deterministic | Verified |
| Approval store | Local pending and resolved approval records (SQLite per install guide; JSONL-backed per security model); immutable resolution | Verified |
| Audit logger | WAL plus JSONL projection with event hashes and previous-hash linkage; fsync-backed, fail-fast on corruption | Verified |
| Evidence verifier | Read-only hash-chain verification (GET /evidence/verify, /audit/verify) | Implemented |
| Runtime log store | Bounded in-memory operational log buffer exposed by GET /logs; operational visibility only, not durable proof | Implemented |
| Policy lifecycle store | Immutable version files, active policy pointer, candidate state, validation, activation, rollback; manifest-authoritative startup | Verified |
| Audit derived index V1 | Read-model index (audit_index_v1.json); safe to delete/rebuild; WAL remains canonical | Implemented |
| Evidence Bundle V1 exporter | Redacted, WAL-backed export bundle (bundle_type: axis.evidence_bundle.v1) with optional Ed25519 signing | Implemented |
| PostgreSQL executor | Executes ALLOW decisions through the configured executor with bounded pool and timeouts | Verified |
| Control Plane | Next.js operator surface; reads live endpoints via server-side proxy; mock mode is explicit demo-only | Implemented |
| Native PG wire listener (lab) | Disabled-by-default Simple Query listener (AXIS_PGWIRE_ENABLED=false); intercepts Q messages, enforces before forward | Experimental |
Intentional read/write split
The pilot integration intentionally sends safe reads directly to PostgreSQL and protected writes through AXIS. This keeps the demo focused on policy-controlled mutation paths; it does not prove universal inspection of every read query. Reads default to ALLOW, writes default to BLOCK, DDL defaults to REQUIRE_APPROVAL.
Control Plane boundary
- The browser calls
/api/axis/*on the Control Plane; it never receives the backend URL or the operator token. - Real mode reads live endpoints; mock mode is explicit server-side demo behavior only and is not production evidence.
- Runtime logs are read through
/api/axis/logs; real mode does not fabricate log rows.
Trust boundaries
Trusted
AXIS process; local policy files and manifest; local audit WAL; local approval store; the configured PostgreSQL instance; AXIS-to-database forwarding (AXIS is trusted to enforce before forwarding).
Untrusted / verifiable
HTTP body to /query; SQL text; identity fields (actor, app, tenant, role, host, env); approval resolution input. v1 does not authenticate HTTP callers: identity fields are evidence and policy inputs, not verified identity claims.
Local SHA-256 integrity checks detect accidental or simple tampering but do not replace external key management or signed policy distribution. Audit WAL files are trusted for local review but are not an external tamper-proof ledger.
Architectural principles
- Deterministic over probabilistic — policy decides; AXIS does not guess with AI.
- Fail-safe defaults — unsupported or dangerous SQL shapes do not silently pass.
- Evidence before execution — if durable decision evidence cannot be written, protected execution must not proceed.
- Audit integrity over convenience — malformed or corrupted evidence is reported, never silently repaired.
- No silent policy downgrade — activation and rollback require validation and expected-hash checks.
- Visibility without fake data — operator views expose real state when connected to a live backend.
Documented boundaries
- AXIS session id to PostgreSQL backend session: not trusted as equivalent in v0.8 — pooled backends do not guarantee connection affinity.
- Runtime log store is operational visibility only, not durable proof.
- Prepared
EXECUTEdry-run fails safe as unresolved (no durable session store attached). - The v1 guarantee is local and process-bound; it does not claim distributed, multi-instance audit finality or enterprise access control.
Related: Security Model · Request Lifecycle · Native PG Wire Protocol