> ## 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
> Technical reference for the KnoxCall agent's localhost database proxy — supported protocols, peer attestation, TLS handling, and wire-level details.
# 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
```text theme={"dark"}
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**:
| Mode | Description |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `require` | Strict 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. |
| `disable` | Plain 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_type` | Probe type values | `outcome` values |
| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `migration.db_proxy_probe` | `dns_probe`, `tls_probe`, `connection_attempt`, `no_traffic_window` | `still_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.
Setting up DB proxy routes for a migration
Probe results and safe-to-delete confirmation
Agent installation and configuration
Store client certs for mTLS upstream connections