sunglasses

SUNGLASSES is an open-source, local-only input inspection layer for AI agents, described by its README as an input firewall. It is written in Python and released under the MIT License. The project scans content before an agent acts on it and reports findings instead of silently rewriting or stripping content. It covers six media types: text, images, audio, video, PDFs and QR/barcodes. Image scanning can use OCR, EXIF metadata and hidden-text detection; PDF scanning reads page text, metadata and annotations; audio and video deep scans use speech-to-text and subtitle extraction. The scanner targets prompt injection, credential exfiltration, command injection, memory poisoning, social engineering and evasion techniques such as Unicode tricks, RTL obfuscation, leetspeak, Base64 encoding and homoglyph substitution. SUNGLASSES is English-first. The README states the full ruleset is English; 13 languages have exactly two dedicated patterns each; 7 languages are keyword-level only; and Persian and Bengali are listed as name only with no dedicated pattern or keyword. Normalization is language-independent. The project warns against expecting non-English parity with English and marks deeper language coverage as a v0.6+ lane. Installation is through pip: pip install sunglasses for zero-dependency text scanning, with media or all extras for images, PDFs, QR codes, audio and video. The CLI offers scan, check, demo, info and report. The Python API exposes SunglassesEngine for text and SunglassesScanner for media. Other integration surfaces include an MCP server, LangChain and CrewAI integrations, SARIF 2.1.0 output for CI, and a browser demo for text, GitHub repositories and images. The CLI uses an explicit exit-code contract. 0 means the whole input was read and no threat was found. 1 means a threat was found. 2 is a usage or operational error where nothing was scanned in the requested scope. 3 means incomplete inspection: nothing was found in the part that could be read, but some part could not be read, such as an archive, an audio file without deep scan, or input past the size cap. Precedence is 1 > 3 > 2 > 0. JSON output separates threat_found, inspection_complete and is_clean, and reports truncated and extraction_complete. The engine reads at most 1 MB by default, and a scan that hits the cap reports truncated and bytes_scanned rather than a silent clean pass. The v0.4 firewall installs as a Claude Code PreToolUse hook and is described as best-effort: it has a 10-second timeout and a timed-out hook does not block the call. It can pin MCP tool descriptors and check whether they changed, block exact-format secrets on tool calls that can put bytes on a wire, enforce a user policy file, and write receipts that record a SHA-256 of tool input rather than the input itself. The project separates deterministic facts, which can be hard-blocked, from detections, which escalate to the user rather than auto-block. It fails open and records when a call was not checked. The README lists honest limits: descriptor pinning is not live; the hook sees the tool call text, not files behind it; interpreter or socket one-liners can hide egress; the WARN lane is off by default. Published performance and benchmark figures include 1,540 patterns, 6,931 unique keywords, 118 attack categories, 17 normalization techniques, and internal recall of 64/64 on the shipped attack fixture set. The README benchmark uses 38 real agent-input attacks and 76 well-known open-source READMEs as negatives, reporting precision 86.1%, recall 97.4%, F1 0.914, 30/30 known-shape attacks caught and 7/8 novel-semantic paraphrases caught. It states the one known miss is a pipe-to-shell install line that also appears in clean READMEs, and that a test asserts the scanner does not flag it. Latency figures given are about 0.7 ms for a short input, about 4.2 ms for a typical attack string, about 311 ms for a real README, and sustained throughput around 26 KB per second single-threaded. The README notes these are regenerated from an in-repo corpus and that hardware will differ. Deep audio and video scanning requires Whisper and FFmpeg, and the project marks those media scans as experimental. Scanning runs locally: the README states no cloud, no API keys and no telemetry for scanning. It also notes the static scanner does not execute scanned content, while the pin command launches configured MCP servers only after asking for consent and refuses without consent in unattended contexts. The project positions itself as a local foundation layer that can be used alone or alongside cloud guardrail tools.