sunglasses

SUNGLASSES is an open-source (beta) AI agent input firewall, positioned as a local input inspection layer used to see through agent attacks hidden in ordinary content, such as prompt injection, credential exfiltration, command injection, memory poisoning, social engineering and authority impersonation, Unicode evasion, RTL confusion, leetspeak, Base64-encoded attacks, homoglyph substitution, and more. It does not silently sanitize content; instead, it flags findings, and the caller decides the subsequent action.

【Main capabilities】 Locally scan text (emails, messages, files, APIs, web content, logs), code, PDFs, images, QR codes/barcodes, audio, and video. There are 1,569 detection rules in total, covering 117 categories. It can report the content that hits as well as the parts that "cannot be read/not checked," and will not treat unchecked content as clean. For images, it can perform OCR to recognize visible text, EXIF metadata, and hidden text regions; for audio, it can perform speech-to-text and metadata tag inspection; for video, it can inspect subtitle tracks, audio transcription, and video metadata; for PDFs, it can inspect page text, document metadata, and annotations; for QR codes, it can decode and scan the content. It supports decoding QR codes and barcodes and scanning their content.

【Usage methods】

1. sunglasses scan: check files, repositories, or strings on demand in the terminal or CI, and report findings and content that cannot be read.
2. Claude Code firewall hook: inspect before a tool call runs and optionally block, intercepting credential paths listed in policy and policy violations. This hook runs best-effort within a 10-second timeout, and a timeout will not block the call.
3. MCP server: expose scanning capability as a tool that agents can call.
4. Local MCP proxy: before a human approves a server in an interactive terminal, it rejects all tools/list and tools/call requests; after approval, it withholds credentials in tool calls or tool results within the credential channel. Installing the proxy itself does not provide protection.
5. GitHub Action: scan every pull request.
6. Python: scanning can be invoked from Python (e.g., scanner.scan_email(body, attachments) returns a scanned document).

【Supplementary usage notes】 CLI mode supports checking files, folders, repositories, or strings. Example output distinguishes between "read and no match" and "this format is nottwo facts, exit codes 0 and 3 are never confused: 0 means all content within the supported scope has been read and there is no match, 3 means there is unchecked content. The JSON output likewise explicitly distinguishes is_clean, threat_found, and inspection_complete. Proxy approval is a manual step requiring an interactive terminal; it prints the tool name and the first 16 characters of each descriptor summary, then asks for confirmation; it is rejected when input is piped in. Approval belongs to a single server (stored by server_id), not to a tool list; different servers, even if they expose the same tools and have the same snapshot_sha256, will receive different server_ids, and therefore will not inherit an existing approval. How to self-test the proxy: the package includes a small server sunglasses/proxy/echo_server.py (with its own echo tool), which can be run in an empty folder. Use python -m sunglasses.proxy -- <your server command> to run a real MCP server as a subprocess and mediate a stdio session. Installation requires an existing .mcp.json; running sunglasses uninstall echo restores .mcp.json byte for byte, and approvals are preserved. You can try it in the browser without installing: sunglasses.dev/scan (scan text, GitHub repositories, or images; image OCR runs locally in the browser, and images never leave the device).

[Use cases] As a local foundational security layer, it is suitable for scenarios where data should not leave the local machine, for offline or isolated networks, with no API keys and no cloud calls, for checking input content before an agent reads or calls a tool, and it can be used in CI pipelines to scan pull requests. It can be used alone or work alongside other security tools in the same pipeline (the project provides an adapter system). Official documentation states that its positioning differs from tools such as Lakera Guard, LLM Guard, NVIDIA NeMo Guardrails, and Azure Prompt Shields, which excel at ML-based detection of novel attacks, whereas SUNGLASSES focuses on being local, offline, zero-cost, and LLM-free.

[Limitations and cautions] The project is in beta. The official documentation clearly states several limitations:

• Outside the credential channel, it reads input, so a clean result is only a lower bound on confidence rather than a guarantee.
• It does not touch authentication (OAuth, cookie, token, header), nor does it monitor agent behavior (the latter being SHIELD, not yet released).
• Scanning runs locally, with no cloud, no API keys, and no telemetry; text, image, PDF, and QR code scanning require no network. Audio and video scanning only occur when optional dependencies are installed (sunglasses[audio], sunglasses[video], or sunglasses[all]) and a DEEP scan is requested; the Whisper speech model is downloaded on first use and reused thereafter; video scanning also writes an audio track.
• Content that cannot be inspected (archives, images for which OCR is unavailable, files exceeding the size limit) is reported as "unchecked" rather than "clean". Within opened files, coverage depends on format (see the PDF notes).
• There are four exit status codes, deliberately conveying different signals; 0 is not a guarantee that a file is safe, but only indicates that the supported scope was covered and no rules were triggered.
• The proxy only covers the credential channel in tool results and tool calls, and is not a generic check of everything a tool returns; the official statement makes no comparison with any other tool.
• Rule GLS-SD-010 is line-anchored: it matches only assignments at the start of a line, so KEY=value indented by any whitespace, or assignments inside a JSON string or after quotation marks, will not be matched in any channel (including tool results, files, and messages). When the value is in a known credential format, the GLS-SD-001 series can still catch it everywhere (GLS-SD-001 for files, messages, and web content; GLS-SD-001-API for tool results); what is not covered is embedded assignments whose values have no recognizable form (such as passwords, DSNs, internal tokens).
• The hook is best-effort under load: after a 10-second timeout it will not block the call.
• Official reminder: installing the proxy itself does not constitute protection; do not treat decision: allow alone as permission to proceed, and judge in conjunction with is_clean and inspection_complete.

[Other] The repository address is https://github.com/sunglasses-dev/sunglasses，官方在 The README suggests starring the repository if you find it useful, and mentions the browser trial address sunglasses.dev/scan. Installation and upgrade notes: using an activated virtual environment keeps the sunglasses resolved by the installation and the shell in the same environment; if an older version is already installed, --upgrade is important; curl -fsSL fails on HTTP errors without saving the error page, so the script only runs when the download succeeds. The demo script mentioned in the text writes three fixture files to a temporary directory and deliberately scans a fourth nonexistent path, for five scanner invocations in total (the archive is scanned twice: human-readable output and JSON); the scanned content always remains data and is never executed, and the ZIP is not extracted. The timing and presentation in the demo vary by environment; the script checks the exit status and the ZIP coverage fields, and if they do not match, please report against the installed version.