Lakera Red SDK

Official TypeScript SDK for Lakera Red — run adversarial scans against your AI agents from your own runtime.

Lakera is a Check Point company.

Install

npm install lakera-red-sdk

Quick start

import { LakeraRedClient, type Session } from "lakera-red-sdk"

const client = new LakeraRedClient({
  apiKey: process.env.LAKERA_RED_API_KEY!,
  baseUrl: process.env.LAKERA_RED_URL!,
  logLevel: "info",
})

const scan = await client.createScan({
  target: "My Agent",
  name: "Example scan",
  concurrency: 3,
  strategy: "static",
  objectives: ["safety.hate-speech.1"],
})

await scan.run(async (session: Session) => {
  for await (const { attack, respond } of session) {
    const reply = await yourAgent(session.id, attack)
    await respond(reply)
  }
})

await scan.writeResults("./results.json")

Key concepts

| Concept | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Target | A named configuration representing the system under test. Created once, reused across scans. | | Session | A multi-turn conversation. The SDK manages lifecycle; your handler receives an async iterator of { attack, respond } pairs. | | Strategy | static = independent single-turn probes (fast). crescendo = adaptive multi-turn attacks. smoke = canned probe set. | | Concurrency | How many sessions run in parallel. For crescendo, automatically capped to the number of objectives. |

Multi-turn sessions with cleanup

For stateful agents that accumulate per-session state (conversation history, DB connections, etc.), use try/finally to clean up:

await scan.run(async (session: Session) => {
  try {
    for await (const { attack, respond } of session) {
      const reply = await chatbot(session.id, attack)
      await respond(reply)
    }
  } finally {
    clearSession(session.id)
  }
})

Configuration

const client = new LakeraRedClient({
  apiKey: "sk_lr_...", // Lakera Red API key
  baseUrl: "https://...", // Lakera Red API endpoint
  logLevel: "info", // "debug" | "info" | "warn" | "error" | "silent"
  extraHeaders: {}, // additional HTTP headers (optional)
  logger: customLogger, // BYO logger implementing the Logger interface (optional)
})

Examples

The SDK ships with runnable examples. Copy them into your project with:

npx lakera-red-sdk init-examples
cd lakera-red-examples/echo
cp .env.example .env        # fill in your credentials
npm install
npm start

| Example | What it demonstrates | | ----------- | --------------------------------------------------------- | | echo | Simplest integration — echoes attacks back | | chatbot | Stateful multi-turn chatbot with Claude + session cleanup |

Run npx lakera-red-sdk list-examples to see all available examples.

License

MIT

Development

npm install
npm run check-types   # tsc type-check (no emit)
npm run lint          # eslint
npm run format:check  # prettier
npm run test          # vitest
npm run build         # tsc -> ./dist (with .d.ts + source maps)

Releasing

On master, the GitLab CI pipeline exposes two manual jobs when red/sdk/** files change:

1. scan:sdk:pre-publish — runs typecheck, lint, tests, build, then validates the tarball (publint, attw, leak scan, size check).
2. publish:sdk:npm — verifies the tarball checksum from the scan step, then publishes to npm with provenance attestation.

Bump the version in package.json before merging to master, then trigger both jobs in order from the pipeline UI.