Endpoint scans
Scan an already-deployed HTTP agent when an in-process runtime target is not available.
An endpoint scan exercises an agent through its HTTPS contract. ZeroLeaks sends each probe to your endpoint, and your agent runs its own model and tools. Prefer runtime scans for application code and CI because they capture complete tool traces and local framework behavior.
Only scan systems you own or are authorized to test.
Register an endpoint
const { id: configId } = await zeroleaks.endpointConfigs.create({
name: "Production support endpoint",
endpointUrl: "https://api.example.com/agent",
authMethod: "bearer",
authValue: process.env.PRODUCTION_AGENT_TOKEN,
requestFormat: {
method: "POST",
headers: { "X-Agent-Version": "production" },
bodyTemplate:
'{"message":{{message}},"messages":{{messages}},"sessionId":{{sessionId}}}',
responseField: "data.answer",
toolCallsField: "data.toolCalls",
finishReasonField: "data.finishReason",
usageField: "data.usage",
},
tools: [
{
name: "lookup_customer",
description: "Read customer profile data",
inputSchema: {
type: "object",
properties: { id: { type: "string" } },
required: ["id"],
},
},
],
});authMethod controls how authValue is sent:
authMethod | Header |
|---|---|
none | No auth header |
bearer | Authorization: Bearer <authValue> |
api_key | X-API-Key: <authValue> |
custom_header | <authHeaderName>: <authValue> |
Authenticated endpoints must use HTTPS. Credentials and planted canaries are encrypted at rest and never returned by list or get operations; reads return authValueConfigured and plantedSecretConfigured instead.
tools declares what the agent can call. ZeroLeaks uses the definitions to profile the agent and plan probes; it does not call them.
Set an optional plantedSecret to test for context disclosure. See plant a canary.
Format the request
Placeholders in bodyTemplate are JSON-encoded automatically:
| Placeholder | Value |
|---|---|
{{message}} or the older {{prompt}} | Current probe |
{{messages}} | Current isolated conversation history |
{{sessionId}} | Stable scan session identifier |
Without bodyTemplate, ZeroLeaks generates a JSON object from these requestFormat options:
| Option | Behavior |
|---|---|
messageField | Field for the probe. Defaults to message. |
messagesField, sessionField | Add the history and session ID |
attachmentsField | For agents that accept file uploads. Artifact probes send real PDF, image, HTML, and spreadsheet files there as [{ filename, mediaType, dataBase64 }]. Without it, or with a bodyTemplate or method: "GET", the file's text is pasted into the message. |
With method: "GET", the probe and session ID are sent as query parameters.
Parse the response
Set responseField to a dot-separated path such as data.answer. If that path is missing from a response, the response is treated as an error instead of scoring the raw body. Without responseField, the scanner checks text, answer, output, content, and message, then falls back to the raw body. Responses are truncated at 100,000 characters.
toolCallsField, finishReasonField, and usageField map structured traces from the same response. Without toolCallsField, a top-level toolCalls array is read if present. Return observed tool calls when available: an executed tool call is stronger evidence than a response that only describes one.
Contain tools behind your endpoint
Your endpoint runs its own tools, so ZeroLeaks can't stop a tool call there. It rewrites attacker destinations in every probe to the canary.zeroleaks.invalid sink before sending, and every scan request carries the header X-ZeroLeaks-Scan: contained.
Use that header to put side-effecting tools in dry-run mode for the request: let the agent call them, return a simulated result, and skip the write, payment, or message. Keep returning the call in toolCalls so the report still shows what the agent tried. Read-only tools can stay live. The SDK's containment policy works inside your endpoint too:
import { resolveToolContainment, runContainedTool } from "@zeroleaks/sdk";
const policy =
request.headers.get("x-zeroleaks-scan") === "contained"
? resolveToolContainment({ allowedHosts: ["api.acme.com"] })
: null; // live traffic: no containment
// In your tool loop, around each call:
const result = await runContainedTool(name, args, () => execute(args), policy);If you can't change the endpoint, point the scan at a staging deployment, or run a runtime scan, where the SDK contains tool calls for you.
Run a scan
const result = await zeroleaks.endpointScans.run(configId, {
onPoll: ({ scan }) => console.log(scan.currentPhase),
});
console.log(result.report?.overallScore);
console.log(result.report?.components);Endpoint scans take no scan options. Every endpoint scan runs full coverage: reconnaissance, secrets in context, injection, and agent-specific probes including the production catalog. See reports for the report fields.
Manage configurations
const { configs } = await zeroleaks.endpointConfigs.list();
await zeroleaks.endpointConfigs.update(configId, {
...endpointConfig, // the full configuration, without authValue
endpointUrl: "https://api-v2.example.com/agent",
});
await zeroleaks.endpointConfigs.delete(configId);update() is a partial update: send only the fields you want to change. Omitted fields, including authValue and plantedSecret, keep their stored values. requestFormat is merged key by key, and requestFormat.headers is replaced as a whole when you send it. Send plantedSecret: "" to clear the canary. Switching authMethod to none clears the stored credential.
agentConfigs and agentScans remain available as compatibility aliases. New code should use endpointConfigs and endpointScans.