sunglasses

SUNGLASSES es una capa de inspección de entrada de código abierto, solo local, para agentes de IA, descrita en su README como un firewall de entrada. Está escrita en Python y publicada bajo la licencia MIT. El proyecto escanea el contenido antes de que un agente actúe sobre él y reporta los hallazgos en lugar de reescribir o eliminar silenciosamente el contenido. Cubre seis tipos de medios: texto, imágenes, audio, video, PDFs y códigos QR/barcode. El escaneo de imágenes puede usar OCR, metadatos EXIF y detección de texto oculto; el escaneo de PDFs lee el texto de la página, metadatos y anotaciones; los escaneos profundos de audio y video utilizan reconocimiento de voz y extracción de subtítulos. El escáner apunta a inyección de prompts, exfiltración de credenciales, inyección de comandos, envenenamiento de memoria, ingeniería social y técnicas de evasión como trucos Unicode, ofuscación RTL, leetspeak, codificación Base64 y sustitución de homógrafos. SUNGLASSES está orientado primero al inglés. El README indica que el conjunto completo de reglas está en inglés; 13 idiomas tienen exactamente dos patrones dedicados cada uno; 7 idiomas solo a nivel de palabras clave; y persa y bengalí aparecen solo como nombres sin patrón ni palabra clave dedicada. La normalización es independiente del idioma. El proyecto advierte que no se debe esperar paridad con el inglés para otros idiomas y marca la cobertura más profunda de idiomas como una vía v0.6+. La instalación se realiza mediante pip: `pip install sunglasses` para escaneo de texto sin dependencias, con extras de media o all para imágenes, PDFs, códigos QR, audio y video. La CLI ofrece los comandos scan, check, demo, info y report. La API de Python expone `SunglassesEngine` para texto y `SunglassesScanner` para medios. Otras superficies de integración incluyen un servidor MCP, integraciones con LangChain y CrewAI, salida SARIF 2.1.0 para CI y una demo en navegador para texto, repositorios GitHub e imágenes. La CLI utiliza un contrato explícito de códigos de salida. 0 significa que se leyó toda la entrada y no se encontró amenaza. 1 indica que se encontró una amenaza. 2 representa un error de uso u operativo donde nada se escaneó en el alcance solicitado. 3 indica inspección incompleta: no se encontró nada en la parte que pudo leerse, pero alguna parte no pudo leerse, como un archivo comprimido, un archivo de audio sin escaneo profundo o entrada que supera el límite de tamaño. La precedencia es 1 > 3 > 2 > 0. La salida JSON separa `threat_found`, `inspection_complete` e `is_clean`, y reporta `truncated` y `extraction_complete`. El motor lee como máximo 1 MB por defecto, y un escaneo que alcanza el límite informa `truncated` y `bytes_scanned` en lugar de pasar silenciosamente como limpio. El firewall v0.4 se instala como un hook PreToolUse de Claude Code y se describe como best‑effort: tiene un timeout de 10 segundos y un hook expirado no bloquea la llamada. Puede fijar (pin) descriptores de herramientas MCP y verificar si cambiaron, bloquear secretos de formato exacto en llamadas de herramienta que puedan enviar bytes por la red, aplicar un archivo de política de usuario y escribir recibos que registren un SHA‑256 de la entrada de la herramienta en lugar de la entrada misma. El proyecto separa hechos determinísticos, que pueden bloquearse de forma rígida, de detecciones, que se escalan al usuario en lugar de bloquear automáticamente. Falla abierto y registra cuando una llamada no fue revisada. El README enumera limitaciones honestas: el pin de descriptores no es en tiempo real; el hook ve solo el texto de la llamada de herramienta, no los archivos detrás; una‑líneas de intérprete o socket pueden ocultar egresos; la vía WARN está desactivada por defecto. Las cifras publicadas de rendimiento y benchmarks incluyen 1 540 patrones, 6 931 palabras clave únicas, 118 categorías de ataque, 17 técnicas de normalización y un recall interno de 64/64 en el conjunto de fixtures de ataque incluido. El benchmark del README usa 38 ataques reales de entrada de agente y 76 READMEs de código abierto bien conocidos como negativos, reportando precisión 86.1 %, recall 97.4 %, F1 0.914, 30/30 ataques de forma conocida capturados y 7/8 paráfrasis semánticas novedosas capturadas. Señala que el único fallo conocido es una línea de instalación pipe‑to‑shell que también aparece en READMEs limpios, y que una prueba asegura que el escáner no la marque. Las cifras de latencia dadas son aproximadamente 0.7 ms para una entrada corta, 4.2 ms para una cadena de ataque típica, 311 ms para un README real, y un rendimiento sostenido de alrededor de 26 KB por segundo en un solo hilo. El README indica que estos datos se regeneran a partir de un corpus interno y que el hardware puede variar. El escaneo profundo de audio y video requiere Whisper y FFmpeg, y el proyecto marca esos escaneos de medios como experimentales. El escaneo se ejecuta localmente: el README afirma que no hay nube, ni claves API y ni telemetría para el escaneo. También señala que el escáner estático no ejecuta el contenido escaneado, mientras que el comando pin lanza servidores MCP configurados solo después de solicitar consentimiento y lo rechaza sin consentimiento en contextos no atendidos. El proyecto se posiciona como una capa fundacional local que puede usarse sola o junto a herramientas de guardia en la nube.