guardrailprobe

Provider-agnostic AI guardrail benchmarking tool. Tests your guardrail layer — not your model — across 10 backends against the OWASP LLM Top 10.

What it does

guardrailprobe fires 78 attack probes at your guardrail endpoints and tells you which ones let attacks through. It produces:

• Pass/fail per probe across OWASP LLM01–LLM10 and content-moderation categories
• Side-by-side comparison of multiple backends in a single run
• Signed benchmark reports (PDF with RFC 3161 timestamp, JSON, Markdown)
• Flask dashboard for ad-hoc probe runs and report browsing

No framework lock-in. No cloud account required. Just point it at an endpoint and run.

Supported backends

Adapters with missing credentials return SKIPPED gracefully — partial configurations run fine.

Installation

pip install guardrailprobe

With optional SDK extras:

# All extras
pip install "guardrailprobe[all]"

# Pick what you need
pip install "guardrailprobe[nemo,guardrails_ai,presidio]"

Skip the spaCy model download (e.g. in CI):

GUARDRAILPROBE_SKIP_SPACY=1 pip install guardrailprobe

Quick start

# 1. Set up credentials — interactive wizard (or copy .env.example to .env and edit manually)
guardrailprobe init

# 2. Check which backends are ready
guardrailprobe status

# 3. Run a benchmark (current month, all configured backends)
guardrailprobe run --output-dir ./reports

# 4. Run against specific backends only
guardrailprobe run --backends lakera,openai_moderation --output-dir ./reports

# 5. Launch the dashboard
guardrailprobe dashboard

Docker

Start the dashboard

docker compose up

Open http://localhost:8080. The container starts even without a .env file — the Setup Guide card in the dashboard lists exactly which environment variables each unready adapter needs.

Configure credentials

cp .env.example .env
# Fill in the keys for the backends you want to test, then:
docker compose up

The .env file is optional. Any variables already exported in your shell are passed through automatically via the environment: block in docker-compose.yml.

Adapter status in Docker

Here is the out-of-the-box status for each adapter and what you need to enable it:

LlamaFirewall (Meta PromptGuard 2)

LlamaFirewall runs a local ML model and is excluded from the Docker image to keep it lean.

Requirements: Python 3.10–3.12 on the host (PyTorch is a transitive dependency).

# 1. Install into ./site-packages on your host
# --ignore-installed avoids false conflicts with other packages in your host environment
python3.12 -m pip install llamafirewall --target ./site-packages --ignore-installed

# 2. Restart the container — the entrypoint detects the package automatically
docker compose up

On startup you will see:

[guardrailprobe] site-packages mounted — llama_firewall: YES  llm_guard: NO

First run — model download (one-time): LlamaFirewall uses Meta's Llama-Prompt-Guard-2-86M model, which is gated on HuggingFace. You must:

1. Accept the license at huggingface.co/meta-llama/Llama-Prompt-Guard-2-86M
2. Set HF_TOKEN=<your-token> in .env before starting the container

The model is cached in ./hf_models (bind-mounted at /app/hf_models inside the container). Subsequent runs load from cache and work fully offline.

PyTorch / CUDA compatibility: If the host torch version does not match the CUDA driver, the first scan raises Cannot copy out of meta tensor. The adapter automatically sets CUDA_VISIBLE_DEVICES="" to force CPU-only inference, which sidesteps this. If you still see the error, verify torch is installed in ./site-packages:

python3.12 -c "import torch; print(torch.__version__)"

If the model never loads successfully, guardrailprobe marks all LlamaFirewall probes as SKIPPED (not BLOCK) so benchmark results are not inflated.

LLM Guard (Protect AI)

LLM Guard runs PromptInjection and Toxicity scanners locally and is also excluded from the Docker image.

Requirements: Python 3.9–3.12 on the host.

# 1. Install into ./site-packages on your host
python3.12 -m pip install llm-guard --target ./site-packages --ignore-installed

# 2. Restart the container
docker compose up

On startup you will see:

[guardrailprobe] site-packages mounted — llama_firewall: NO  llm_guard: YES

First run — model download (one-time): PromptInjection and Toxicity scanners download their model weights from HuggingFace on first use. No token or license is required — the models are public. Weights are cached in ./hf_models.

Scanner init failures: If llm_guard is installed but scanners fail to load (common when transformers or torch versions mismatch), the adapter logs the exact error and falls back to pattern-only detection. Probes not matched by patterns are returned as SKIPPED — not BLOCK — so benchmark results stay accurate. To diagnose:

python3.12 -c "from llm_guard.input_scanners import PromptInjection; PromptInjection()"

No environment variables are required. LLM Guard runs fully offline once models are cached.

Install both at once

python3.12 -m pip install llamafirewall llm-guard --target ./site-packages --ignore-installed
docker compose up

The container prints the detected status for each package at startup and skips any that are absent — no configuration required.

Custom HTTP guardrail (opt-in)

GenericHTTPAdapter lets you test any proprietary or self-hosted guardrail that exposes an HTTPS API. It is not registered by default — it won't appear in benchmark runs unless you register it manually:

from guardrailprobe.adapters import REGISTRY
from guardrailprobe.adapters.generic_http import GenericHTTPAdapter
REGISTRY.register(GenericHTTPAdapter())

Add to .env:

CUSTOM_GUARDRAIL_URL=https://your-guardrail-api.example.com/check
CUSTOM_GUARDRAIL_API_KEY=your-key-here
# CUSTOM_GUARDRAIL_AUTH_HEADER=X-Api-Key   # only needed if the API uses a non-standard header

One-shot benchmark via Docker

docker compose run --rm guardrailprobe \
  guardrailprobe run --year 2026 --month 6 --output-dir /app/reports

Reports are written to the guardrailprobe_reports named volume and also to ./docs/benchmarks on the host (via the ./docs bind mount).

Ollama (local LLM for NeMo, GPU recommended)

The container uses network_mode: host so localhost:11434 inside the container reaches the host's Ollama process directly, without exposing Ollama to the LAN.

# Start Ollama on the host (separate terminal)
ollama serve
ollama pull llama3.2

# Enable in .env
echo "OLLAMA_BASE_URL=http://localhost:11434" >> .env

docker compose up

Ollama is disabled by default (OLLAMA_BASE_URL=). CPU inference with llama3.2 is too slow for NeMo's 3-call-per-probe workflow (~20 s/probe); a GPU is recommended. Without OLLAMA_BASE_URL, NeMo uses AWS Bedrock if credentials are present (priority 1 — recommended for benchmarks).

Skip the spaCy model download (CI / constrained environments)

docker compose build --build-arg SKIP_SPACY=1

Probes

78 built-in attack probes across 11 categories:

See METHODOLOGY.md for probe design, scoring, and reproduction steps.

Reports

Each guardrailprobe run produces three artifacts in the output directory:

reports/
  benchmark_2026_06.pdf   # Signed PDF with RFC 3161 timestamp
  benchmark_2026_06.json  # Machine-readable full results
  benchmark_2026_06.md    # Human-readable summary

To sign reports with your own certificate:

guardrailprobe cert generate          # self-signed P12 for testing
guardrailprobe cert show              # inspect the active signing cert
guardrailprobe cert verify report.pdf # verify an existing report

Set GUARDRAIL_SIGNING_KEY_P12 to the path of your P12 file.

Configuration

Choose either approach — both produce the same .env file.

Option A — Interactive wizard (recommended)

guardrailprobe init

Walks through each backend and prompts for keys. Press Enter to skip any adapter you don't have credentials for. Writes only what you enter to .env.

Option B — Edit manually

cp .env.example .env
# Open .env and fill in the keys for the backends you want to test

Key variables

NeMo-specific variables

After either option, verify which backends are ready:

guardrailprobe status

Python API

from guardrailprobe import GuardrailBackend
from guardrailprobe.runner import RedTeamRunner
from guardrailprobe.probes import ProbeLibrary, AttackCategory

runner = RedTeamRunner()
library = ProbeLibrary()

# Run all probes against one backend
report = runner.run(GuardrailBackend.LAKERA, library.all_probes())
print(f"Pass rate: {report.pass_rate:.1%}")

# Compare backends
comparison = runner.compare_backends(
    [GuardrailBackend.LAKERA, GuardrailBackend.OPENAI_MODERATION],
    library.all_probes(),
)
print(f"Best overall: {comparison.best_overall}")

# Filter probes
injection_probes = library.get_by_category(AttackCategory.PROMPT_INJECTION)
critical_probes  = library.get_by_severity("critical")
cm_probes        = library.get_content_moderation_probes()

Development

GUARDRAILPROBE_SKIP_SPACY=1 pip install -e ".[dev]"
pytest tests/ -v
ruff check guardrailprobe/ tests/

License

Apache-2.0 — see LICENSE.