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 1115 detection patterns across 78 attack categories — prompt injection, MCP tool poisoning, cross-agent injection, credential exfiltration, and more — in an average of 0.261ms per scan. 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.3.5 ships 1115 detection patterns across 78 attack categories. Here is an honest breakdown of the coverage:
prompt_injection_direct — "ignore previous instructions" and 200+ obfuscated variants across 23 languages
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 64-category taxonomy
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 — the 0.261ms average 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 (average 0.261ms per text scan), 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.