Threat model, trust boundaries and the controls the platform provides today, with the gaps that are roadmap items. The POC defaults are deliberately permissive (DBP_SECURITY_MODE=none, DBP_SERVICE_TOKEN=dev-service-token); this page lists what to change before any production use.

Related: operations.md (configuration), collectors.md (collector accounts), control-plane-api.md (api-key and credential endpoints).

flowchart LR
  subgraph APPS[Application network]
    A1[Service with dbp-jdbc<br/>api key]
    A2[Legacy app with vendor driver]
  end
  subgraph PLAT[Platform network]
    GW[dbp-gateway<br/>holds DB credentials in memory]
    PX[dbp-proxy<br/>sees connect packets, relays bytes]
    CP[dbp-control-plane<br/>metadata store, encrypted secrets]
    UI[dbp-ui]
  end
  subgraph DBS[Database network]
    ORA[(Oracle)]
    PG[(PostgreSQL)]
  end
  A1 -- "wire protocol (TLS optional)" --> GW
  A2 -- "TNS / PG protocol" --> PX
  GW -- "vendor JDBC, DB credentials" --> ORA
  GW --> PG
  PX -- "same protocol, rewritten service name" --> ORA
  PX --> PG
  GW -- "service token" --> CP
  PX -- "service token" --> CP
  CP -- "collector account" --> ORA
  CP --> PG
  UI -- "public API (none/basic)" --> CP

Format: dbp_<prefix>_<secret>.

Why api keys first and not workload identity: see ADR 0011. The key is a bearer secret; its blast radius is bounded by the grants of the owning application, and it never grants anything on the database itself.

/api/v1/internal/** (auth, resolve, credential material, proxy config, telemetry, heartbeat) is protected by one shared token sent as X-DBP-Service-Token and configured through DBP_SERVICE_TOKEN on the control plane, gateways and proxies.

• Change the default before exposing the control plane to anything but localhost.
• Treat it like a database password: random ≥ 32 bytes, stored in your secret manager, rotated by updating the control plane and the components. The control plane accepts exactly one token (DBP_SERVICE_TOKEN), so a rotation is: restart the control plane with the new value, then restart gateways and proxies immediately — in between they get 401, keep serving from cache and buffer telemetry (bounded queue, oldest dropped), so keep the window short.
• Restrict the internal path at the network/ingress layer to the gateway and proxy subnets.
• The same variable gates the proxy's admin API: with DBP_SERVICE_TOKEN set, GET :7431/connections and GET :7431/config (client addresses, users, program names, route table) require X-DBP-Service-Token; /health and /metrics stay open. The gateway's /sessions and /pools have no authentication — keep both admin ports off application networks (see Network enforcement) or bind them to localhost (DBP_PROXY_ADMIN_ADDRESS=127.0.0.1).

A Credential is the database account the platform itself uses (gateway pools, collectors). Secrets never appear on public endpoints.

Operational rules:

• Generate DBP_MASTER_KEY once, keep it in the secret manager, never in the metadata store or in compose files committed to git (deploy/.env is git-ignored). Losing it makes INLINE secrets unrecoverable; re-entering them via rotate is the recovery path.
• Prefer ENV/FILE over INLINE in production so the metadata store never contains DB passwords, even encrypted.
• Gateways fetch material on demand (GET /internal/credentials/{id}/material) and keep it only in memory; the fetch is audited by the control plane (logger org.dbplatform.controlplane.audit.credentials: which credential, when, which component).
• One DB account per datasource (not per application) is the recommended granularity: it keeps the Oracle user count manageable while telemetry provides per-application attribution.

The platform's value depends on applications not being able to go around it.

• Only gateway, proxy and control plane (collectors) may reach database ports. Express this as a Kubernetes NetworkPolicy on the database namespace (or firewall rules/security groups for VMs): ingress to 1521/5432/1433 from the dbp-gateway, dbp-proxy and dbp-control-plane labels only.
• Applications reach the gateway (7420) and the proxy (1521/5432/1433 on the proxy service) only.
• Admin ports (7421, 7431) and the control plane's /api/v1/internal/** are reachable from the platform namespace and monitoring only (deploy/k8s/networkpolicy.yaml admits 7421/7431 from namespaces labelled dbp.io/monitoring=true). Prometheus needs only /metrics, which never requires the token.
• The DIRECT_DB_ACCESS_BYPASSING_PLATFORM governance policy uses collector session samples to flag database sessions whose client address is neither a gateway nor a proxy; it is detection, not prevention.

Example (sketch; adapt labels and namespaces):

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: db-ingress-from-platform, namespace: databases }
spec:
  podSelector: { matchLabels: { role: database } }
  policyTypes: [Ingress]
  ingress:
    - from:
        - namespaceSelector: { matchLabels: { name: dbp } }
          podSelector: { matchExpressions: [{ key: app, operator: In, values: [dbp-gateway, dbp-proxy, dbp-control-plane] }] }
      ports: [{ port: 1521 }, { port: 5432 }, { port: 1433 }]

"Who executed what" is answered at three levels, from cheapest to most authoritative:

Gateway telemetry is attribution-grade (application identity is authenticated), but it is not a tamper- evident audit log and it does not contain parameter values. Where regulation requires a database-side record, enable the vendor audit on the schemas concerned and let the collector import it (collector.auditTrail: true, Oracle AUDIT_VIEWER). The gateway forwards every client info entry the application sets to the physical connection while the session is pinned and, for Oracle, maps ApplicationName → OCSID.MODULE, ClientUser → OCSID.CLIENTID and action → OCSID.ACTION (V$SESSION.MODULE / CLIENT_IDENTIFIER / ACTION, UNIFIED_AUDIT_TRAIL.CLIENT_IDENTIFIER), so even the database audit shows the logical application rather than only the shared pool user dbp-gateway/<gatewayId>. See Request-level tracing.

The control plane itself records: credential material reads, MigrationEvents (by), api-key issue/ revoke timestamps. Operator identity is only meaningful with DBP_SECURITY_MODE ≠ none.

The collector needs read access to metadata and runtime views only — never to application data.

-- Oracle (run in the PDB)
CREATE USER dbp_collector IDENTIFIED BY "…" PROFILE service_accounts;
GRANT CREATE SESSION, SELECT_CATALOG_ROLE TO dbp_collector;
-- optional, only with unified auditing policies in place:
GRANT AUDIT_VIEWER TO dbp_collector;

-- PostgreSQL
CREATE ROLE dbp_collector LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE sales TO dbp_collector;
GRANT pg_monitor TO dbp_collector;

-- SQL Server
CREATE LOGIN dbp_collector WITH PASSWORD = '…';
GRANT VIEW SERVER STATE TO dbp_collector;
USE sales; CREATE USER dbp_collector FOR LOGIN dbp_collector; GRANT VIEW DEFINITION TO dbp_collector;

The gateway pool account per datasource is different: it needs exactly the object privileges the consuming applications need (typically SELECT/INSERT/UPDATE/DELETE on the domain's tables and EXECUTE on its packages), granted through a role per datasource. Do not reuse a schema owner.

Logging configuration: gateway and proxy ship Logback (DBP_LOG_LEVEL, gateway also DBP_LOG_LEVEL_HIKARI); keep them at INFO in production (DEBUG on the gateway can log full SQL; DEBUG on the proxy logs every handshake with service names, programs and users). The driver logs through java.util.logging (org.dbplatform.jdbc) and never logs SQL text, parameters or rows, even at FINE.

See ADR 0011 for the reasoning behind the ordering.