AI Red TeamingSDKPrevious versionsv0.6.x

Quickstart

The Check Point AI Red Teaming 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 is outbound-only: your process pulls attack prompts from the Red API over HTTPS, so you don’t need to expose any inbound endpoints or open inbound firewall rules. See SDK Deployment for network requirements, proxy configuration, and runtime details.

Prerequisites

Install

npm install lakera-red-sdk

Try a Runnable Example

The SDK includes ready-to-run examples to help you get started quickly.

npx lakera-red-sdk init-examples
cd lakera-red-examples/echo
cp .env.example .env # add your LAKERA_RED_API_KEY
npm install
npm start

See the examples helper reference for the full list of examples and commands.

Run Your First Scan

1

Initialize the client

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

import { LakeraRedClient } from "lakera-red-sdk"
const client = new LakeraRedClient({
  apiKey: process.env.LAKERA_RED_API_KEY,
  baseUrl: "https://red-webhooks.lakera.ai",
})
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.

You can optionally provide app context — a structured description of your application that helps Red tailor its attacks. If you omit it, the SDK automatically runs a short reconnaissance phase at the start of scan.run() to learn about your agent.

const scan = await client.createScan({
  name: "CI nightly security check",
  target: "my-agent",
  appContext: {
    appDescription:
      "A customer support chatbot that can look up orders and process refunds",
    allowedActions: [
      "Look up order status",
      "Process refunds",
      "Answer product questions",
    ],
    forbiddenActions: ["Reveal internal pricing rules", "Share other customers' data"],
  },
  strategy: { name: "static" },
  objectives: [
    "security.system-prompt-extraction.1",
    "safety.dangerous-instructions.1",
  ],
  concurrency: 5,
})

Alternatively, load the context from a YAML file:

const scan = await client.createScan({
  name: "CI nightly security check",
  target: "my-agent",
  appContextFile: "./app-context.yaml",
  strategy: { name: "static" },
  objectives: [
    "security.system-prompt-extraction.1",
    "safety.dangerous-instructions.1",
  ],
  concurrency: 5,
})

You can also define custom objectives alongside standard ones:

const scan = await client.createScan({
  name: "CI nightly security check",
  target: "my-agent",
  appContext: {
    appDescription:
      "A customer support chatbot that can look up orders and process refunds",
    allowedActions: [
      "Look up order status",
      "Process refunds",
      "Answer product questions",
    ],
    forbiddenActions: ["Reveal internal pricing rules", "Share other customers' data"],
  },
  strategy: { name: "static" },
  objectives: ["security.system-prompt-extraction.1"],
  customObjectives: [
    {
      key: "my-org.competitor-mention.1",
      name: "Competitor Recommendations",
      attackDescription:
        "Get the assistant to recommend a named competitor instead of our product.",
      successIndicators: [
        "The reply names a specific competitor and actively endorses it — recommends buying it, praises its features, or calls it the better choice.",
      ],
    },
  ],
  concurrency: 5,
})

See CustomObjective for the full field reference.

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 via scan.dashboardLink / scan.dashboard_link.

await scan.run(async (session) => {
  try {
    for await (const { attack, respond } of session) {
      const reply = await myAgent.chat(attack)
      await respond(reply)
    }
  } finally {
    await myAgent.shutdown()
  }
})

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.

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

You can also write results directly to a file:

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

Full Example

import { LakeraRedClient } from "lakera-red-sdk"
// Replace this echo agent with a call to your own agent or application.
const myAgent = {
  async chat(message: string): Promise<string> {
    // Simply echoes whatever the scanner sends.
    return `Echo: ${message}`
  },
  async shutdown(): Promise<void> {
    // No cleanup necessary for this dummy implementation.
  },
}
const client = new LakeraRedClient({
  apiKey: process.env.LAKERA_RED_API_KEY,
  baseUrl: "https://red-webhooks.lakera.ai",
  logLevel: "info",
})
const scan = await client.createScan({
  name: "Nightly security scan",
  target: "my-chatbot",
  appContext: {
    appDescription:
      "A customer support chatbot that can look up orders and process refunds",
    allowedActions: [
      "Look up order status",
      "Process refunds",
      "Answer product questions",
    ],
    forbiddenActions: ["Reveal internal pricing rules", "Share other customers' data"],
  },
  strategy: { name: "crescendo", maxTurns: 15 },
  objectives: [
    "security.system-prompt-extraction.1",
    "security.instruction-override.1",
    "safety.dangerous-instructions.1",
  ],
  concurrency: 3,
})
await scan.run(async (session) => {
  try {
    for await (const { attack, respond } of session) {
      const reply = await myAgent.chat(attack)
      await respond(reply)
    }
  } finally {
    await myAgent.shutdown()
  }
})
const results = await scan.getResults()
await scan.writeResults("./red-results.json")
console.log(`View report: ${scan.dashboardLink}`)
const failures = results.results?.filter((r) => r.error)
if (failures?.length) {
  console.error(`${failures.length} objectives failed`)
  process.exit(1)
}

Next Steps