litellm-shield
SusFactor jailbreak and prompt-injection guardrail for LiteLLM.
Runs the 0DIN SusFactor classifier — an e5-large encoder + MLP head trained on hard negatives — to detect jailbreak and prompt-injection attempts on LLM inputs, outputs, and tool-call arguments. With the sdk/sdk-onnx backends this runs in-process: no network hop, fully offline once the model is provisioned. A hosted backend is also available for when self-hosting the model isn't desired — it sends prompts to 0DIN's hosted SusFactor API over HTTPS instead.
Installation
pip install 0din-litellm-shieldThis installs the hosted backend — no private dependencies required. Self-hosted in-process inference (sdk/sdk-onnx) remains 0DIN-internal only, since it depends on odin-prompt-toolkit, which is not on public PyPI; see Configuration reference.
---
How it works
- LiteLLM calls SusFactorGuardrail.applyguardrail(inputs, ...) for every request.
- Each text (user message, assistant response, tool-call arguments) is scored: P(suspicious) ∈ [0, 1].
- The configured enforcement is applied:
- flag — allow through, annotate in logs + X-SusFactor-Decision response header. Default for POCs.
- shadow — allow through, record only (no client annotation). Use for latency/accuracy validation.
- block — reject the request. With mode: precall the upstream model is never contacted; with mode: duringcall the model call is already in-flight when the block fires.
---
Prerequisites
- Python ≥ 3.11
- uv (asdf install uv latest or curl -LsSf https://astral.sh/uv/install.sh | sh)
- Docker + Docker Compose (for the container path)
- A HuggingFace account with access to 0dinai/susfactor-e5-large (gated — request access first)
- An OpenRouter API key (OPENROUTERAPIKEY)
---
Quick start
1. Provision the model
The SusFactor model weights are not bundled. Download them once into your local cache:
# Set your HuggingFace token (must have access to 0dinai/susfactor-e5-large)
export HF_TOKEN=hf_...
uv run python scripts/provision_model.pyThis writes to ~/.cache/signature-sdk/models/susfactor-v1/ by default. Override with --cache-dir /your/path or SIGNATURESDKMODELCACHE=/your/path.