Python Prompt Injection Detection Library
Sunglasses is a free, MIT licensed Python prompt injection detection library. Install it with pip install sunglasses, then call engine.scan(text) before any model call or tool invocation. It runs 1554 detection patterns across 118 attack categories prompt injection, MCP tool poisoning, cross agent injection, credential exfiltration and more. In ~0.7ms on a short input and ~4ms on a typical attack string. No API keys, no cloud calls, no telemetry. Everything runs inside your process.
Install
Sunglasses installs from PyPI in one command. No build tools, no API keys, no accounts. The text scanning path has zero heavy dependencies. The patterns, normalization engine and decision logic all ship inside the package.
For audio and video scanning (Whisper + FFmpeg path), add the [all] extra:
After install, scan your first input in three lines:
That is the complete install to first scan flow. The engine loads on first instantiation and is designed to be reused create one instance and call scan() on it for every input in your pipeline. Full package source and changelog: pypi.org/project/sunglasses. GitHub: github.com/sunglasses dev/sunglasses.
What it detects
Sunglasses 0.5.9 ships 1554 detection patterns across 118 attack categories. Here is an honest breakdown of the coverage:
prompt_injection_direct "ignore previous instructions" and 200+ obfuscated variants across 13 languages with dedicated patterns
prompt_injection_indirect malicious instructions hidden in documents, retrieval results, web pages and RAG content your agent reads
mcp_tool_poisoning malicious tool descriptions, manifest manipulation and tool output policy overrides that turn legitimate MCP servers into attack vectors
cross_agent_injection payloads that propagate from agent A to agent B during handoff, including forged revocation receipts and persona scope rebind attacks (15 new patterns in 0.2.31, following 16 in 0.2.31)
credential_exfiltration payloads designed to extract API keys, secrets and tokens through agent tool calls
state_sync_poisoning A2A protocol level attacks that corrupt shared agent state
runtime_governance_bypass payloads targeting guardrail and governance orchestration layers
encoded_payload_* base64, ROT13, hex, URL encoded, HTML entity, Unicode homoglyph and mixed script evasions unwrapped by the normalization layer before pattern matching
readme_poisoning hidden instructions in repo READMEs that agents read at install time
supply_chain_signals package and repository signals indicating poisoned dependencies
jailbreak_roleplay / jailbreak_system_override roleplay and persona override framings mapped across the full taxonomy of 118 categories
The full category list and per pattern detail lives in the scanner repo at sunglasses/patterns.py. The attack taxonomy is cross referenced with OWASP and MITRE in the compliance section and visualized in the MCP Attack Atlas.
audio_prompt_injection via Whisper transcription path (needs sunglasses[all] + FFmpeg)
video_prompt_injection via FFmpeg frame and subtitle extraction
Audio and video detection are functional but marked experimental. Conservative confidence claims until larger public validation sets are published.
Code examples
From the CLI, pass --json to get structured output compatible with any log pipeline:
Sunglasses integrates with LangChain and CrewAI as a pre ingestion filter. Insert the scan call before any model.invoke() or tool execution:
For integration walkthroughs specific to Claude Code MCP workflows, read how Sunglasses works. The security manual has dedicated integration chapters for LangChain, CrewAI and generic agent frameworks.
Output format
Every engine.scan() call returns a structured result with a three way decision:
The CLI's sunglasses scan --output sarif command outputs SARIF 2.1.0. This plugs directly into GitHub Code Scanning, Azure DevOps Pipelines and any SARIF aware CI system. Surface prompt injection findings inside pull request checks or deployment gates without custom tooling. See the manual operations chapter for CI integration examples.
Why pure Python matters
Most security tools for AI agent pipelines are cloud APIs. That means every input you scan leaves your infrastructure, you pay per call at scale and your pipeline has a hard network dependency. Sunglasses takes the opposite position:
No daemon the engine initializes inline. No sidecar process, no socket, no IPC. Import and call.
No API key core text/image/PDF/QR scanning requires zero external credentials. The patterns ship in the package.
No network calls zero outbound telemetry on the default path. Your agent inputs never leave your process.
Runs in your process call engine.scan() from any Python process. Works air gapped. Works in Lambda. Works in a Docker container with no egress rules.
Zero core dependencies for text scanning optional deps (Tesseract, pyzbar, Whisper, FFmpeg) only apply to media paths. The text engine installs clean.
Sub millisecond latency ~0.7ms short-input latency means you can scan every agent input in production without measurable throughput impact.
This positions Sunglasses as the local ingestion boundary layer the first filter before any model call or tool execution. Use it standalone or pair it with cloud guardrails for layered defense. The FAQ covers the positioning comparison in more detail. The open source AI agent security scanner page has the full architecture context.
What Sunglasses does NOT replace: runtime behavioral monitoring, SBOM and dependency governance, network level controls or model internal defenses. It is an ingestion time filter. Use it as the first layer in a defense in depth stack, not the only layer.
Compatibility
Confirmed from the published package and README:
Python: 3.8 and above. No compiled extensions required for text scanning.
Operating systems: macOS, Linux, Windows. Anywhere standard Python runs.
Core text/image/PDF/QR path: zero heavy dependencies. Pip install is the only requirement.
Image scanning: requires Tesseract (OCR) and pyzbar (QR decode). Both are documented in the repo README.
Audio/video scanning: requires pip install sunglasses[all] plus FFmpeg on your system path. Experimental.
Frameworks: LangChain, CrewAI and Claude Code MCP workflows confirmed. Generic agent frameworks work via direct engine.scan() calls.
CI/CD: SARIF 2.1.0 output via sunglasses scan --output sarif. Compatible with GitHub Code Scanning and Azure DevOps Pipelines.
MCP server mode: available via sunglasses.mcp for agent frameworks that speak the Model Context Protocol.
Performance numbers published in stats/current.json were measured on Apple M3 Max, 48GB RAM, single threaded Python. Your hardware will produce different results benchmark on your own stack before citing numbers.
Where to verify
Every claim on this page is verifiable against a live source. Do not take install instructions at face value. Confirm before running in production:
PyPI package: pypi.org/project/sunglasses confirms version, install command, release history
Source code: github.com/sunglasses dev/sunglasses MIT license, full pattern source, integration examples
FAQ: sunglasses.dev/faq 30 Q&A pairs covering install, performance, licensing and comparisons
Architecture: sunglasses.dev/how it works the 3-stage pipeline, normalization layer and decision logic
Security manual: sunglasses.dev/manual install, integration and operations reference with framework specific chapters
Entity page: sunglasses.dev/open source ai agent security scanner full capability overview including proof of work and CVP benchmark results
Live stats: sunglasses.dev/llms full.txt machine readable handbook, canonical fact sheet for LLM agents and answer engines
CVP benchmark reports: sunglasses.dev/cvp Anthropic CVP approval + six published model evaluation runs
Competitor comparisons: vs Lakera · vs Promptfoo
Frequently asked questions
How do I install the Sunglasses Python prompt injection detection library?+
pip install sunglasses no build tools, no API keys, no accounts required. For audio and video scanning, add pip install sunglasses[all] to pull in Whisper. After install, import SunglassesEngine from sunglasses.engine and call engine.scan(text) to run your first detection. The engine loads on first instantiation and is designed to be reused across your pipeline.What Python versions does Sunglasses support?+
Does Sunglasses require an API key or network connection to scan?+
Does Sunglasses support async Python?+
SunglassesEngine.scan() call is synchronous and sub millisecond (~0.7ms short input, ~4ms attack string), so in practice it does not block an async event loop meaningfully. If you need an awaitable wrapper, use asyncio.run_in_executor with the default thread pool. A dedicated async API is on the roadmap but is not in 0.2.60.How do I wrap Sunglasses inside a LangChain or CrewAI tool boundary?+
engine.scan(text) on any input before it reaches a model.invoke() or tool call. If result.decision is "block", raise an error or return a sanitized response. Do not forward the input. Full integration examples are in the GitHub README and the manual chapters. For Claude Code MCP workflows, the how it works page has specific wiring guidance.Does Sunglasses output SARIF for CI/CD pipelines?+
sunglasses scan --output sarif CLI command outputs SARIF 2.1.0, which is compatible with GitHub Code Scanning, Azure DevOps Pipelines and any SARIF aware CI system. Use this to surface prompt injection findings inside pull request checks or deployment gates. See the manual operations chapter and the agent contract poisoning blog post for real world examples of what Sunglasses finds in agent pipelines.