# ZeroLeaks Developer Context Continuous red teaming for AI agents: hosted scans attack a deployed agent's tools, memory, and context and report what an attacker could make it do. ## Product Selection Use @zeroleaks/sdk for hosted red teaming of AI agents. Runtime scans relay probes to the developer's local AI SDK, OpenAI, or custom agent and record complete tool calls and results. Endpoint scans attack a deployed HTTPS agent, which runs its own tools. The SDK also supports agent-skill scans, reports, polling, and cancellation. Hosted prompt scans are retired; scan a standalone prompt locally with the zeroleaks CLI. Use @zeroleaks/shield inside an LLM application's runtime request path. It hardens system prompts, detects prompt-injection patterns, sanitizes leaked prompt fragments, and wraps common model providers. Its core checks run locally and do not require a ZeroLeaks API key: hardening, output scanning, and tool policy checks always run in process, and injection detection runs in process through the @zeroleaks/shield/local export. The default detect export calls the hosted Shield API instead. Use the zeroleaks package and CLI when scans must run locally or the developer needs direct control over attack agents, probes, knowledge, and orchestration. It is also the place for local system-prompt extraction tests. It uses the developer's own OPENROUTER_API_KEY or OPENAI_API_KEY, or any OpenAI-compatible endpoint through --base-url, rather than a ZeroLeaks API key. ## When to use ZeroLeaks Use runtime scans to test your production agent after changes to tools, memory, credentials, or connected agents. Use endpoint scans for deployed HTTPS agents, skill scans for third-party skills and manifests, and Shield for runtime injection detection. Call the hosted scan API from a server process with an API key and an active scan plan. Read the [agent instructions](https://zeroleaks.ai/agent-instructions.md) for scan selection, safe tool dependencies, persistent workflow IDs, and retry rules. ## Hosted SDK Setup Install @zeroleaks/sdk and set: ZEROLEAKS_API_KEY=zl_live_... Initialize: import { ZeroLeaks } from "@zeroleaks/sdk"; const zeroleaks = new ZeroLeaks(); The API key is a server credential. Do not place it in browser bundles, NEXT_PUBLIC_ variables, mobile apps, repositories, or logs. ## Production Runtime Workflow Wrap the existing production agent with createRuntimeTarget(), @zeroleaks/sdk/ai-sdk, or @zeroleaks/sdk/openai. Then call runtimeScans.run(target). The SDK sends only serializable target metadata and complete tool definitions to ZeroLeaks. Model keys, executable tool functions, memory, and local state stay in the runner environment; retrieved data reaches ZeroLeaks only when a tool returns it in a traced tool result. Each invoke/reset relay event is executed through the real target. The SDK preserves session history and submits final text plus observed tool arguments, results, errors, and provider execution state. All configured tools are included by default. Use scan-safe databases, tenants, email sinks, payment sandboxes, and credentials for irreversible side effects while preserving the same authorization and approval logic as production. AI SDK supports existing Agent objects or ToolLoopAgent settings. OpenAI supports Responses API and Chat Completions function-tool loops. Custom orchestration should use createRuntimeTarget() so the production handler is invoked exactly. Runtime scan modes are full (default) and quick. Full covers every attack surface, includes the production probe catalog, and ignores attackSurfaces. Quick skips the catalog and honors attackSurfaces, knowledgeProfile, and maxAdaptiveCandidates. ## What an Agent Scan Does Runtime and endpoint scans run the same stages: 1. Reconnaissance: three short questions about the agent's tasks, tools, and rules. The answers and declared tools feed a target profile. 2. Three tracks in parallel: secrets in context, prompt injection, and agent probes derived from boundary invariants (authorization, data access, network egress, tool use, human approval, memory, cross-agent trust), including multi-turn campaigns and the production probe catalog. 3. A panel of judge models scores the results. Observable effects, such as a real tool call or an echoed canary, outweigh replies that only sound compliant. 4. The report has overallScore (0-100, higher is safer), overallVulnerability, components (promptSecurity, toolSafety, multiTurnResilience, dataLeakage), findings, recommendations, conversationLog, boundaryAssurance, and containment. Runtime reports add toolTrace and target. The secrets-in-context track replaced the system-prompt extraction loop in agent scans. It scores by what leaked: credential (critical), planted_canary (high), authorization_rule (high), internal_endpoint (medium), tool_schema (medium), instruction_text (informational, no score penalty). Its summary is at report.boundaryAssurance.secretsInContext. Judge-only leak claims whose quoted span did not verify stay in the findings with claimedSpan "" and do not affect the score. boundaryAssurance also carries invariants, verificationCases, attackQuality (success rates and attack-surface coverage), longHorizonCampaigns, strategy (the reconnaissance, escalation, and persistence phase plan), fingerprint (the defenses observed, reused by the next scan of the same target in the same account), and searchTree (the bounded attack-path search: every path explored or pruned, with the reason). A scan does not rerun exploits against a fixed agent. The next scan runs the same attacks again. Outbound attack payloads are rewritten so external URLs, email addresses, and reverse-shell targets point at canary.zeroleaks.invalid. Loopback and cloud-metadata addresses are left in place. The agent's own tools still execute, so use scan-safe dependencies. ## Endpoint Scan Workflow 1. Create an endpoint configuration with endpointConfigs.create() or POST /api/v1/agent-configs. 2. Start a scan with endpointScans.create(configId) or POST /api/v1/agent-scans. 3. Poll endpointScans.get() or GET /api/v1/agent-scans/{scanId}. The report is on the scan result. 4. Cancel through endpointScans.cancel() when needed. Supported target auth modes are none, bearer (Authorization: Bearer), api_key (X-API-Key header), and custom_header. Authenticated targets require HTTPS. Request formats support custom headers, message/history/session fields, JSON-safe templates, and nested response and tool-call fields. Target credentials are encrypted and omitted from API reads. An endpoint configuration can include plantedSecret: a write-only canary (8-200 characters, must contain a digit or separator) that the developer also puts in the agent's system prompt. If a scan gets it back, the report records a planted_canary leak without storing the value. Reads return plantedSecretConfigured. On update, omit the field to keep it or send an empty string to clear it. PATCH is a partial update: omitted fields keep their stored values. Endpoint scans take no scan options and always run full coverage. ## Prompt Scan Workflow Hosted prompt scans are retired. POST /api/v1/scans and scans.create()/scans.run() return 410 Gone with code PROMPT_SCANS_RETIRED. Historical prompt scans remain readable through scans.get(), scans.list(), scans.wait(), GET /api/v1/scans/{scanId}, GET /api/v1/reports/by-scan/{scanId}, and POST /api/v1/scans/{scanId}/cancel. To scan a standalone prompt, install the source-available (FSL) engine with npm i -g zeroleaks. For hosted coverage, use the runtime, endpoint, or skill scan workflows instead. ## Skill Scan Workflow Use skillScans.run({ source }) for remote sources, or skillScans.uploadArchive() for ZIP uploads. To scan an MCP server, pass its Streamable HTTP URL with sourceType: "mcp" (and mcpAuthorization if it needs a token): ZeroLeaks connects as an MCP client, lists tools, prompts, resources, and instructions without calling any tool, checks them for tool poisoning, hidden characters, shadowing, and misleading annotations, and reports tool definitions that changed since the previous scan of the same server. Async scans return scanId and can be polled through skillScans.get() or skillScans.wait(). Sync delivery returns the report in the create response. Skill scan modes are review, risk, behavior, and full. Tool profiles are readonly, standard, and networked. ## Error Policy - 400: fix the named validation error before retrying. - 401: replace the missing, invalid, or revoked API key. - 403 (code SUBSCRIPTION_LIMIT): no active paid plan, trial scans used up, or inactive workspace. - 404: verify the resource ID and API-key owner. - 410 (code PROMPT_SCANS_RETIRED): prompt-scan creation is retired. Do not retry; use a runtime or endpoint scan. - 429: SCAN_CONCURRENCY_LIMIT or SCAN_HOURLY_LIMIT when the plan's concurrent or hourly scan cap is reached (the message says when to retry), or "Rate limit exceeded" with a reset time for the hourly abuse ceiling. Scans are otherwise unlimited on paid plans. - 500 or 503: retry later with bounded backoff. Do not automatically retry scan-creation POST requests because they are not idempotent. ## Public MCP resources The read-only MCP endpoint is https://zeroleaks.ai/mcp (Streamable HTTP, stateless, JSON responses). Initialize with protocol version 2025-11-25, send notifications/initialized, then resources/list and resources/read. No key is needed for public documentation resources. See https://zeroleaks.ai/docs/api-reference/mcp. ## Resources - Docs: https://zeroleaks.ai/docs - SDK: https://zeroleaks.ai/docs/sdk - Shield: https://zeroleaks.ai/docs/shield-sdk - Local package: https://zeroleaks.ai/docs/zeroleaks-package - OpenAPI: https://zeroleaks.ai/openapi.json - Authentication: https://zeroleaks.ai/docs/api-reference/authentication - Webhooks: https://zeroleaks.ai/docs/api-reference/webhooks - Agent instructions: https://zeroleaks.ai/agent-instructions.md - Short context: https://zeroleaks.ai/llms.txt