ZeroLeaks SDK
Run hosted red-team scans against the exact agent, models, tools, memory, and middleware used by your application.
@zeroleaks/sdk connects the hosted ZeroLeaks attack engine to your application code. Runtime scans send every probe through your agent while the SDK maintains conversation state and records observed tool calls and results.
Version 0.2.2 makes the complete production probe catalog the default for runtime scans, runs isolated sessions concurrently, and detects stalled hosted workers.
Version 0.3.0 adds types for the remaining agent report fields: component findings, the secrets-in-context summary, defense fingerprints, campaign state, and the attack-path search tree. It also adds plantedSecret to endpoint configurations and deprecates scans.create and scans.run. Both methods reject with PROMPT_SCANS_RETIRED because hosted prompt scans are retired.
components names its four components instead of using Record<string, unknown>, and boundaryAssurance is typed instead of unknown. Handwritten test reports must include all four components and every required boundaryAssurance field. To cast boundaryAssurance to your own interface, cast through unknown. Upgrade with bun add @zeroleaks/sdk@^0.3.0.
Version 0.4.0 moves the optional AI SDK adapter to AI SDK 7: it needs ai@^7, and aiSdk() accepts AI SDK 7's runtime-context type. Projects still on AI SDK 6 should stay on 0.3.x. Upgrade with bun add @zeroleaks/sdk@^0.4.0.
import { ZeroLeaks, createRuntimeTarget } from "@zeroleaks/sdk";
const zeroleaks = new ZeroLeaks();
const target = createRuntimeTarget({
definition: {
name: "Production support agent",
provider: "custom",
tools: productionToolDefinitions,
},
invoke: ({ messages, sessionId, signal }) =>
runProductionAgent({ messages, sessionId, signal }),
reset: (sessionId) => resetAgentSession(sessionId),
});
const { report } = await zeroleaks.runtimeScans.run(target);
console.log(report.overallScore, report.toolTrace);Choose a scan path
| Path | Best for | What ZeroLeaks exercises |
|---|---|---|
| Runtime scans | Application code, CI, staging | Your real model configuration, instructions, memory, middleware, tools, and execution loop |
| AI SDK adapter | AI SDK Agent or ToolLoopAgent | Full AI SDK tool schemas, executions, results, and multi-turn state |
| OpenAI adapter | Responses API or Chat Completions | Native OpenAI request settings and local function-tool execution |
| Endpoint scans | Already-deployed HTTP agents | Production HTTP contract, authentication, response parsing, and declared tools |
zeroleaks CLI | A system prompt before an application exists | Local prompt scanning with your own model-provider credentials (the hosted version is retired) |
| Skill scans | Agent skills and manifests | Static and behavioral analysis of repositories, URLs, or ZIP archives |
What an agent scan does
Runtime and endpoint scans run the same stages:
- Reconnaissance and profiling. Three short questions to the agent plus your tool definitions produce a profile of its role, tools, reachable data, and trust boundaries.
- Three attack tracks in parallel:
- secrets in context: does the agent leak credentials, rules, tool schemas, internal hosts, or a canary you planted;
- prompt injection;
- agent probes derived from the profile, covering boundaries such as authorization, data access, network egress, tool use, human approval, memory, and cross-agent trust, plus multi-turn campaigns and the production probe catalog.
- Judging. A panel of judge models scores the results. An observable effect, such as a real tool call or an echoed canary, counts for more than a reply that only sounds compliant.
- Report. Scores, findings, evidence, and recommendations. See reports.
A scan does not rerun exploits against a fixed version of your agent. After you apply a fix, the next scan repeats the attacks to check whether the fix holds.
Production fidelity
Runtime scans use a relay protocol. The attack engine creates a probe, your SDK process claims it, and the SDK calls your target locally. Model and tool credentials never have to be sent to ZeroLeaks, and the target does not need a public URL.
The SDK automatically:
- keeps reconnaissance, secrets-in-context, injection, and agent-probe sessions separate;
- runs the complete production probe catalog by default;
- executes independent sessions concurrently while keeping each multi-turn session in order;
- resets state when the engine starts a new conversation;
- passes the full conversation history to every invocation;
- includes all configured tools by default;
- preserves complete input and output schemas;
- records tool arguments, results, failures, and provider-executed calls;
- handles polling, stalled-worker detection, cancellation, abort signals, and report retrieval.
Package design
- Node.js 18+ and Bun 1+
- ESM and CommonJS
- Typed errors and API responses
- Optional peer integrations for
aiandopenai - MIT-licensed SDK; hosted orchestration and attack intelligence remain server-side