WeChat 4.x 채팅 기록 복호화 및 조회 (macOS + Windows)
최초 로드 자가 진단 (Agent 필수 실행)
python3 -c "import platform; print(platform.system())"
claude mcp list 2>&1 | grep -q "wechat.*Connected" && echo "MCP_OK" || echo "MCP_MISSING"
test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "KEY_OK" || echo "KEY_MISSING"
| 상태 | 조치 |
|---|---|
MCP_MISSING | macOS bash setup.sh / Windows powershell -File setup.ps1, "Claude Code 재시작" 안내 |
KEY_MISSING | 해당 플랫폼에 맞는 "키 추출" 절차 실행 (Windows는 키 추출 후 python scripts\windows\decrypt_all.py로 전체 DB를 평문으로 복호화) |
| 모두 OK | MCP 도구 직접 사용 |
Windows 자가 진단 (PowerShell, 위 macOS 3항목과 동일):
python -c "import frida, Crypto; print('DEPS_OK')" # 없음 → pip install frida pycryptodome Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\key_windows.txt" # 없음 → extract_raw_key.py 로 키 추출 Test-Path "$env:USERPROFILE\.claude\skills\wechat-decrypt\decrypted" # 없음 → decrypt_all.py 로 전체 DB 복호화해당 단계가 없으면 각각 실행: deps→
setup.ps1, key→extract_raw_key.py, 평문 DB→decrypt_all.py.
자가 진단을 건너뛰지 마세요.
Agent 트리거 규칙
| 사용자 의도 | 조치 |
|---|---|
| "내 위챗 봐줘" "최근 채팅" "누가 나 찾았어" "새 메시지 뭐야" | MCP: wechat_recent_messages / wechat_chat_summary |
| "XX와의 채팅 검색" "XX가 말한" | MCP: wechat_search_messages |
| "대화 목록 보여줘" "어떤 단체방이 있어" | MCP: wechat_list_chats |
| "XX와의 채팅 읽어줘" | MCP: wechat_read_chat |
| "XX와의 채팅 내보내기" "XX를 바탕화면에 내보내기" | 먼저 ① 모델 확인(아래 참조), 이후 python3 scripts/common/export_chat.py <contact> [--start/--end/--year] [-o path] (날짜 미지정=전체 기록; 모델 있으면 기본적으로 텍스트 변환, --no-transcribe 로 끌 수 있음; 음성 변환 결과는 voice_cache.json에 영구 캐시되어 재내보내기 시 즉시 반환) |
| "XX의 음성 텍스트 변환" "음성을 글자로" "음성을 텍스트로 내보내기" | python3 scripts/common/export_chat.py <contact> --transcribe, 또는 별도로 python3 scripts/common/transcribe_db.py <contact> -o map.json |
| "위챗 업데이트됨" "다시 크랙" "키失效" | 아래 해당 플랫폼의 "키 추출" 절차 실행 |
① 내보내기 사전——음성 텍스트 변환 모델 확인 (기본 실행)
음성이 포함될 수 있는 대화를 내보내거나 변환하기 전에 먼저 모델이 준비되었는지 확인:
test -d ~/.cache/huggingface/hub/models--mlx-community--whisper-large-v3-mlx && echo MODEL_OK || echo MODEL_MISSING
| 결과 | 조치 |
|---|---|
MODEL_OK | 내보내기 기본적으로 음성 텍스트 변환 활성화 (스크립트가 모델을 감지하면 자동 변환, --transcribe 불필요; 사용자가 명시적으로 원하지 않을 때만 --no-transcribe 추가) |
MODEL_MISSING | 먼저 사용자에게 설치 여부 확인 (whisper-large-v3 ~3GB, 순수 오프라인 일회성). 설치→--transcribe 추가 (최초 다운로드 후 자동 변환); 미설치→일반 내보내기, 음성은 [Audio]로 유지 |
스크립트 측에도 동일한 로직이 내장되어 있음 (모델 있음→기본 변환, 없음→[Audio] 유지 및 안내). 그러나 MODEL_MISSING 시 Agent는 반드시 사용자에게 물어보고, 3GB를 임의로 다운로드하지 마세요.
MCP 도구 (등록명 wechat)
| 도구 | 매개변수 | 용도 |
|---|---|---|
wechat_list_chats | 없음 | 모든 대화 (그룹명+별명 이미 파싱됨) |
wechat_read_chat | contact, limit(50), days(7) | 특정 대화 |
wechat_search_messages | keyword, days(30), limit(50) | 전체 검색 |
wechat_recent_messages | days(3), limit(100) | 최근 동향 |
wechat_chat_summary | days(3) | 구조화된 요약 + 할 일 |
[나] = 사용자가 보낸 메시지, [상대방] = 연락처가 보낸 메시지.
음성 텍스트 변환 (완전 자동)
음성 메시지(local_type=34)의 오디오는 SILK v3 형식으로 media_0.db의 VoiceInfo.voice_data에 저장되며, svr_id == server_id로 정렬됩니다. 체인: VoiceInfo 직접 추출 → pilk 디코딩 SILK→wav → whisper large-v3 변환 → server_id별로 다시 채움. 완전 자동, 배치, 순수 오프라인, BlackHole/재생/재시작 불필요. 기본 동작: 모델이 캐시되어 있으면 자동 변환; --transcribe 강제 (최초 다운로드 ~3GB 모델 포함, 캐시 ~/.cache/huggingface/); --no-transcribe 비활성화. 백엔드는 플랫폼에 따라 자동 전환: macOS = mlx-whisper (Apple Silicon), Windows = faster-whisper (CPU int8, 필요시 다운로드); 기존 BlackHole+Swift 방식은 langlobal 개발 저장소에 있음.
명령줄 entry (로직 핵심; MCP는 선택적 얇은 외관)
로직 핵심은 scripts/common/query.py (명령줄)에 있으며, server.py의 MCP 도구는 이를 호출하는 역할만 합니다. Agent 호출 시 --json을 추가하여 구조화된 출력을 받는 것을 권장 (파싱이 안정적이며 텍스트 레이아웃 영향 없음); 사람이 디버깅할 때는 추가하지 않고 텍스트로 확인.
SKILL_DIR=~/.claude/skills/wechat-decrypt
python3 "$SKILL_DIR/scripts/common/query.py" list
python3 "$SKILL_DIR/scripts/common/query.py" recent -d 3 --json # agent 용 --json
python3 "$SKILL_DIR/scripts/common/query.py" search 키워드 --json
# 하위 명령어: list / read <contact> / search <kw> / recent / summary / stats / media / openfile
키 체계 (양쪽 플랫폼 공통)
- Raw Key: 64 hex, 장치별 독립적 (WeChat 4.0: 동일 계정이라도 macOS와 Windows의 raw key가 다르므로 상호 사용 불가); WeChat이 업데이트되지 않으면 계속 유효
- 파생 공식:
PBKDF2-HMAC-SHA512(raw_key, db_file_salt, 256000) → 32 bytes - SQLCipher 매개변수:
PRAGMA key = "x'<derived>'"; PRAGMA kdf_iter = 1; PRAGMA cipher_compatibility = 4; PRAGMA cipher_page_size = 4096;
데이터베이스 경로
| 플랫폼 | 경로 |
|---|---|
| macOS | ~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/{wxid}/db_storage/ |
| Windows | ~/Documents/xwechat_files/{wxid}/db_storage/ |
키 추출
macOS
Agent 실행 흐름
- 재서명 확인:
codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"NEED_RESIGN→ 사용자에게sudo codesign --force --deep --sign - /Applications/WeChat.app실행 안내
bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh실행- 스크립트가 WeChat을 실행 → 사용자에게 QR 코드 로그인 안내 → 로그인 후 키가 자동으로
key.txt에 기록됨 - 확인:
test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK" - 추출 후 반드시 사용자에게 서명 복원 안내: adhoc 재서명은 단방향 파괴적 작업으로, Tencent 원본 서명을 덮어쓰므로 WeChat 스크린샷/데이터 접근 시 권한 팝업이 반복적으로 나타날 수 있음. codesign으로 타사 서명을 복원할 수 없으며, WeChat 재설치만이 서명을 복구합니다. 채팅 기록은 독립 컨테이너 디렉토리(
~/Library/Containers/com.tencent.xinWeChat/)에 있으므로/Applications/WeChat.app재설치는 영향을 받지 않습니다. 키 추출 후 일상적인 메시지 조회는 DB를 읽기 전용으로 사용하므로 재서명이 더 이상 필요하지 않습니다.
중요 인지 사항
- 재서명은 "키 추출" 순간에만 필요하며, 추출 후 즉시 WeChat을 재설치하여 서명을 복원해야 합니다.
- 반복적인 권한 팝업 = WeChat 서명이 adhoc 상태임을 나타내는 증상이며, Claude Code/MCP로 인한 것이 아닙니다.
- 키는 장치별로 독립적입니다 (동일 계정의 각 기기 키가 다르며 상호 사용 불가). WeChat이 업데이트되지 않으면 계속 유효하므로 반복 추출할 필요가 없습니다.
원리
WeChat 4.x macOS 버전은 sqlite3_key를 호출하지 않으며 (Apple 시스템 SQLite의 해당 함수는 껍데기), 대신 WCDB 통합 암호화 계층을 통해 CCKeyDerivationPBKDF (CommonCrypto)를 호출합니다. Frida는 Module.findGlobalExportByName (Frida 17.x+ API)을 사용하여 해당 함수를 후킹하고, passwordLen=32, rounds>1000, dkLen=32 조건에서 비밀번호 매개변수(raw key)를 캡처합니다.
Windows (이미 해결: 키 추출→복호화→읽기, macOS와 동등한 성능)
현황 (2026-06-06 UTM 실측 통과): 키 추출→전체 DB 복호화→MCP/내보내기/음성 변환, macOS와 동일한 성능. message_0에서 99개 대화/1384개 메시지 추출. 전체 과정은 docs/2026-06-06-windows-raw-key-journey.md 참조.
Agent 실행 흐름
- WeChat 로그인
- 키 추출:
python scripts\windows\extract_raw_key.py→ 안내에 따라 데스크탑에서 수동으로 WeChat 재시작 (필수; schtasks/SSH로 실행하면 빈 껍데기만 뜨고 DB를 읽지 않음) → 스크립트가 자동으로 race-attach + hook sha512로 raw key 캡처 + 검증,key_windows.txt에 기록 - 전체 DB 복호화:
python scripts\windows\decrypt_all.py→ raw key를 사용하여 db_storage의 모든 DB를decrypted\{wxid}_<device>\db_storage\에 복호화 (평문) - Claude Code 재시작 → MCP 도구, 내보내기, 음성 변환이 macOS와 완전히 동일 (server/export/transcribe는
DB_BACKEND="sqlite3"로 평문 DB를 읽음; 음성은 faster-whisper 사용)
단일 DB 확인/디버깅은 scripts\windows\decrypt_read.py <raw_key> 사용 (message_0만 복호화하여 확인).
키 추출 원리 (sha512 엔트리 후킹 + HMAC ipad)
핵심: raw key/K1은 메모리에서 삼중 보호(AES-NI 라운드 키/사용 후 삭제/secure mem, 메모리 무차별 대입 모두 실패)되지만, SQLCipher 파생 키는 PBKDF2-HMAC-SHA512를 사용하므로 HMAC이 ipad 블록을 구성하는 순간 key의 평문 key XOR 0x36 (이후 96바이트는 항상 0x36)이 나타납니다——모든 보호를 우회하여 직접 획득.
extract_raw_key.py는 자체 포함: 자동으로 sha512 엔트리 위치 탐색 (K 상수 0x428a2f98d728ae22 검색→xref→역어셈블, 주소 하드코딩 불필요, WeChat 버전이 바뀌어도 작동) + race-attach (DB 열기 전에) + 엔트리 후킹 (rdx=input block) + ipad 감지 + 자동 검증 (PBKDF2→AES page1 출력=raw key 일반 / 직접 AES 출력=K1 단일 DB). 실행 시 PBKDF2(raw,salt)로 raw key 노출; 런타임 page-MAC은 mac_key만 노출(무용) → 반드시 race로 시작 시점을 잡아야 함.
frida는 ARM 에뮬레이션(xtajit이 x64 번역)에서도 WeChat 내부 x64 함수를 후킹 가능 (1127만 회 검증); spawn 비호환 시 race-attach 사용.
- 데이터 경로:
C:\Users\<사용자>\Documents\xwechat_files\{wxid}_<device>\db_storage\.wechat-dump-rs는 DMCA로 차단되었으며, 본 방법이 대체합니다. - 개발 기간 전체 공략 스크립트(위치 탐색/brute/실패 기록)는 langlobal 개발 저장소에 있으며, 실행은
extract_raw_key.py+decrypt_all.py만 있으면 됩니다.
배포 및 설치
전체 skill 디렉토리를 복사합니다. 수신자는 다음을 실행:
macOS: bash setup.sh
Windows: powershell -File setup.ps1
key.txt, contacts.json, all_keys.json, voice_cache.json은 개인 데이터이므로 배포 전에 삭제합니다 (이미 .gitignore에 포함).
파일 목록
~/.claude/skills/wechat-decrypt/ # 실행 단위; 전체 개발(tests/docs/공략 스크립트/legacy)은 langlobal 개발 저장소에 있음
├── server.py config.py crypto.py db.py contacts.py message.py ← MCP 실행 핵심(6), db.py 이중 백엔드
├── scripts/
│ ├── common/ ← 크로스 플랫폼: export_chat(내보내기+변환) transcribe_db voice_decode sqlcipher_decrypt read_doc export_media verify_key
│ ├── macos/ ← extract_key.sh + hook_pbkdf.js (CCKeyDerivationPBKDF)
│ └── windows/ ← extract_raw_key.py(자체 포함 키 추출) decrypt_all.py(전체 DB 복호화→평문) decrypt_read.py(단일 DB 확인)
├── setup.sh / setup.ps1 ← 플랫폼 설치
├── SKILL.md README.md LICENSE
├── key.txt key_windows.txt ← .gitignore
└── contacts.json ← .gitignore
의존성: macOS 전역 python (mcp/frida/cryptography/pilk/mlx-whisper/zstd); Windows (mcp/frida/pycryptodome/pilk/faster-whisper/zstandard). 음성 모델 캐시 ~/.cache/huggingface/.