Endpoint Scans

Endpoint scans exercise 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.

Register an endpointCopy Anchor Link

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:

Template placeholders are JSON-encoded automatically:

• {{message}} or legacy {{prompt}}: current probe;
• {{messages}}: current isolated conversation history;
• {{sessionId}}: stable scan session identifier.

When bodyTemplate is omitted, the probe goes in messageField (default message), and messagesField and sessionField can add the history and session ID to the generated JSON object. With method: "GET", the probe and session ID are sent as query parameters.

tools declares what the agent can call. ZeroLeaks uses the definitions to profile the agent and plan probes; it does not call them.

Use an optional plantedSecret to test for context disclosure. Put the same value in your agent's system prompt; the report records whether the agent returned it. See plant a canary.

Response parsingCopy Anchor Link

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. toolCallsField, finishReasonField, and usageField map structured traces from the same response; without toolCallsField, a top-level toolCalls array is read if present. 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.

Return observed tool calls when available. An executed tool call provides stronger evidence than a response that only describes one.

Run a scanCopy Anchor Link

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 shape.

Manage configurationsCopy Anchor Link

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() replaces the whole configuration, so send every field you want to keep, including requestFormat and tools. The exceptions are authValue and plantedSecret: omit them to keep the stored values. 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.

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. Only scan systems you own or are authorized to test.