Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent database proxy protocols

The KnoxCall agent’s database proxy binds one TCP listener per configured route on 127.0.0.1. Applications connect as if they’re connecting to the database directly. The agent handles authentication upstream and pipes the connection through. This page covers the wire-level details for each supported protocol.

​
General architecture

Application (any process on the same host)
    ↓  TCP to 127.0.0.1:{port}
Agent listener
    ↓  SO_PEERCRED UID check
    ↓  Fetch credentials from KnoxCall session bundle
    ↓  TLS connect to upstream DB host:port
    ↓  Perform auth handshake on behalf of application
    ↓  Pipe post-auth bytes bidirectionally until connection closes
Upstream database

​
Local-only binding guarantee

The agent refuses to start if any proxy port is configured to bind on a non-loopback interface. There is no override flag. If your deployment requires cross-host access, use a network namespace or a dedicated proxy tier — do not configure the agent to bind to 0.0.0.0.
For container deployments, run the agent in the same network namespace as the application (sidecar pattern). The 127.0.0.1 binding then scopes to the shared namespace.

​
Peer attestation

On Linux, the agent checks SO_PEERCRED on every new connection to retrieve the connecting process’s UID. If a UID allowlist is configured on the route and the connecting UID is not in the list, the connection is refused immediately before any bytes are read. On Windows, named pipes with an explicit ACL replace SO_PEERCRED. The behaviour is equivalent. If no UID allowlist is configured, any process on localhost can connect. Configure a UID allowlist in production environments where multiple users share the same host.

​
PostgreSQL

Auth method: ScramSHA-256
  1. Agent receives the client’s startup packet (protocol 3.0)
  2. Agent stores the requested database name and user field from the startup packet
  3. Agent opens TLS to the upstream PostgreSQL server
  4. Agent performs a full ScramSHA-256 handshake with the upstream server using KnoxCall credentials
  5. After AuthenticationOk, agent sends ReadyForQuery back to the application
  6. From this point, agent pipes bytes bidirectionally — no further inspection
The application’s own startup packet parameters (database, user, application_name) are forwarded to upstream where safe. The password field in PasswordMessage is never forwarded — the agent substitutes its own credentials. TLS modes:
ModeDescription
requireStrict TLS — upstream cert validated against system CA bundle + any custom CAs in KnoxCall
prefer (default)Try TLS first; fall back to plain TCP if the upstream doesn’t support it. Cert not validated.
disablePlain TCP — no TLS to upstream

​
MySQL

Auth method: CLIENT_PLUGIN_AUTH with caching_sha2_password or mysql_native_password
  1. Agent receives the client’s connection request (no auth info — MySQL initiates auth from server side)
  2. Agent opens TLS to upstream MySQL
  3. Agent responds to the server’s auth challenge using KnoxCall credentials
  4. After server sends OK_Packet, agent pipes bidirectionally
The agent negotiates CLIENT_SSL with the upstream server regardless of the application-to-agent TLS setting. The application always connects to 127.0.0.1 unencrypted; the agent always connects to upstream encrypted.

​
MongoDB

Auth method: SCRAM-SHA-256 via OP_MSG
  1. Agent receives the client’s isMaster / hello command
  2. Agent opens TLS to upstream MongoDB
  3. Agent performs SASL SCRAM-SHA-256 authentication using KnoxCall credentials
  4. After auth succeeds, agent pipes all subsequent OP_MSG frames bidirectionally
MongoDB connection strings in the application: mongodb://127.0.0.1:{port}/{dbname} — no username or password in the URI. For MongoDB Atlas clusters, the upstream address is the SRV hostname. The agent resolves SRV records and connects to the primary.

​
Redis

Auth method: AUTH command injection
  1. Agent accepts the TCP connection from the application
  2. Agent opens TLS to upstream Redis
  3. Before forwarding any application commands, agent sends AUTH username password (Redis 6+ ACL) or AUTH password (Redis 5 and below) using KnoxCall credentials
  4. After +OK, agent pipes all subsequent RESP frames bidirectionally
The application does not send any AUTH command — the agent has already authenticated. If the application sends an AUTH command, the agent intercepts it and returns +OK without forwarding (to prevent auth token leakage). For Redis Cluster, the agent connects to one seed node and supports MOVED / ASK redirects transparently.

​
TLS to upstream

The agent always connects to the upstream database over TLS, regardless of how the application connects to the agent. Certificate validation behaviour:
  • strict (default): certificate chain validated against the system CA bundle plus any custom CAs stored in KnoxCall PKI
  • skip_verify: validation disabled — only use for local development databases with self-signed certificates
  • mtls: agent presents a client certificate (stored as a KnoxCall certificate secret) during the TLS handshake

​
Telemetry

The agent emits migration.db_proxy_probe telemetry events to KnoxCall during the verification window. Each probe reports whether the upstream database is still being reached through the legacy credentials:
event_typeProbe type valuesoutcome values
migration.db_proxy_probedns_probe, tls_probe, connection_attempt, no_traffic_windowstill_reachable, nxdomain, connection_refused, tls_error, clean, unknown
Probe events are stored in the migration verification log (visible on the Migration Verification page) and inform the safe-to-delete verdict. They do not appear in the main Audit Logs.

Bucket B: Database migration

Setting up DB proxy routes for a migration

Migration verification

Probe results and safe-to-delete confirmation

KnoxCall agent

Agent installation and configuration

Certificate Authority

Store client certs for mTLS upstream connections