MaxHu-xuan/chat-archive-guard

Audit AI chat exports locally before sharing or migration. Find possible secrets, personal-data patterns, broken JSON/JSONL, SQLite issues, and scan gaps—without uploading the archive.

ChatArchiveGuard란?

ChatArchiveGuard는 내보낸 채팅 로그가 포함된 로컬 디렉토리(또는 단일 파일)를 감사하는 작은 순수 Python 명령줄 유틸리티입니다. 파일을 수정하거나 데이터를 어디로든 보내지 않고 스캔하여 다음을 보고합니다:

잠재적 비밀 또는 개인 데이터 패턴 – 예: API 키, 베어러 토큰, 이메일 주소, 전화번호, 신용카드 유사 번호.
형식 문제 – 잘못된 UTF-8, 손상된 JSON/JSONL 파일.
SQLite 상태 – 데이터베이스의 개인 복사본(WAL/SHM 사이드카 포함)에 대해 SQLite의 PRAGMA quick_check(1)을 실행하고 일반 및 FTS 테이블에서 읽을 수 있는 텍스트를 찾습니다.
커버리지 격차 – 검사할 수 있는 모든 파일이 실제로 스캔되었는지, 아니면 권한 문제, 리소스 제한 또는 지원되지 않는 파일 유형으로 인해 스캔이 잘렸는지 알려줍니다.

이 도구는 전달 전 게이트로 사용됩니다: 채팅 내보내기를 분석가, 백업 파이프라인 또는 타사 서비스에 넘기기 전에 빠른 로컬 감사를 실행하여 우발적인 자격 증명 유출이나 손상된 파일을 잡을 수 있습니다.

주요 기능(README에 설명된 대로)

기능	작동 방식	출력에서 볼 수 있는 것
비밀 및 PII 감지	개인 키, 공급자 토큰, JWT, 이메일 주소, 전화번호, IP, ID 번호, Luhn 검증된 카드 번호 등에 대한 정규식 기반 패턴	`secret.provider_key` 또는 `pii.email`과 같은 카테고리 수(실제 값은 표시되지 않음).
형식 검증	UTF-8 유효성을 확인하고 JSON/JSONL 파일을 구문 분석합니다.	`format.invalid_json` 또는 `format.invalid_jsonl`과 같은 카테고리.
SQLite 무결성	기본 DB와 WAL/SHM 파일을 개인 임시 디렉토리에 복사하고, 복사본을 열고, `PRAGMA quick_check(1)`을 실행하고, 텍스트 열(FTS 가상 테이블 포함)을 스캔합니다.	`sqlite.*` 아래의 카테고리(예: `sqlite.quick_check_failed`).
디렉토리 커버리지 보고	`files_seen`(발견된 모든 파일)과 `files_scanned`(콘텐츠 검사에 들어간 파일)을 추적하고, 제한이나 오류가 전체 커버리지를 방해할 때 `complete`/`truncated` 플래그를 지정합니다.	JSON/텍스트 보고서의 부울 플래그 및 숫자 카운터.
요약 전용 모드	`--summary-only`는 파일 경로와 개별 발견 세부 정보를 제거하고 집계 수만 남깁니다 – 파일 이름이나 데이터를 노출하고 싶지 않은 CI 파이프라인에 유용합니다.	동일한 종료 코드이지만 `details_omitted`/`findings_omitted`가 true로 설정됩니다.
하드 리소스 제한	파일 크기, 파일 수, SQLite 행, 값 크기 및 총 발견 수에 대한 상한으로 스캔을 예측 가능하게 유지합니다.	제한에 도달하면 특별한 발견이 추가되고 `truncated`가 true가 됩니다.
크로스 플랫폼 안전	Python 표준 라이브러리만 사용합니다. 심볼릭 링크를 따르지 않고 SQLite를 안전하게 열 수 없는 플랫폼(Windows)에서는 도구가 해당 파일을 중단하고 데이터 유출 위험을 감수하는 대신 안전하지 않다고 표시합니다.	Windows에서 `sqlite.sidecar_unsafe` 카테고리.

누가 사용할까요?

데이터 엔지니어 또는 ML 운영 팀 – Slack, Teams, Discord 등에서 채팅 내보내기 덤프를 받고 비밀이 다운스트림 파이프라인으로 실수로 전송되지 않도록 해야 하는 경우.
보안 감사자 – 보관 또는 공유 전에 오프라인 개인정보 보호 검사를 수행하는 경우.
CI/CD 파이프라인 – 채팅 내보내기에 플래그된 비밀 또는 잘못된 파일이 포함된 경우 빌드를 자동으로 거부하는 경우.
개인 개발자 – 채팅 아카이브를 버전 관리에 커밋하기 전에 빠른 오프라인 상태 확인을 원하는 경우.

시작하는 방법

설치(Python 3.11 이상 필요):

python3 -m venv .venv && . .venv/bin/activate
python -m pip install chat-archive-guard

디렉토리 스캔 실행:

chat-archive-guard /path/to/export          # 사람이 읽을 수 있는 텍스트 보고서
chat-archive-guard /path/to/export --json   # JSON 보고서
chat-archive-guard /path/to/export --json --summary-only   # CI 친화적인 집계 전용

종료 코드 해석:
- 0 – 발견 사항이 없고 스캔이 모든 것을 덮었습니다.
- 1 – 최소 하나의 발견 또는 불완전한 커버리지.
- 2 – 잘못된 경로/인수.

제한 사항 및 하지 않는 일

채팅 메시지가 완전하고, 진본이며, 변조되지 않았는지 검증하지 않습니다.
압축 아카이브, 암호화된 파일, 이미지, 오디오 또는 독점 바이너리 형식을 읽지 않습니다.
본격적인 DLP 또는 포렌식 도구로 작동하지 않습니다. 발견은 패턴 기반이며 오탐/부정 오탐을 포함할 수 있습니다.
데이터를 업로드하지 않습니다. 유일한 네트워크 활동은 선택적 패키지 설치입니다.

더 많은 정보를 찾을 수 있는 곳

소스 코드 및 이슈 트래커: https://github.com/MaxHu-xuan/chat-archive-guard
라이선스: Apache 2.0(LICENSE 참조)
상세 위협 모델: THREAT_MODEL.md
릴리스 노트 및 변경 로그: RELEASE_NOTES.md, CHANGELOG.md

TL;DR

ChatArchiveGuard는 채팅 내보내기 파일에서 비밀, 개인 데이터, 잘못된 JSON/UTF-8 및 SQLite 무결성 문제를 안전하게 스캔하는 가벼운 오프라인 Python 도구로, 명확한 집계 보고서와 CI 호환 종료 코드를 제공합니다. 채팅 로그를 공유하거나 처리하기 전에 빠른 개인정보 우선 게이트가 필요한 모든 사람에게 유용합니다.