Endpoint Scans

Endpoint scans exercise an agent through an HTTPS contract. Prefer runtime scans for application code and CI because they preserve complete tool traces and local framework behavior.

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"],
      },
    },
  ],
});

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, messageField, messagesField, and sessionField can map values into a generated JSON object.

Response parsing

Set responseField to a dot-separated path such as data.answer. toolCallsField, finishReasonField, and usageField can map structured traces from the same response. Without responseField, the scanner checks common fields including text, answer, output, content, and message, then falls back to the raw body.

Run a scan

const result = await zeroleaks.endpointScans.run(configId, {
  onPoll: ({ scan }) => console.log(scan.currentPhase),
});

console.log(result.report?.overallScore);

agentConfigs and agentScans remain available as compatibility aliases. New code should use endpointConfigs and endpointScans.

Authenticated endpoints must use HTTPS. Credentials are encrypted at rest and never returned by list or get operations. Only scan systems you own or are authorized to test.