Lakera RedSDK

SDK Quickstart

The Lakera Red SDK (lakera-red-sdk) lets you run adversarial scans programmatically. Use it to integrate red teaming into CI/CD pipelines, test custom agent flows, or automate security assessments without the web UI.

The SDK uses a poll-based architecture — your client pulls attack messages from the Red API rather than receiving inbound calls. This means you don’t need to expose any endpoints or whitelist IPs. The SDK runs entirely within your network with only outbound HTTPS requests, avoiding the complexity of firewall rules, tunnels, or public-facing infrastructure that a webhook-based approach would require.

Prerequisites

Install

$npm install lakera-red-sdk

Run Your First Scan

1

Initialize the client

Create a LakeraRedClient with your API key and the Red API base URL.

1import { LakeraRedClient } from "lakera-red-sdk";
2
3const client = new LakeraRedClient({
4  apiKey: process.env.LAKERA_RED_API_KEY,
5  baseUrl: "https://red-webhooks.lakera.ai",
6});
2

Create a scan

Define what you want to test. The target name is reused across scans — if a target with that name already exists, the SDK uses it.

1const scan = await client.createScan({
2  name: "CI nightly security check",
3  target: "my-agent",
4  strategy: { name: "static" },
5  objectives: ["security.prompt-extraction.1", "safety.harmful-content.1"],
6  concurrency: 5,
7});
3

Handle attack sessions

The scan.run() method drives the scan. For each concurrent session, your handler receives adversarial prompts and submits your agent’s responses.

You can also follow the scan’s progress in the dashboard at https://red.lakera.ai/scans/<scanId>/progress.

1await scan.run(async (session) => {
2  try {
3    for await (const { attack, respond } of session) {
4      // Forward the attack to your agent
5      const reply = await myAgent.chat(attack);
6
7      // Send the response back to Red for evaluation
8      await respond(reply);
9    }
10  } finally {
11    // Clean up agent resources when the session ends
12    await myAgent.shutdown();
13  }
14});

Each session may contain multiple turns (especially with the crescendo strategy). The async iterator handles this naturally — just keep looping. The finally block ensures your agent is properly shut down once the session completes or errors out.

4

Retrieve results

Once run() completes, fetch the evaluated results.

1const results = await scan.getResults();
2console.log(`Ready: ${results.ready}`);
3console.log(`Issues found: ${results.results?.filter((r) => r.evaluation).length}`);

You can also write results directly to a file:

1const path = await scan.writeResults("./red-results.json");
2console.log(`Results saved to ${path}`);

Full Example

1import { LakeraRedClient } from "lakera-red-sdk";
2
3const client = new LakeraRedClient({
4  apiKey: process.env.LAKERA_RED_API_KEY,
5  baseUrl: "https://red-webhooks.lakera.ai",
6  logLevel: "info",
7});
8
9const scan = await client.createScan({
10  name: "Nightly security scan",
11  target: "my-chatbot",
12  strategy: { name: "crescendo", maxTurns: 15 },
13  objectives: [
14    "security.prompt-extraction.1",
15    "security.instruction-override.1",
16    "safety.harmful-content.1",
17  ],
18  concurrency: 3,
19});
20
21await scan.run(async (session) => {
22  try {
23    for await (const { attack, respond } of session) {
24      const reply = await myAgent.chat(attack);
25      await respond(reply);
26    }
27  } finally {
28    await myAgent.shutdown();
29  }
30});
31
32const results = await scan.getResults();
33await scan.writeResults("./red-results.json");
34
35const failures = results.results?.filter((r) => r.error);
36if (failures?.length) {
37  console.error(`${failures.length} objectives failed`);
38  process.exit(1);
39}

Next Steps