SUNGLASSES 是一款开源（beta）的 AI 智能体输入防火墙，定位为本地输入检查层，用于识破隐藏在常规内容中的智能体攻击，例如提示注入、凭证外泄、命令注入、记忆污染、社工与权威伪装、Unicode 规避、RTL 混淆、仿写词（leetspeak）、Base64 编码攻击、同形字替换等。它不会静默清洗内容，而是标记发现结果，由调用方决定后续动作。
【主要能力】 本地扫描文本（邮件、消息、文件、API、网页内容、日志）、代码、PDF、图片、QR 码/条码、音频、视频。检测规则共 1,569 条，覆盖 117 个类别。能够报告命中的内容以及“无法读取/未检查”的部分，不会把未检查的内容当作干净。图片可做 OCR 识别可见文本、EXIF 元数据与隐藏文本区域；音频可做语音转文字与元数据标签检查；视频可检查字幕轨、音频转写与视频元数据；PDF 可检查页面文本、文档元数据与注释；QR 码可解码并扫描内容。支持解码 QR 码与条码并扫描其内容。
【使用方式】
- sunglasses scan：在终端或 CI 中按需检查文件、仓库或字符串，报告发现结果与无法读取的内容。
- Claude Code 防火墙 hook：在工具调用运行前进行检查并可拦截，拦截策略中列出的凭据路径与策略违规。该 hook 在 10 秒超时内尽最大努力执行，超时不会阻断调用。
- MCP 服务器：将扫描能力作为智能体可调用的工具暴露出来。
- 本地 MCP 代理：在人工于交互式终端批准某个服务器之前，会拒绝所有 tools/list 与 tools/call 请求；批准后会在凭据通道内对工具调用或工具结果中的凭据进行扣留。安装代理本身并不提供保护。
- GitHub Action：对每个 pull request 进行扫描。
- Python：可从 Python 调用扫描（如 scanner.scan_email(body, attachments) 返回扫描文档）。
【使用方式补充说明】 CLI 模式支持检查文件、文件夹、仓库或字符串。示例输出会区分“已读取且无匹配”与“该格式未被检查”两种事实，退出码 0 与 3 永不混淆：0 表示支持范围内的内容均已读取且无匹配，3 表示存在未检查的内容。JSON 输出中同样显式区分 is_clean、threat_found 与 inspection_complete。 代理审批是一个需要交互式终端的人工步骤，会打印工具名称与每个描述符摘要的前 16 个字符，然后询问确认；通过管道输入时会被拒绝。审批属于单个服务器（按 server_id 存储），而非工具列表；不同服务器即使暴露相同工具、拥有相同的 snapshot_sha256，也会获得不同的 server_id，因此不会继承已有审批。 试用代理的自测方式：包内附带一个小型服务器 sunglasses/proxy/echo_server.py（自带一个 echo 工具），可在空文件夹中运行。使用 python -m sunglasses.proxy -- <你的服务器命令> 将真实 MCP 服务器作为子进程运行并中介 stdio 会话。安装需要已存在的 .mcp.json；执行 sunglasses uninstall echo 可将 .mcp.json 逐字节恢复，审批会被保留。 浏览器中可无需安装试用：sunglasses.dev/scan（扫描文本、GitHub 仓库或图片，图片 OCR 在浏览器本地运行，图片不会离开设备）。
【适用场景】 作为本地基础安全层，适合希望数据不出本机、离线或隔离网络、无 API 密钥、无云端调用的场景，用于在智能体读取或调用工具之前检查输入内容，并可用于 CI 流水线对 pull request 进行扫描。可单独使用，也可与其他安全工具在同一流水线中协作（项目提供适配器系统）。官方说明称其定位与 Lakera Guard、LLM Guard、NVIDIA NeMo Guardrails、Azure Prompt Shields 等工具不同，后者擅长基于 ML 检测新型攻击，而 SUNGLASSES 侧重本地、离线、零成本、无需 LLM。
【限制与注意事项】 该项目为 beta 版本。官方明确说明若干限制：
- 在凭据通道之外，它会读取输入，因此干净结果只是信心的下限而非保证。
- 它不触碰身份验证（OAuth、cookie、token、header），也不监控智能体行为（后者为 SHIELD，尚未发布）。
- 扫描在本机运行，无云端、无 API 密钥、无遥测；文本、图片、PDF 与 QR 码扫描无需网络。音频与视频扫描仅在安装可选依赖（sunglasses[audio]、sunglasses[video] 或 sunglasses[all]）并请求 DEEP 扫描时，首次会下载 Whisper 语音模型，之后复用；视频扫描还会写入音轨。
- 无法检查的内容（归档文件、OCR 不可用的图片、超过大小上限的文件）会被报告为“未检查”，而非“干净”。在已打开文件内部，覆盖范围按格式而定（见 PDF 说明）。
- 退出状态码有四种，刻意传递不同信号；0 并非文件安全的保证，只表示支持范围内已覆盖且无规则触发。
- 代理只覆盖工具结果与工具调用中的凭据通道，并非对工具返回的一切内容做通用检查；官方声明未与其他工具做任何对比。
- 规则 GLS-SD-010 是行锚定的：它只匹配行首的赋值，因此被任何空白缩进的 KEY=value、位于 JSON 字符串内或引号后的赋值在任何通道都不会被匹配（包括工具结果、文件与消息）。当值属于已知凭据格式时，GLS-SD-001 系列仍可在各处捕获（文件、消息与网页内容为 GLS-SD-001，工具结果为 GLS-SD-001-API）；未被覆盖的是值无可识别形态的嵌入式赋值（如密码、DSN、内部令牌）。
- hook 在负载下为尽力而为：10 秒超时后不会阻断调用。
- 官方提醒：安装代理本身并不构成保护；不要把 decision: allow 单独视为可继续执行的许可，应结合 is_clean 与 inspection_complete 判断。
【其他】 仓库地址为 https://github.com/sunglasses-dev/sunglasses，官方在 README 中建议若觉得有用可为仓库加星，并提到浏览器试用地址 sunglasses.dev/scan。安装与升级注意事项：使用已激活的虚拟环境可将安装与 shell 解析到的 sunglasses 保持在同一环境；若已安装旧版本，--upgrade 很重要；curl -fsSL 会在 HTTP 错误时失败而不会保存错误页面，因此脚本仅在下载成功时运行。文中提及的演示脚本会写入三个 fixture 文件到临时目录并故意扫描第四个不存在的路径，共五次扫描器调用（归档被扫描两次：人类可读输出与 JSON）；被扫描内容始终保持为数据，绝不执行，ZIP 不会被解压。演示中的计时与呈现会因环境而异，脚本会检查退出状态与 ZIP 覆盖字段，如有不符请对照已安装版本报告。
