Security model
Trust boundaries, threat model, and secret handling in Orca AI Gateway.
This page describes what the gateway defends against, what it does not, and how it handles secrets.
Trust boundaries
Every request crosses five boundaries between the client and the upstream provider, plus one between the gateway and its own control plane.
| Boundary | Threat | Mitigation |
|---|---|---|
| Client to auth validator | Forged or replayed credentials | JWT signature, issuer, and audience validation, or API-key SHA-256 digest lookup from keys_file |
| Authenticated client to authorizer and rate limiter | Authorization bypass, resource exhaustion | Configured authorizers and per-scope request, token, and dollar limits |
| Authorized client to guardrails | Prompt injection, sensitive data in prompts | Regex redaction and LLM evaluation on the input phase |
| Gateway to upstream provider | Credential theft, interception | Credentials resolved at call time from a vault and never written to config; TLS to upstreams |
| Upstream to client | Sensitive data in responses | Output-phase guardrails on non-streaming responses |
| Gateway to control plane | Tampered configuration | Least-privilege Postgres roles and validation before startup |
The single most important property is that the caller never holds the upstream credential. A compromised application can make calls the gateway permits, within the budget the gateway allows, and produces an audit record for each - but it cannot walk away with a provider API key.
Before you expose the data plane to untrusted clients, configure an auth validator for your callers' credentials and an authorizer that denies anonymous principals.
In scope
The gateway is designed to defend against:
- One authenticated tenant reaching another tenant's resources. Map every scope dimension from verified JWT claims or API-key attributes, and use a fail-closed authorizer. A verified scope value takes precedence over a same-named request header, so authorizers, routes, and rate limits act on the scope the credential proves. A config that references an undeclared dimension fails validation at boot.
- Prompt injection and jailbreak attempts. Guardrails run on input and non-streaming output, and can deny on error. Send a request without streaming when its response must pass output guardrails.
- A compromised dependency exfiltrating credentials. Secrets are resolved at runtime and held
only in memory, never persisted into config. The image is based on
debian:13-slimand runs as the non-root UID65532. The Helm chart sets a read-only root filesystem, disallows privilege escalation, and drops all capabilities. The Docker Hub image is signed with cosign and carries SPDX SBOM and SLSA provenance attestations.
Out of scope
The gateway does not defend against these threats. Address them in your environment:
- Same-host side-channel attacks. Run the gateway in a single-tenant pod if this is in your threat model.
- Compromise of an upstream provider. Rotate credentials and follow the provider's incident guidance; the gateway cannot help here.
- Compromise of the Kubernetes cluster. Standard cluster hygiene applies - RBAC, network policies, admission control.
Secret handling
Credentials are resolved through a vault at call time, held in memory in a wrapper that keeps them out of debug output, and injected into the upstream request. They are never included in a response to the caller and never written into the config document.
Two operational rules follow from that:
- Keep the admin plane off the network. It binds
127.0.0.1:9099by default, and it exposes configuration throughGET /admin/v1/config. Only widen the bind when a network policy or mTLS proxy fronts it. - Treat audit records as sensitive. They carry principal, scope, resource, and policy-decision metadata. Give them their own retention policy and access control.
Report a vulnerability
Report a suspected vulnerability in Orca AI Gateway by email to security@runorca.ai.