lakera-red-sdk 0.1.0__tar.gz

lakera_red_sdk-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Environment variables
+.env
+.env.*
+!.env.example
+# fine for development, no secrets
+!.env.local
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Convex
+.vercel
+# Entire folder is regenerated by `convex codegen` — not committed so files stay fresh
+backend/convex/_generated/
+
+# Local copy of import-export data
+/data
+
+# Build outputs
+frontend/dist
+backend/dist
+
+# TypeScript build info files
+*.tsbuildinfo
+
+# Storybook
+*storybook.log
+storybook-static
+
+# Playwright
+/test-results/
+/playwright-report/
+
+# Output files for testing
+cli/scan/runs/
+cli/scan/judge-comparison.md
+cli/compare/output/
+temp-profile-*
+
+# Local AI assistant config
+.claude/
+.specify/
+.specs/

lakera_red_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lakera AI (a Check Point company)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lakera_red_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: lakera-red-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Lakera Red — run adversarial scans against your AI agents and chatbots.
+Project-URL: Homepage, https://red.lakera.ai
+Project-URL: Documentation, https://docs.lakera.ai/docs/red/sdk-quickstart
+Author-email: "Lakera AI (a Check Point company)" <support@lakera.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adversarial,agent-security,ai-safety,ai-security,lakera,lakera-red,llm,red-teaming,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Lakera Red SDK
+
+Official Python SDK for [Lakera Red](https://red.lakera.ai) — run adversarial scans
+against your AI agents from your own runtime.
+
+Lakera is a Check Point company.
+
+## Install
+
+```bash
+pip install lakera-red-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions, CreateScanOptions, Session
+
+
+async def main():
+    async with LakeraRedClient(LakeraRedClientOptions(
+        api_key="sk_lr_...",
+        base_url="https://red-webhooks.lakera.ai",
+        log_level="info",
+    )) as client:
+        scan = await client.create_scan(CreateScanOptions(
+            target="My Agent",
+            name="Example scan",
+            concurrency=1,
+            objectives=["safety.hate-speech.1"],
+        ))
+
+        async def handler(session: Session) -> None:
+            async for message in session:
+                reply = await your_agent(session.id, message.attack)
+                await message.respond(reply)
+
+        await scan.run(handler)
+        await scan.write_results("./results.json")
+
+
+asyncio.run(main())
+```
+
+## 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 `SessionMessage` objects. |
+| **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:
+
+```python
+async def handler(session: Session) -> None:
+    try:
+        async for message in session:
+            reply = await chatbot(session.id, message.attack)
+            await message.respond(reply)
+    finally:
+        clear_session(session.id)
+```
+
+## Configuration
+
+```python
+from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions
+
+async with LakeraRedClient(LakeraRedClientOptions(
+    api_key="sk_lr_...",             # Lakera Red API key
+    base_url="https://red-webhooks.lakera.ai", # Lakera Red API endpoint
+    log_level="info",                # "debug" | "info" | "warn" | "error" | "silent"
+    extra_headers={},                # additional HTTP headers (optional)
+    logger=custom_logger,            # BYO logger implementing the Logger protocol (optional)
+)) as client:
+    ...
+```
+
+## Examples
+
+| Example     | What it demonstrates                                      |
+| ----------- | --------------------------------------------------------- |
+| **echo**    | Simplest integration — echoes attacks back                |
+| **chatbot** | Stateful multi-turn chatbot with Claude + session cleanup |
+
+## License
+
+[MIT](./LICENSE)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+mypy src/        # type checking
+ruff check src/  # linting
+ruff format src/ # formatting
+pytest           # tests
+```

lakera_red_sdk-0.1.0/README.md

@@ -0,0 +1,104 @@
+# Lakera Red SDK
+
+Official Python SDK for [Lakera Red](https://red.lakera.ai) — run adversarial scans
+against your AI agents from your own runtime.
+
+Lakera is a Check Point company.
+
+## Install
+
+```bash
+pip install lakera-red-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions, CreateScanOptions, Session
+
+
+async def main():
+    async with LakeraRedClient(LakeraRedClientOptions(
+        api_key="sk_lr_...",
+        base_url="https://red-webhooks.lakera.ai",
+        log_level="info",
+    )) as client:
+        scan = await client.create_scan(CreateScanOptions(
+            target="My Agent",
+            name="Example scan",
+            concurrency=1,
+            objectives=["safety.hate-speech.1"],
+        ))
+
+        async def handler(session: Session) -> None:
+            async for message in session:
+                reply = await your_agent(session.id, message.attack)
+                await message.respond(reply)
+
+        await scan.run(handler)
+        await scan.write_results("./results.json")
+
+
+asyncio.run(main())
+```
+
+## 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 `SessionMessage` objects. |
+| **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:
+
+```python
+async def handler(session: Session) -> None:
+    try:
+        async for message in session:
+            reply = await chatbot(session.id, message.attack)
+            await message.respond(reply)
+    finally:
+        clear_session(session.id)
+```
+
+## Configuration
+
+```python
+from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions
+
+async with LakeraRedClient(LakeraRedClientOptions(
+    api_key="sk_lr_...",             # Lakera Red API key
+    base_url="https://red-webhooks.lakera.ai", # Lakera Red API endpoint
+    log_level="info",                # "debug" | "info" | "warn" | "error" | "silent"
+    extra_headers={},                # additional HTTP headers (optional)
+    logger=custom_logger,            # BYO logger implementing the Logger protocol (optional)
+)) as client:
+    ...
+```
+
+## Examples
+
+| Example     | What it demonstrates                                      |
+| ----------- | --------------------------------------------------------- |
+| **echo**    | Simplest integration — echoes attacks back                |
+| **chatbot** | Stateful multi-turn chatbot with Claude + session cleanup |
+
+## License
+
+[MIT](./LICENSE)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+mypy src/        # type checking
+ruff check src/  # linting
+ruff format src/ # formatting
+pytest           # tests
+```

lakera_red_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lakera-red-sdk"
+version = "0.1.0"
+description = "Official Python SDK for Lakera Red — run adversarial scans against your AI agents and chatbots."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Lakera AI (a Check Point company)", email = "support@lakera.ai" },
+]
+keywords = [
+    "lakera",
+    "lakera-red",
+    "ai-security",
+    "ai-safety",
+    "red-teaming",
+    "adversarial",
+    "llm",
+    "agent-security",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+yaml = [
+    "pyyaml>=6",
+]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "pyyaml>=6",
+    "types-PyYAML>=6",
+]
+
+[project.scripts]
+lakera-red-sdk-echo = "lakera_red_sdk.examples.echo:run"
+lakera-red-sdk-chatbot = "lakera_red_sdk.examples.chatbot:run"
+
+[project.urls]
+Homepage = "https://red.lakera.ai"
+Documentation = "https://docs.lakera.ai/docs/red/sdk-quickstart"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lakera_red_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.uv]
+exclude-newer = "14 days"

lakera_red_sdk-0.1.0/src/lakera_red_sdk/__init__.py

@@ -0,0 +1,39 @@
+from lakera_red_sdk.client import LakeraRedClient
+from lakera_red_sdk.logger import CreateLoggerOptions, create_logger, noop_logger
+from lakera_red_sdk.scan import Scan
+from lakera_red_sdk.types import (
+    CrescendoStrategyOptions,
+    Logger,
+    LogLevel,
+    ReconContext,
+    ScanResultEntry,
+    ScanResults,
+    Session,
+    SessionHandler,
+    SessionMessage,
+    SmokeStrategyOptions,
+    StaticStrategyOptions,
+    StrategyName,
+    StrategyOptions,
+)
+
+__all__ = [
+    "LakeraRedClient",
+    "CreateLoggerOptions",
+    "CrescendoStrategyOptions",
+    "Logger",
+    "LogLevel",
+    "ReconContext",
+    "Scan",
+    "ScanResultEntry",
+    "ScanResults",
+    "Session",
+    "SessionHandler",
+    "SessionMessage",
+    "SmokeStrategyOptions",
+    "StaticStrategyOptions",
+    "StrategyName",
+    "StrategyOptions",
+    "create_logger",
+    "noop_logger",
+]

lakera_red_sdk-0.1.0/src/lakera_red_sdk/_helpers.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from lakera_red_sdk.types import Logger, ReconContext
+
+INITIAL_BACKOFF_S = 1.0
+MAX_BACKOFF_S = 5.0
+MAX_RETRIES = 5
+DEFAULT_HTTP_TIMEOUT_S = 30.0
+
+
+def load_app_context_file(file_path: Path) -> ReconContext:
+    try:
+        import yaml
+    except ImportError as err:
+        raise ImportError(
+            "pyyaml is required for app_context_file support: pip install lakera-red-sdk[yaml]"
+        ) from err
+
+    resolved = file_path.resolve()
+    content = resolved.read_text()
+    parsed = yaml.safe_load(content)
+
+    if not isinstance(parsed, dict):
+        raise ValueError(f"app_context_file '{file_path}' must contain a YAML object")
+
+    required_keys = ["appDescription", "allowedActions", "forbiddenActions"]
+    for key in required_keys:
+        if not isinstance(parsed.get(key), str):
+            raise ValueError(
+                f"app_context_file '{file_path}' is missing required string field '{key}'"
+            )
+
+    return ReconContext(
+        app_description=parsed["appDescription"],
+        allowed_actions=parsed["allowedActions"],
+        forbidden_actions=parsed["forbiddenActions"],
+    )
+
+
+def safe_json(res: httpx.Response) -> dict[str, Any]:
+    try:
+        data: dict[str, Any] = res.json()
+        return data
+    except Exception:
+        return {}
+
+
+async def fetch_with_retry(
+    url: str,
+    *,
+    method: str = "GET",
+    headers: dict[str, str],
+    json_body: dict[str, Any] | None = None,
+    client: httpx.AsyncClient | None = None,
+    timeout: float = DEFAULT_HTTP_TIMEOUT_S,
+    max_retries: int = MAX_RETRIES,
+    logger: Logger | None = None,
+) -> httpx.Response:
+    last_error: Exception | None = None
+    backoff_s = INITIAL_BACKOFF_S
+    path = httpx.URL(url).path
+    owns_client = client is None
+
+    for attempt in range(max_retries + 1):
+        start = time.monotonic()
+        try:
+            http = client or httpx.AsyncClient(timeout=timeout)
+            try:
+                res = await http.request(
+                    method,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    timeout=timeout,
+                )
+            finally:
+                if owns_client:
+                    await http.aclose()
+            elapsed_ms = int((time.monotonic() - start) * 1000)
+            if res.is_success or (res.status_code < 500 and res.status_code != 429):
+                if logger:
+                    logger.debug(
+                        "http response",
+                        {
+                            "method": method,
+                            "path": path,
+                            "status": res.status_code,
+                            "elapsed_ms": elapsed_ms,
+                            "attempt": attempt + 1,
+                        },
+                    )
+                return res
+            last_error = RuntimeError(f"HTTP {res.status_code}")
+        except Exception as err:
+            last_error = err
+
+        elapsed_ms = int((time.monotonic() - start) * 1000)
+        if attempt < max_retries:
+            if logger:
+                logger.debug(
+                    "http retry",
+                    {
+                        "method": method,
+                        "path": path,
+                        "attempt": attempt + 1,
+                        "max_retries": max_retries,
+                        "elapsed_ms": elapsed_ms,
+                        "backoff_ms": int(backoff_s * 1000),
+                        "error": str(last_error),
+                    },
+                )
+            await asyncio.sleep(backoff_s)
+            backoff_s = min(backoff_s * 2, MAX_BACKOFF_S)
+        else:
+            if logger:
+                logger.warn(
+                    "http exhausted retries",
+                    {
+                        "method": method,
+                        "path": path,
+                        "attempts": attempt + 1,
+                        "elapsed_ms": elapsed_ms,
+                        "error": str(last_error),
+                    },
+                )
+
+    raise last_error  # type: ignore[misc]