A working description of how SecurityVault is put together — the components, the three hard trust boundaries, the scan lifecycle, the tenancy model, the ontology pipeline and the cryptography. Written from the code and the normative architecture reference, for the people who will integrate and audit it.
Trusted components run in the platform namespaces. Untrusted work runs as ephemeral Jobs in a scan namespace with no route back except the callback.
FastAPI · create_app(Role)OIDC · SAML · RS256Celery · 15 deploymentsprojections · SSEOPA subprocesslocal model · advisorysecurityvault-scansfetcher + N tool pairsSV_TOOL · SV_RESULTS_DIRparse · sign · POSTSV_TOOL_DEADLINE_SECONDS≤ 1 h · garbage-collectedpgvector · RLSbroker · cache · noncessecurity lakeS3-compatiblesecrets · signing keysHarbor · CosignA compromised scanner is the assumed case, not the edge case. The boundaries are enforced by pod specification, by Kubernetes Secrets and by the API — not by policy documents.
The tool container holds the scanner binary and the acquisition credentials for the target. The adapter container holds the platform token. They share one results volume, read-only on the adapter side. A scanner with remote code execution reaches the repository it was already given and nothing more.
Two Kubernetes Secrets per job. scan-acquire-creds (Git or registry token) mounts only into the tool container. scan-adapter-creds(SCAN_TOKEN, BODY_SIGNING_KEY) mounts only into the adapter. No container ever holds both. The adapter hard-exits if any storage credential appears in its environment.
Results enter the control plane only through api-callback. The scan token is opaque, single-use, database-backed and bound to the scan, the tool and the job; the body is HMAC-signed and carries a replay nonce. Both are verified before a byte is parsed.
appsec-unified, our own engine, is held to exactly the same rules as Trivy or Semgrep. It runs as a Job, it reports through the callback, and there is no privileged in-process fallback. If it breaks, scans fail closed.Every transition goes through one module and records its evidence. Terminal states say what happened, not just that something did.
| From | To | Trigger | Recorded |
|---|---|---|---|
| — | PENDING | Scan requested | Scan row, audit event |
PENDING | QUEUED | Celery task dispatched | Task id |
QUEUED | RUNNING | Kubernetes Job started | Job name, tokens minted, per-tool deadlines |
RUNNING | COMPLETED | All tools reported | Results ingested, audit event |
RUNNING | PARTIAL | Some tools failed or missed their deadline | Per-tool outcome, partial results kept |
RUNNING | FAILED_TIMEOUT | Job deadline exceeded | Reaper verdict with the tool that timed out |
RUNNING | FAILED_DEPENDENCY | Missing credential or policy | Dependency error |
RUNNING | FAILED_CONFIG | Invalid scan configuration | Configuration error with hint |
The adapter posts a signed result. The callback handler verifies, then resolves it into the ontology under the tenant the scan belongs to. Nothing the pod says about its tenant is trusted.
SCAN_TOKEN, scope-bound to scan, tool, job and the server-derived organization. Verified by database lookup; purged when the job is garbage-collected.X-SV-Body-Signature over canonical JSON with a key derived per scan. Constant-time comparison.X-SV-Nonce recorded in a per-scan set. In required mode the callback fails closed if the nonce store is unreachable.scan.organization_id. Any organization field in the payload is advisory and ignored for authority.Every session binds the acting organization before the first query. Row-level security policies exist for every tenant table and are asserted by the test suite on every merge.
Authenticated requests bind app.current_org_id and the acting principal through one set of database binders. Search path is always public; there are no per-tenant schemas.
The tenant comes from the verified session, never from a caller-controlled parameter. A CI gate refuses any handler that reads a bare org_id before resolving it against the session.
Every read, update or delete of one resource filters on organization_id in the SQL — a primary-key-only match is treated as a cross-tenant defect and blocked at review.
Cross-tenant admin routes take a platform-scoped session that can never bind a tenant and must run under the admin database role, or answer 503.
A database trigger refuses any disposition change without a bound acting principal, so no worker, reaper or AI task can flip a verdict even with a valid connection.
Forward-only SQL migrations with SHA-256 verification of applied files; CI proves a populated upgrade converges with a fresh installation before a release is cut.
Raw results are observations. Observations become entities, edges, logical findings, cases, attack paths and risk scores through a deterministic pipeline that emits a versioned event at each step.
missing and conflicting hops are computed when the view is built and never persisted. Storing a missing edge would fabricate a relationship.No invented protocols. Each algorithm below has one job.
| Where | Primitive | Detail |
|---|---|---|
| User sessions | RS256 JWT | 15-minute access token with a kid header; refresh token in an httpOnly cookie. RS256 is mandatory outside development; HS256 verification paths are closed. |
| Stored credentials | Fernet (AES-128-CBC + HMAC-SHA256) | Customer Git, registry and cloud credentials encrypted at rest; decrypted only inside the worker that mints the scan Secrets. |
| Control decisions | Ed25519 | Canonical sorted-key payload: control, decision, framework control, input hash, organization, key fingerprint, schema version, timestamp. Private key held by the evaluation service; public half distributable to auditors. |
| Evidence & inputs | SHA-256 | Evidence hashing and evaluation-input hashing so a decision can be tied to exactly what it saw. |
| Audit log | HMAC chain | Append-only records, each carrying the HMAC of its predecessor. |
| Scanner callbacks | HMAC body signature | Per-scan derived key, canonical JSON, replay nonce, constant-time compare. |
| Ticketing webhooks | HMAC + nonce | Per-organization, per-provider key with the same replay guard as scanner callbacks. |
| Images | Cosign | Platform and scanner images signed; an admission webhook can refuse unsigned images in the cluster. |
| Transport | TLS 1.2+ / 1.3 | Edge TLS at the gateway; internal mTLS from the platform PKI for service-to-service calls. |
OIDC and SAML single sign-on, SCIM 2.0 provisioning, MFA. Okta, Microsoft Entra ID, Google Workspace and CyberArk connectors ship in the platform.
Permission bindings are the access authority. Eight personas — developer, AppSec, cloud, SOC, GRC, executive and more — only shape the home view; they never grant access.
Finding status and disposition are governance fields. An ORM-level guard blocks AI and worker writes; a database trigger backs it up. Reason codes are mandatory.
Pipelines authenticate with OIDC workload identity; PR comments and gate results are posted under a CI principal with per-organization rate limits.
Sensitive governance actions require a second approver; approval scope is checked at the action, not at login.
Every natural-language query to the AI filter is audited whether accepted or rejected. The model is never re-prompted on failure, closing the model-probing surface.
| Scenario | Blast radius | Containment |
|---|---|---|
| Scanner remote code execution | One scan; the repository it was given | Network isolation, ephemeral credentials, pod termination, no platform credentials present |
| Scanner out of memory or crash | One tool in one scan | Per-tool deadline and resource limits; scan ends PARTIAL with the other results kept |
| Worker crash | Tasks queued on that worker | Automatic restart; tasks re-queued from the broker |
| Broker unavailable | New scans wait | Redis persistence, reconnect with backoff; nothing is silently dropped |
| Nonce store unavailable | Callbacks refused | Fail closed in required mode; the adapter retries, results are not lost |
| Policy evaluator error | The decision being evaluated | DENY with OPA_EVALUATION_FAILED; never an allow |
| Database primary failure | Writes until promotion | Streaming replication and standby promotion; point-in-time recovery from WAL |
| IdP unreachable | New SSO logins | Existing tokens valid until expiry; retry with backoff |
Structured logging, Prometheus metrics on every plane and worker, OpenTelemetry tracing through the API and Celery. Logs are shipped to a central store per environment.
Dozens of architectural-invariant checks run on every merge request: banned patterns, tenant-parameter authority, structlog floor, Cilium policy shape, bundle budgets, route manifest, credential rotation versions, accessibility on redesigned routes.
Unit, worker, property and integration suites in Docker; Playwright end-to-end against the production build; schema proofs on a fresh and an upgraded database.
The platform scans its own repository and images on the same pipeline it sells, and the finding burndown is tracked in the repository.
Images built rootless, signed with Cosign, pulled through a private registry mirror; dependency and base-image updates go through the same gates.
Cilium network policies scoped by label; an empty selector is rejected by CI because it would put every pod into default-deny at once.
| Layer | Technology | Purpose |
|---|---|---|
| API | FastAPI · Pydantic v2 | Async REST with strict request models (extra="forbid", length caps) |
| Data access | SQLAlchemy 2.0 | Async sessions on the request path, sync in workers |
| Database | PostgreSQL 16 · pgvector | Primary store, audit ledger, row-level tenant policies |
| Queue | Celery 5 · Redis | Orchestration, scheduling, rate limits, replay nonces |
| Lake | ClickHouse | High-volume security events and analytics |
| Policy | Open Policy Agent | Deterministic Rego evaluation, fail closed |
| Analysis | Tree-sitter | Language grammars for the native taint analysers |
| Execution | Kubernetes · Cilium | Scan Jobs, platform deployment, network policy |
| Signing | Cosign · Ed25519 · HMAC | Images, decisions, audit chain, callbacks |
| Frontend | React 19 · TypeScript · MUI · TanStack Query · Vite | Single-page application with strict CSP |
| Testing | pytest · Vitest · Playwright · axe-core | Backend, frontend, end-to-end, accessibility |
api-callback. Deregistration is a soft delete so the audit trail survives.A 60-minute session with the engineers who built this. We answer from the code, on the record.