scan

Documentation

Overview

Package scan finds WeChat database master keys by walking the WeChat process's RW memory regions, looking for the SQL literal pattern `x'<hex>'` that WCDB uses when it forwards keys to sqlite3_key_v2, and verifying each candidate against page 1 of every collected DB.

Algorithm (after Thearas, adapted for SQLCipher 4 + WCDB v4 KDF):

1. enumerate RW non-executable regions of the WeChat task
2. read each region in chunks; regex-match `x'[0-9a-fA-F]{64,192}'`
3. for each match, take first 64 hex as candidate key, last 32 hex (when present) as embedded salt
4. if embedded salt matches a DB salt, verify against that DB only; otherwise, try every DB whose salt is still unmatched
5. verification = SQLCipher 4 password-or-enc_key MAC check

Index

• Constants
• type Options
• type ProgressFn
• type Result
• type Stats
  • func Run(pid int32, dbs []dbfiles.DB, saltIdx map[string][]int, progress ProgressFn) (map[string]Result, Stats, error)
  • func RunWithOptions(pid int32, dbs []dbfiles.DB, saltIdx map[string][]int, opts Options, ...) (map[string]Result, Stats, error)

Constants

const MaxRegionSize = 500 * 1024 * 1024

MaxRegionSize skips any single region larger than this (typically shared caches or the dyld closure mapped at full virtual size).

Types

type Options

type Options struct {
	// IncludeBareHex enables a slower auxiliary pass that scans for bare
	// 64-hex strings (no x'...' wrapper) and tries each as the master
	// password. This recovers the master password when WCDB only ever held
	// it as a plain std::string, but each candidate costs one 256000-round
	// PBKDF2 to verify. Only enable when needed (e.g. Plan-C investigation).
	IncludeBareHex bool
}

Options tunes Run.

type ProgressFn

type ProgressFn func(s Stats)

ProgressFn is called periodically with cumulative stats so the CLI can print a status line. May be nil.

type Result

type Result struct {
	DBRel    string `json:"db_rel"`    // db path relative to scan root
	DBPath   string `json:"db_path"`   // absolute db path
	SaltHex  string `json:"salt_hex"`  // 32-hex db salt
	KeyHex   string `json:"key_hex"`   // 64-hex master key
	VerifyAs string `json:"verify_as"` // "password" or "enc_key"
}

Result describes one matched (db, key) pair.

type Stats

type Stats struct {
	Regions        int           `json:"regions"`
	BytesScanned   uint64        `json:"bytes_scanned"`
	HexMatches     int           `json:"hex_matches"`
	BareHexMatches int           `json:"bare_hex_matches,omitempty"`
	Verifications  int           `json:"verifications"` // PBKDF2 calls actually made
	Found          int           `json:"found"`
	Elapsed        time.Duration `json:"elapsed_ns"`
}

Stats summarizes a scan run.

func Run

func Run(pid int32, dbs []dbfiles.DB, saltIdx map[string][]int, progress ProgressFn) (map[string]Result, Stats, error)

Run scans pid's memory for keys decrypting any of dbs. It stops as soon as every distinct salt has at least one verified key (or the address space is exhausted).

func RunWithOptions

func RunWithOptions(pid int32, dbs []dbfiles.DB, saltIdx map[string][]int, opts Options, progress ProgressFn) (map[string]Result, Stats, error)

RunWithOptions is Run with explicit options.