Runtime Scans

Runtime scans provide the highest-fidelity integration. Instead of approximating an agent from a system prompt or calling a limited HTTP shape, ZeroLeaks invokes a local RuntimeScanTarget through an authenticated relay.

Target contract

interface RuntimeScanTarget {
  describe(): RuntimeTargetDefinition | Promise<RuntimeTargetDefinition>;
  invoke(input: RuntimeTargetInvocation):
    | string
    | RuntimeTargetResponse
    | Promise<string | RuntimeTargetResponse>;
  reset?(sessionId: string): void | Promise<void>;
}

invoke() receives:

• message: the current attack prompt;
• messages: complete history for this isolated session;
• sessionId: stable across a multi-turn sequence;
• signal: cancellation and timeout signal;
• scan and event identifiers for logging or correlation.

Structured responses

Return text alone or a structured response:

return {
  text: result.text,
  messages: result.messages,
  finishReason: result.finishReason,
  usage: result.usage,
  toolCalls: result.toolCalls.map((call) => ({
    id: call.id,
    name: call.name,
    arguments: call.arguments,
    result: call.result,
    error: call.error,
    providerExecuted: call.providerExecuted,
  })),
};

When messages is omitted, the SDK appends the returned text as an assistant message. Return the complete post-invocation history when your framework emits tool and assistant messages that must be retained for later turns.

Relay lifecycle

• The SDK polls only while runtimeScans.run() is active.
• Invoke and reset events are claimed so two runners cannot normally execute the same event.
• Independent sessions execute concurrently by default, while events within each session stay ordered.
• Abandoned claims become available again after a short lease.
• A target invocation has a bounded server wait; runner errors are attached to the scan.
• The hosted scan uses durable stages: target profiling, checkpointed extraction, injection, agent probes, and report finalization. Independent scan tracks run in parallel.
• Aborting, timing out, or detecting a stalled hosted worker cancels the run instead of leaving it indefinitely marked as running.

Use eventConcurrency to tune local execution when your target has stricter rate limits:

await zeroleaks.runtimeScans.run(target, {
  eventConcurrency: 4,
  workerStallTimeoutMs: 6 * 60_000,
  scan: { scanMode: "full" },
});

full is the default runtime scan mode. It combines extraction, adaptive injection, the complete production probe catalog, and target-specific probes. quick omits the additional production catalog and is intended for development smoke tests.

Existing target objects

Use defineRuntimeTarget() when your application already implements the interface:

const target = defineRuntimeTarget(myTarget);
await zeroleaks.runtimeScans.run(target);

Use createRuntimeTarget() when wrapping functions and metadata separately.