Skip to Content
ZeroLeaksDocs
ZeroLeaks SDK

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:

authMethodHeader
noneNo auth header
bearerAuthorization: Bearer <authValue>
api_keyX-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:

PlaceholderValue
{{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:

OptionBehavior
messageFieldField for the probe. Defaults to message.
messagesField, sessionFieldAdd the history and session ID
attachmentsFieldFor 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.

On this page