Community연구 & 데이터 분석github.com

tzwkb/wechat-decrypt

에이전트 스킬 — WeChat 4.x 채팅 기록 복호화 및 조회 (macOS + Windows): MCP 읽기/검색, 내보내기, 음성 텍스트 변환.

wechat-decrypt란 무엇인가요?

이 스킬은 MCP 프로토콜을 통해 WeChat 4.x의 채팅 기록을 안전하게 복호화하고 검색 및 내보낼 수 있는 에이전트 도구입니다. macOS와 Windows를 모두 지원하며, SQLCipher로 암호화된 데이터베이스에서 원시 키(raw key)를 추출하고 PBKDF2-HMAC-SHA512 파생 공식을 사용하여 복호화합니다. 주요 기능으로는 최근 메시지 보기, 특정 연락처 검색, 대화 목록 조회, 채팅 내보내기, 음성 메시지 자동 텍스트 변환(whisper large-v3 기반, 오프라인) 등이 있습니다. 에이전트는 사용자의 의도에 따라 MCP 도구(예: wechat_recent_messages, wechat_search_messages)를 호출하거나 명령줄 스크립트(query.py)를 직접 실행합니다. macOS에서는 Frida를 이용해 CCKeyDerivationPBKDF 함수를 후킹하여 키를 추출하고, Windows에서는 HMAC-SHA512의 ipad 블록을 후킹하여 키를 획득한 후 전체 데이터베이스를 평문으로 복호화합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add tzwkb/wechat-decrypt

Installed? Explore more 연구 & 데이터 분석 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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_MISSINGmacOS bash setup.sh / Windows powershell -File setup.ps1, "Claude Code 재시작" 안내
KEY_MISSING해당 플랫폼에 맞는 "키 추출" 절차 실행 (Windows는 키 추출 후 python scripts\windows\decrypt_all.py로 전체 DB를 평문으로 복호화)
모두 OKMCP 도구 직접 사용

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_chatcontact, limit(50), days(7)특정 대화
wechat_search_messageskeyword, days(30), limit(50)전체 검색
wechat_recent_messagesdays(3), limit(100)최근 동향
wechat_chat_summarydays(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 실행 흐름

  1. 재서명 확인: codesign -dv /Applications/WeChat.app 2>&1 | grep -q "Signature=adhoc" || echo "NEED_RESIGN"
    • NEED_RESIGN → 사용자에게 sudo codesign --force --deep --sign - /Applications/WeChat.app 실행 안내
  2. bash ~/.claude/skills/wechat-decrypt/scripts/macos/extract_key.sh 실행
  3. 스크립트가 WeChat을 실행 → 사용자에게 QR 코드 로그인 안내 → 로그인 후 키가 자동으로 key.txt에 기록됨
  4. 확인: test -f ~/.claude/skills/wechat-decrypt/key.txt && echo "OK"
  5. 추출 후 반드시 사용자에게 서명 복원 안내: 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 실행 흐름

  1. WeChat 로그인
  2. 키 추출: python scripts\windows\extract_raw_key.py → 안내에 따라 데스크탑에서 수동으로 WeChat 재시작 (필수; schtasks/SSH로 실행하면 빈 껍데기만 뜨고 DB를 읽지 않음) → 스크립트가 자동으로 race-attach + hook sha512로 raw key 캡처 + 검증, key_windows.txt에 기록
  3. 전체 DB 복호화: python scripts\windows\decrypt_all.py → raw key를 사용하여 db_storage의 모든 DB를 decrypted\{wxid}_<device>\db_storage\에 복호화 (평문)
  4. 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/.

관련 스킬