sunglasses

SUNGLASSES는 AI 에이전트를 위한 로컬 전용 입력 검사 레이어이며, README에서는 이를 입력 방화벽이라고 설명합니다. Python으로 작성되었으며 MIT 라이선스로 배포됩니다. 이 프로젝트는 에이전트가 동작하기 전에 콘텐츠를 스캔하고, 조용히 재작성하거나 삭제하는 대신 발견 사항을 보고합니다. 텍스트, 이미지, 오디오, 비디오, PDF, QR/바코드 등 6가지 미디어 유형을 지원합니다. 이미지 스캔은 OCR, EXIF 메타데이터 및 숨은 텍스트 탐지를 사용할 수 있으며, PDF 스캔은 페이지 텍스트, 메타데이터 및 주석을 읽습니다. 오디오와 비디오의 깊은 스캔은 음성‑텍스트 변환 및 자막 추출을 이용합니다. 스캐너는 프롬프트 인젝션, 자격 증명 유출, 명령 인젝션, 메모리 중독, 사회공학 및 Unicode 트릭, RTL 난독화, 리트스피크, Base64 인코딩, 동형 글자 치환과 같은 회피 기법을 목표로 합니다. SUNGLASSES는 영어 중심입니다. README에 따르면 전체 규칙 집합은 영어이며, 13개 언어는 각각 정확히 두 개의 전용 패턴을 가지고, 7개 언어는 키워드 수준만 지원합니다. 페르시아어와 벵골어는 이름만 나열되고 전용 패턴이나 키워드가 없습니다. 정규화는 언어에 독립적입니다. 프로젝트는 비영어와 영어 간의 동등성을 기대하지 말 것을 경고하고, 더 깊은 언어 지원은 v0.6+ 라인에서 제공된다고 명시합니다. 설치는 pip를 통해 이루어집니다: `pip install sunglasses` 로 텍스트 스캔만 하는 경우 의존성이 없으며, 이미지, PDF, QR 코드, 오디오 및 비디오를 포함하려면 media 또는 all extras를 추가합니다. 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 훅으로 설치되며, 최선 노력(best‑effort) 방식으로 10초 타임아웃을 갖습니다. 타임아웃이 발생한 훅은 호출을 차단하지 않습니다. MCP 툴 디스크립터를 고정(pin)하고 변경 여부를 확인하며, 바이트를 전송할 수 있는 툴 호출에서 정확한 형식의 비밀을 차단하고, 사용자 정책 파일을 적용하며, 입력 자체가 아니라 SHA‑256 해시를 기록하는 영수증을 작성합니다. 프로젝트는 결정론적 사실(hard‑block 가능한)과 탐지(사용자에게 알리고 자동 차단하지 않는)를 구분합니다. 검사를 수행하지 못한 경우에는 열려 있는(fail open) 상태로 기록합니다. README에는 정직한 제한 사항이 명시되어 있습니다: 디스크립터 고정은 실시간이 아니며, 훅은 툴 호출 텍스트만 보며 파일은 보지 못하고, 인터프리터나 소켓 일회성 명령은 탈출을 숨길 수 있으며, WARN 라인은 기본적으로 비활성화됩니다. 공개된 성능 및 벤치마크 수치는 1,540개의 패턴, 6,931개의 고유 키워드, 118개의 공격 카테고리, 17개의 정규화 기법, 그리고 제공된 공격 픽스처 세트에서 64/64의 내부 재현율을 포함합니다. README 벤치마크는 38개의 실제 에이전트 입력 공격과 76개의 잘 알려진 오픈소스 README를 부정 사례로 사용했으며, 정밀도 86.1%, 재현율 97.4%, F1 0.914, 알려진 형태 공격 30/30, 새로운 의미 변형 7/8을 잡았습니다. 하나의 알려진 누락은 깨끗한 README에도 나타나는 파이프‑투‑쉘 설치 라인이며, 테스트에서는 스캐너가 이를 플래그하지 않도록 검증합니다. 지연 시간은 짧은 입력에 약 0.7 ms, 일반적인 공격 문자열에 약 4.2 ms, 실제 README에 약 311 ms이며, 단일 스레드에서 초당 약 26 KB의 지속 처리량을 보입니다. README는 이 수치가 저장소 내 코퍼스에서 재생성된 것이며 하드웨어에 따라 달라질 수 있음을 언급합니다. 깊은 오디오·비디오 스캔은 Whisper와 FFmpeg이 필요하며, 해당 미디어 스캔은 실험적이라고 표시됩니다. 스캔은 모두 로컬에서 실행됩니다: README는 클라우드, API 키, 텔레메트리를 사용하지 않으며, 정적 스캐너는 스캔된 콘텐츠를 실행하지 않는다고 명시합니다. 또한 pin 명령은 동의가 있을 때만 구성된 MCP 서버를 시작하고, 무인 환경에서는 동의 없이는 거부합니다. 프로젝트는 로컬 기반의 기초 레이어로서 단독으로 혹은 클라우드 가드레일 도구와 함께 사용할 수 있다고 위치를 잡고 있습니다.