sunglasses

SUNGLASSES 是一个开源且仅限本地运行的 AI Agent 输入检查层，其 README 将其描述为输入防火墙。该项目使用 Python 编写，采用 MIT 许可证发布。它在 Agent 执行操作之前扫描内容，并报告发现的结果，而不是静默地重写或删除内容。它涵盖六种媒体类型：文本、图像、音频、视频、PDF 和 QR/条形码。图像扫描可使用 OCR、EXIF 元数据和隐藏文本检测；PDF 扫描可读取页面文本、元数据和注释；音频和视频深度扫描则使用语音转文本和字幕提取。该扫描器针对提示词注入、凭据外泄、命令注入、内存中毒、社会工程学以及 Unicode 技巧、RTL 混淆、leetspeak、Base64 编码和同形异义词替换等规避技术。 SUNGLASSES 以英语为主。README 指出完整规则集为英语；13 种语言每种仅有两个专用模式；7 种语言仅支持关键字级别；波斯语和孟加拉语仅列出名称，没有专用模式或关键字。归一化处理与语言无关。项目警告不要期望非英语语言能达到与英语相同的水平，并将更深层的语言覆盖标记为 v0.6+ 的开发方向。 安装通过 pip 完成：pip install sunglasses 可实现零依赖的文本扫描，安装 media 或 all 额外选项可支持图像、PDF、QR 码、音频和视频。CLI 提供 scan、check、demo、info 和 report 命令。Python API 提供了用于文本的 SunglassesEngine 和用于媒体的 SunglassesScanner。其他集成接口包括 MCP 服务器、LangChain 和 CrewAI 集成、用于 CI 的 SARIF 2.1.0 输出，以及一个支持文本、GitHub 仓库和图像的浏览器演示版。 CLI 使用明确的退出码约定：0 表示完整读取输入且未发现威胁；1 表示发现威胁；2 表示用法或操作错误，导致请求范围内未扫描任何内容；3 表示检查不完整：在可读部分未发现威胁，但某些部分无法读取（如存档、未进行深度扫描的音频文件或超过大小限制的输入）。优先级为 1 > 3 > 2 > 0。JSON 输出将 threat_found、inspection_complete 和 is_clean 分开，并报告 truncated 和 extraction_complete。引擎默认最多读取 1 MB，达到上限的扫描将报告 truncated 和 bytes_scanned，而非静默地通过检查。 v0.4 防火墙可作为 Claude Code PreToolUse 钩子安装，被描述为“尽力而为”：它有 10 秒超时限制，超时钩子不会阻塞调用。它可以固定 MCP 工具描述符并检查其是否更改，在可能发送字节的工具调用中拦截特定格式的密钥，强制执行用户策略文件，并记录包含工具输入 SHA-256 哈希值的收据而非输入本身。项目将可硬拦截的确定性事实与需升级至用户处理（而非自动拦截）的检测结果区分开来。它采用“故障开启”（fail open）模式，并记录未检查的调用。README 列出了诚实的局限性：描述符固定并非实时；钩子可见工具调用文本而非其背后的文件；解释器或套接字单行命令可能隐藏外传；WARN 级别默认关闭。 公布的性能和基准数据包括 1,540 个模式、6,931 个唯一关键字、118 个攻击类别、17 种归一化技术，以及在交付的攻击测试集上 64/64 的内部召回率。README 基准测试使用 38 个真实的 Agent 输入攻击和 76 个知名的开源 README 作为负样本，报告精确率为 86.1%，召回率为 97.4%，F1 分数为 0.914，捕获了 30/30 个已知形状攻击和 7/8 个新语义改写攻击。它指出唯一的一次漏报是一个在干净的 README 中也出现的 pipe-to-shell 安装行，且测试确认扫描器不会将其标记为威胁。延迟数据为：短输入约 0.7 毫秒，典型攻击字符串约 4.2 毫秒，真实 README 约 311 毫秒，单线程持续吞吐量约为每秒 26 KB。README 注明这些数据是从仓库内语料库重新生成的，实际硬件表现会有所不同。 深度音频和视频扫描需要 Whisper 和 FFmpeg，项目将这些媒体扫描标记为实验性。扫描在本地运行：README 声明扫描过程无云端、无 API 密钥且无遥测。它还指出静态扫描器不会执行被扫描的内容，而 pin 命令仅在征得同意后才启动配置的 MCP 服务器，在无人值守环境下若无同意则拒绝执行。该项目将自己定位为一个本地基础层，可单独使用或与云端防护工具配合使用。