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. 
curl -sSfL https://knoxcall.com/agent/install.sh | bash -s -- \
  --agent-id=kc_agent_xxx \
  --agent-secret=yyy \
  --mode=intercept

​
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:
ModePurpose
controlDefault. Persistent WebSocket to control plane; executes commands dispatched from the admin UI
proxyFull proxy data plane (self-hosted / knoxcall/proxy container)
interceptLong-running local MITM listener on localhost:7742
onboardOne-shot AI-powered codebase scanner for discovering API calls + secrets
scanOne-shot hardcoded-credential scanner (walks filesystem, env vars, TCP connections)
doctorOne-shot connectivity and config sanity check

​
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. 
KNOXCALL_AGENT_ID=kc_agent_xxx \
KNOXCALL_AGENT_SECRET=yyy \
knoxcall-agent intercept
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.