Security

What a security review of a Guard Spec deployment needs in one place: the components and their trust boundaries, which data goes where, what is stored, for how long and how it is protected, and how to check that the release you run is the one this project built. Everything here is derived from the code and migrations of the release it ships with (0.1.x); where a statement depends on a setting, the setting is named.

Contents#

• Architecture
• Data flow of one request
• What is stored, where and for how long
• Secrets
• Encryption
• Tenant isolation
• What leaves your network
• Threat model
• Verifying a release

Architecture#

Two Go services and one PostgreSQL database. Nothing else is required.

flowchart LR
  app[Your applications] -->|"HTTPS (your proxy) · API key"| gw
  admin[Admins, browser] -->|"HTTPS (your proxy) · JWT session"| cp
  subgraph yours[Your network]
    gw[gateway :8080<br/>metrics :9090]
    cp[control plane :8081<br/>admin UI, API<br/>metrics :9091]
    db[(PostgreSQL 17)]
    models[[model files<br/>read-only]]
    gw -->|guardspec_app, RLS| db
    cp -->|guardspec_app, RLS| db
    models -.-> gw
  end
  gw -->|prompt, after the checks| llm[Upstream LLM API]
  cp -.->|alert metadata| chan[Slack, Teams, Telegram,<br/>e-mail, webhooks, A2A]
  cp -.->|OIDC| idp[SSO provider]

Neither service terminates TLS: put a reverse proxy or load balancer in front (P1), and set TRUSTED_PROXIES on the control plane so that rate limits, sessions and the activity log see the client address (I5). The release images run as non-root with a read-only root filesystem.

Data flow of one request#

1. An application sends an OpenAI-compatible request to the gateway with its API key. The gateway hashes the key (SHA-256) and looks it up; the plaintext key is never stored.
2. The sanitizer (L0) strips invisible and bidi characters. The detection layers score the parts listed in SCAN_ROLES (L1 rules, L2 classifier, L3 similarity, all in process). The org's policies (CEL) decide: allow, block, log or route.
3. Blocked: the gateway answers 400 and the upstream is never called. Allowed: the request goes to the upstream LLM chosen by routing, with the upstream's key from an environment variable.
4. The output guard checks the answer (links and images to unknown hosts, personal data, a leaked canary), also while streaming, and the answer goes back to the application.
5. The gateway writes one audit row (requests) and, for blocks, an event (events) that the control plane's alert worker turns into notifications.

Prompt and answer text exist in the gateway's memory during the request. By default they are not written anywhere by Guard Spec: not to the audit row (only a SHA-256 and the length), not to logs (log lines carry scores, rule ids and decisions), not to traces (span attributes are the HTTP method, route, status and upstream path), not to events or notifications (metadata only: ids, categories, scores).

What is stored, where and for how long#

Everything is in PostgreSQL. The services keep no state on disk; the gateway's rate-limit counters and caches are in memory.

Outside the database:

• Logs (stdout, JSON lines): no prompt or response text, no secrets. Their retention is whatever your log pipeline sets.
• Metrics: fixed label sets; per-org series only with METRICS_TENANT_LABELS=true.
• Backups of the database hold everything above, including audit content if it was stored. They inherit its sensitivity.

Secrets#

Outside GUARD_ENV=dev the services refuse to start with a missing, short or known default secret. API keys, invite tokens, link codes and recovery codes are shown once and stored only as hashes.

Encryption#

• In transit. Terminate TLS in front of both services. Use sslmode=require (or verify-full) in DATABASE_URL for a database on another host. Upstream, SSO and alert calls use HTTPS as configured.
• At rest, by Guard Spec. TOTP secrets: AES-256-GCM with MFA_ENC_KEY. Passwords and recovery codes: bcrypt. API keys and one-time tokens: SHA-256. Nothing else is encrypted by the application.
• At rest, by your platform. Audit rows (and their content, if stored), the activity log, e-mail addresses and IP addresses rely on the database's storage encryption: turn it on (RDS storage_encrypted, Cloud SQL default encryption, LUKS or similar on-premise) and for backups too.

Tenant isolation#

Every org-scoped table has PostgreSQL row-level security on app.org_id, which the services set per transaction; the application role cannot bypass it. Tables keyed by user (sessions, identities, 2FA) are not org-scoped and are read by user id. A failure to evaluate policies or org settings fails the request closed (503).

What leaves your network#

There is no telemetry or call home.

Threat model#

The risks that remain when you run Guard Spec, grouped as detection, application, deployment, identity, data, supply chain and operations risks, each with what reduces it, are in Security risks and hardening (Vietnamese: security-risks.vi.md). Its hardening checklist is the shortest path to a reviewed deployment.

Verifying a release#

Images are signed with cosign (keyless, GitHub Actions OIDC) and carry SPDX SBOMs and SLSA provenance; archives are covered by signed checksum files. The commands, what each check proves and their output for v0.1.1 are in Verifying a release.

Source: docs/security/README.md @ ca69dad29f02