Skip to main content

​
Go Client Agent

The Go agent runs next to your app as an HTTP(S) forward proxy on localhost:7742. It intercepts outbound calls to your KnoxCall-configured routes and transparently rewrites them through the KnoxCall data plane — no code changes, no base URL swap.

​
When to Use It

  • Your app is on infrastructure where changing DNS records is awkward (serverless runtimes with cached DNS, managed platforms, BYOD-host environments).
  • You can’t modify the SDK’s base URL (vendor SDK that hardcodes production hosts).
  • You want a drop-in ZTNA-style proxy without code changes.
If you can change base URLs, direct routing is simpler and faster — skip the agent.

​
Install

Generate agent credentials under Automation → Agents first, then install on each host that runs your app.

​
How Interception Works

The agent generates a local CA certificate on first run and installs it in the system trust store. For every outbound HTTP(S) request:
  1. The app’s OS/SDK HTTP proxy setting points at localhost:7742.
  2. The agent inspects the target host.
  3. Matched routes (host is a registered KnoxCall route target) → MITM the TLS handshake with a locally-signed certificate, rewrite to the KnoxCall proxy URL with auth headers attached.
  4. Unmatched → pass-through unchanged; the agent never sees non-KnoxCall traffic.
Your app code sees KnoxCall responses as if they came directly from the target API.

​
Modes

The same binary runs in six modes depending on the positional argument:

​
Database Proxying

Database proxying is a capability of the long-running intercept (and control) modes — there is no separate positional mode for it. When the session bundle includes database routes, the agent binds one TCP listener per configured route on 127.0.0.1. Applications connect to 127.0.0.1:{port} as if connecting to the database directly — the agent handles all authentication to the upstream database and pipes the connection through. This is used as part of Secret Store Migration Bucket B to migrate database credentials from cloud secret stores (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) into KnoxCall with zero credential exposure.
The agent reads its database route configuration from the KnoxCall session bundle (pushed from the control plane). Each route specifies: protocol (postgres/mysql/mongodb/redis/sqlserver), local port, upstream host/port, and credential secret reference. See Agent database proxy protocols for wire-level details on each supported protocol.

​
Tamper Seal

Every agent binary ships with a build_sig — an HMAC-SHA256 of the binary hash signed with a CI-only secret. The control plane validates this signature on every session fetch and refuses sessions for unknown builds in strict mode (KNOXCALL_STRICT_TAMPER_CHECK=true). In the default alert-only mode, unknown builds still get sessions but raise a visible warning in the admin UI. This means a modified agent binary cannot simply reuse captured credentials — the control plane recognises it as foreign and refuses to issue the session key.

​
Operational

  • Heartbeat: every 60 seconds. Missing for >2 min = stale, >10 min = offline. Visible in Automation → Agents.
  • Session renewal: in intercept mode the agent renews its bundle via /agent/v1/session/renew on the control plane, at the next_renew_at time returned in each bundle (typically before the ~1-hour session expiry). (The self-hosted proxy container instead re-fetches via /agent/v1/session on its own ~hourly cycle — see Self-Hosted Proxy.)
  • Credential rotation: regenerate the agent secret from the Agents admin page and restart the agent — there is no downtime if you rotate before the old session expires.
  • Revocation: revoking from the admin UI takes effect on the next session-renewal cycle (within ~5 minutes).

​
Agent Detail Page

The Automation → Agents → detail page shows:
  • Identity & heartbeat state
  • 7-day route activity (requests intercepted per route)
  • Tamper events (if any build_sig verifications failed)
  • Revoke action

​
Troubleshooting

  • “Certificate trust errors”: the local CA didn’t install. Re-run knoxcall-agent install-ca with admin/root.
  • “Connection refused on localhost:7742”: agent crashed or exited. Check journalctl -u knoxcall-agent (Linux) or the Event Viewer (Windows).
  • “Session denied, tamper detected”: the running binary’s build_sig isn’t in agent_versions. Download a fresh official binary.