Skip to main content

Understanding the APIsec Hosted Agent

Some of your APIs are internal-only — reachable inside your network but not from the public internet, and so not from APIsec's cloud. To assess them for vulnerabilities, APIsec needs a secure way to reach them. The Hosted Agent is that path: it runs as a container inside your own network and executes scan traffic against APIs that have no public route, without exposing those APIs to the internet. The agent reaches out to APIsec; APIsec never reaches in. This page explains what the agent does, why it connects the way it does, and how a scan flows through it, so you can reason about its behavior and its trust boundary in your environment.

For the click-path to create, download, and manage an agent in the console, see Manage Hosted Agents.

What the agent does​

The Hosted Agent is the component that issues the actual HTTP requests against your target APIs during a scan. Because it runs inside your network, it can test APIs that a SaaS scanner cannot route to — internal services, APIs behind your perimeter, endpoints with no public DNS. Those endpoints are in scope for your API security posture even when they are unreachable from the internet.

The agent does not decide what to test. The platform generates the test traffic and hands the agent instructions — each carrying one or more fully-formed HTTP requests. The agent sends each request to your target API and returns the raw response. Test generation, attack logic, and result analysis all stay in the platform. This keeps the in-network component narrow: it holds no test-generation logic or scan configuration — it executes the requests it's given and reports what came back.

Why it connects outbound only​

The agent uses an outbound-only pull model. It opens an outbound HTTPS connection to APIsec and polls for work. The platform never opens a connection to the agent.

This is a deliberate design choice, and it means the agent adds no new inbound attack surface:

  • No inbound ports, no listener. In the mode you run in your network, the agent runs no HTTP server of its own. There is nothing to expose, firewall, or place behind a load balancer for APIsec to reach — so the agent itself is not a new externally reachable service. (A separate local test mode with a request/response endpoint exists for APIsec's own development; it is not part of a customer deployment.)
  • One outbound path. The agent needs outbound TCP 443 to the APIsec platform, and nothing inbound. Your target APIs stay entirely inside your network.
  • Your perimeter stays closed. Because every connection is agent-initiated, you scan your internal APIs without opening your perimeter to APIsec or to the public internet.
note

The agent needs outbound reachability to the APIsec platform on TCP 443 and a container runtime to run in — Docker on the standard install path, or your cluster's runtime on Kubernetes. The Docker install script checks the outbound path and the Docker engine before it starts the container.

How a scan flows through the agent​

Once the agent is running, work moves through it in a repeating cycle:

  1. Register. When the container starts, it reports in to the platform as ACTIVE, then begins polling.
  2. Poll for instructions. The agent asks the platform for the next instruction. Each agent record has its own dedicated instruction queue, keyed to the agent rather than to a particular container. If the queue is empty, the platform tells the agent there is nothing to do, and the agent waits before asking again.
  3. Execute. When an instruction contains requests to run, the agent sends them to your target APIs. It runs the requests in parallel and preserves each exact response — status, headers, and body — so the platform assesses what the endpoint actually returned.
  4. Return results. The agent sends the responses back to the platform, which files them against the scan they belong to.

After it receives work, the agent polls every second for a short window (about ten seconds) so a burst of instructions drains without waiting for the next cycle. When there is nothing to do, it falls back to a steady-state poll every five seconds. Alongside this loop, the agent sends a health heartbeat every five minutes so the console can show whether it is alive.

How the agent authenticates​

Every call the agent makes to the platform carries a broker token — a signed JWT issued when you download the install command. ("Broker" is the platform's internal name for the agent.) The token identifies the agent and its tenant, and the platform rejects any request whose token is missing, expired, or no longer current. Treat this token as a scoped machine credential: it authenticates one agent to the platform, nothing more.

Three properties matter for how you manage it:

  • Rotation is instant revocation. Each agent record tracks exactly one current token. When you rotate the token, the platform stops honoring the old one immediately — the previous token is refused the next time that agent calls. Rotation is your revocation lever if a token is exposed or an agent should be cut off. A running container does not pick up the new token on its own: after rotating, redeploy the agent with the newly downloaded install command.
  • Re-downloading does not cut off a running agent. Downloading the install command again for an agent whose token has not expired reuses the same token identity and carries a fresh 180-day expiry. The old token stays valid, so the running container keeps working and no rotation is recorded. Moving the agent onto the renewed expiry takes a redeploy with the re-downloaded command; because the old token still works, replicas can be redeployed one at a time.
  • Expiry is judged on the token presented. By default a broker token is valid for 180 days from the moment it is issued. Once the token an agent presents has expired the platform rejects its calls, so the agent can no longer poll and shows as unresponsive. The agent's diagnostics — run when the platform requests a health check — flag a token that is within a week of expiring.
  • Renewal by re-download has a deadline. A re-download reuses the existing token identity only while the agent's recorded expiry is still in the future, and reusing a token does not move that recorded date. Once it passes, the next download mints a new identity, which stops the token any running container is still using. Rotation does move the recorded date forward, at the cost of revoking the old token for every replica at once. See Upgrading and versions for the full sequence.
note

The install command embeds the broker token. Treat the command — and the token inside it — as a secret, and handle it with the same care as any other credential.

Reaching target APIs behind mTLS or a proxy​

Some internal APIs require mutual TLS. The agent can present a client certificate and trust a custom CA so a scan can authenticate to those targets. To use this, you turn certificate support on and mount the certificate files plus a small config file — which maps each target host to its certificates — into the container when you deploy the agent. Client certificates use PKCS12 format (.pfx or .p12); the .pem format is accepted only for the CA certificate. See Certificates for the configuration.

When the agent calls your target APIs it records the negotiated TLS version, cipher, and certificate chain alongside the response, so a scan can assess endpoints whose TLS configuration is out of date rather than skipping them.

If you route the agent's traffic through a proxy, note exactly what the proxy setting covers:

note

The proxy configuration applies to the agent's outbound calls to the APIsec platform. It does not apply to the agent's calls to your target APIs — those go direct. See Proxy for the settings.

Operating the agent over time​

The console reflects the agent through a small set of states:

  • PROVISIONED — the agent record exists but the agent has not yet reported in.
  • ACTIVE — the agent has reported in and is sending its health heartbeat. This is the state an agent reaches on startup and holds while it keeps checking in.
  • UNRESPONSIVE — an active agent stopped reporting. Because the agent heartbeats every five minutes, the platform waits until the last heartbeat is at least an hour old before marking the agent unresponsive, so a brief blip does not flip its state. The tradeoff: an agent that dies can still show ACTIVE until that hour elapses, so treat a stale-but-active agent with suspicion when you are monitoring for failures.
  • SHUTDOWN — the agent stopped gracefully.
  • DELETED — the agent has been deleted and its token revoked.

A few operational behaviors follow from this model:

  • Restart resilience. The container is configured to restart unless you stop it, and it keeps a small restart marker on a Docker volume across restarts. That volume holds coordination state, not your credentials — the token lives in the container's environment, where the install command sets it — so pruning the volume does not leak secrets, and the agent re-registers on the next start. If the platform tells the agent to restart, Docker brings it back automatically. (On Kubernetes, the pod's restart policy and an emptyDir volume play the same two roles.)
  • Deleting an agent. You cannot delete an agent while it is active; stop it first (a shutdown or unresponsive agent can be deleted). Deleting an agent revokes its token immediately, so it cannot rejoin if its container later restarts, and then cleans up its queue and records in the background.

Scaling with replicas​

The agent's identity is its token and its instruction queue, not a particular container. You can run more than one container with the same token: each container — a replica — polls the same queue, each instruction goes to exactly one of them, and scan work load-balances across all of them. More replicas mean more test requests executing in parallel. The replicas need no knowledge of each other and no extra configuration. See Scale with replicas for how to add replicas and what to expect in the console.

What runs where​

The trust boundary matters when you reason about exposure and failures:

  • In your network: the agent container. It needs outbound TCP 443 and a container runtime to host it, and nothing inbound. It holds one credential — the broker token — and executes requests the platform sends it.
  • In the APIsec cloud: the management and data services the agent talks to — the instruction queue, result storage, token issuing and validation, and the dashboard signals. You do not operate any of these.

Most connectivity problems you will see come from the agent's one dependency: outbound TCP 443 to the platform. If an agent goes unresponsive, that path, its token, and the container runtime are the first things to check.

See also​