crypto_key_scanner.py

#!/usr/bin/env python3
"""
╔══════════════════════════════════════════════════════════════════════════════╗
║          CRYPTO PRIVATE KEY SCANNER  —  Unified Forensic Edition           ║
║                                                                              ║
║  Scans HDD/USB/SD image files AND live block devices for crypto key         ║
║  material using three complementary passes:                                 ║
║                                                                              ║
║  1. STRINGS PASS  — extracts printable strings with hex offsets (fast,      ║
║                     practical, mirrors scan_crypto.sh approach)             ║
║  2. REGEX PASS    — applies text/encoded patterns to strings output         ║
║  3. BINARY PASS   — searches raw bytes for binary-encoded key structures    ║
║                     + sliding-window entropy catch-all                      ║
║                                                                              ║
║  Text/encoded schemas:                                                       ║
║    Bitcoin WIF (compressed/uncompressed), mini keys, BIP32 xprv/yprv/zprv  ║
║    Litecoin, Dogecoin, Dash WIF variants                                    ║
║    Ethereum/EVM raw hex keys, keystore v3 JSON                              ║
║    Monero spend/view keys, 25-word mnemonic seeds                           ║
║    Solana base58 keypairs, XRP secret keys, Cardano xprv                    ║
║    BIP39 mnemonics (12/18/24 words) with checksum validation                ║
║    PEM EC / PKCS#8 private keys, brain wallet hints                         ║
║                                                                              ║
║  Binary schemas:                                                             ║
║    Raw 32-byte secp256k1 key (0x80 WIF version prefix)                      ║
║    DER EC private key (RFC 5915, 30 ?? 02 01 01 04 20)                      ║
║    PKCS#8 secp256k1 (OID 1.3.132.0.10)                                     ║
║    BIP32 78-byte xprv/yprv/zprv/tprv binary blob                           ║
║    BIP32 child key (0x00 + 32-byte key, chain-code heuristic)               ║
║    Bitcoin wallet.dat Berkeley DB key records + BDB page magic              ║
║    Ed25519 private seed (DER/ASN.1, OID 1.3.101.112)                       ║
║    Solana id.json 64-byte uint8 JSON array                                  ║
║    Electrum old-style 16-byte seed (adjacent to seed_version tag)           ║
║    Armory wallet root key (preceded by 16× 0xB0 magic)                     ║
║    Entropy sliding-window catch-all (secp256k1-valid 32-byte windows)       ║
║                                                                              ║
║  Triage features (from scan_crypto.sh):                                     ║
║    HIGH / LOW / BIP39 confidence tiers                                      ║
║    Battle-tested noise exclusion regex (DRM, Spotlight, MPEG, etc.)        ║
║    Evidence manifest CSV (offset, schema, confidence, hex context)          ║
║    Free-space safety check before scan                                      ║
║    Auto device discovery on Linux/macOS (optional)                          ║
║    Carving hint output (offsets for use with foremost/scalpel)              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Usage:
  python3 crypto_key_scanner.py /path/to/disk.img
  python3 crypto_key_scanner.py /dev/sdb -o results/ --format json
  sudo python3 crypto_key_scanner.py --discover          # auto-find USB/SD (Linux)
  python3 crypto_key_scanner.py disk.img --fast          # strings+regex only, no binary
  python3 crypto_key_scanner.py disk.img --binary-only   # skip strings pass
  python3 crypto_key_scanner.py disk.img --skip-unvalidated --min-entropy 4.2

Requires: Python 3.9+
Optional: pip install colorama base58 mnemonic
"""

import re
import os
import sys
import math
import json
import time
import shutil
import hashlib
import struct
import argparse
import subprocess
import platform
from pathlib import Path
from dataclasses import dataclass, field
from typing import Optional, List, Tuple, Dict
from datetime import datetime

# ──────────────────────────────────────────────────────────────────────────────
# Optional dependencies
# ──────────────────────────────────────────────────────────────────────────────
try:
    import base58 as _base58lib
    HAS_BASE58 = True
except ImportError:
    HAS_BASE58 = False

try:
    from mnemonic import Mnemonic as _Mnemonic
    HAS_MNEMONIC = True
except ImportError:
    HAS_MNEMONIC = False

try:
    from colorama import Fore, Style, init as _colorama_init
    _colorama_init(autoreset=True)
    HAS_COLOR = True
except ImportError:
    HAS_COLOR = False
    class Fore:
        RED=GREEN=YELLOW=CYAN=MAGENTA=WHITE=BLUE=""
    class Style:
        BRIGHT=RESET_ALL=DIM=""

# ──────────────────────────────────────────────────────────────────────────────
# Constants
# ──────────────────────────────────────────────────────────────────────────────
VERSION       = "1.0.0"
CHUNK_SIZE    = 4 * 1024 * 1024   # 4 MB read chunks
OVERLAP       = 512               # overlap to catch keys spanning chunk boundaries
SECTOR_SIZE   = 512
MIN_STR_LEN   = 6                 # minimum printable string length for strings pass
MIN_FREE_GB   = 2                 # default free-space reserve for output dir

# secp256k1 curve order
SECP256K1_ORDER = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141

# Confidence tiers
TIER_HIGH   = "HIGH"
TIER_LOW    = "LOW"
TIER_BIP39  = "BIP39"
TIER_BINARY = "BINARY"
TIER_ENTROPY= "ENTROPY"

# ══════════════════════════════════════════════════════════════════════════════
# NOISE EXCLUSION  (ported from scan_crypto.sh RE_EXCLUDE — battle-tested)
# ══════════════════════════════════════════════════════════════════════════════
# These patterns appear in DRM blobs, Spotlight indexes, MPEG/JPEG metadata,
# Amazon download records, and other high-volume false-positive sources.
_NOISE_FRAGMENTS = [
    r'uits', r'amazon', r'amzn', r'drm', r'widevine', r'playready', r'fairplay',
    r'rsa2048', r'manifest', r'x-amz', r'etag', r'content-md5', r'audible',
    r'locker', r'transactiontype', r'distributor',
    r'download[ _-]*(paid|locker|queue)',
    r'spotlight', r'dbstr', r'dictionary',
    r'kmditem', r'mditem', r'mdworker', r'mds_stores', r'store-v2',
    r'/9j/4aaqskzjrg', r'x:xmpmeta', r'adobe xmp core', r'adobe photoshop',
    r'dc:format="image/jpeg"', r'xmp\.iid:', r'xmp\.did:', r'xapmm:documentid',
    r'originaldocumentid', r'uuid:[0-9a-f]{24,}',
    r'pubmed', r'fda\.gov', r'acr\.org',
    r'lame3\.[0-9]+', r'\blame\b', r'id3v2', r'xing', r'vbri',
    r'mpeg layer-3', r'\bfm0\b', r'\bfm1\b',
    r'fc[01]{6,}:?z+',
    r'/imageservice/ahr0',
    r'<< /size [0-9]+ /root [0-9]+ 0 r',
    r'u{20,}', r'k{30,}', r'%5u{20,}',
    r'[A-Za-z0-9+/]{100,}={0,2}',   # long base64 blobs (DRM/certs)
]
RE_NOISE = re.compile('|'.join(_NOISE_FRAGMENTS), re.IGNORECASE)

_NOISE_PATH_FRAGMENTS = [
    r'/\.Spotlight-V100/',
    r'/Library/Caches/',
    r'/Cache/',
    r'/logs?/',
    r'/log/',
    r'download[ _-]*queue',
    r'audible',
]
RE_NOISE_PATH = re.compile('|'.join(_NOISE_PATH_FRAGMENTS), re.IGNORECASE)

def _is_noisy_line(line: str) -> bool:
    return bool(RE_NOISE.search(line))

# ══════════════════════════════════════════════════════════════════════════════
# TEXT / REGEX PATTERNS
# ══════════════════════════════════════════════════════════════════════════════

# ── Bitcoin / altcoin WIF ─────────────────────────────────────────────────────
RE_BTC_WIF_UNCOMP = re.compile(rb'(?<![A-Za-z0-9])(5[HJK][1-9A-HJ-NP-Za-km-z]{49})(?![A-Za-z0-9])')
RE_BTC_WIF_COMP   = re.compile(rb'(?<![A-Za-z0-9])([KL][1-9A-HJ-NP-Za-km-z]{51})(?![A-Za-z0-9])')
RE_LTC_WIF        = re.compile(rb'(?<![A-Za-z0-9])(T[1-9A-HJ-NP-Za-km-z]{51}|6[PQ][1-9A-HJ-NP-Za-km-z]{49})(?![A-Za-z0-9])')
RE_DOGE_WIF       = re.compile(rb'(?<![A-Za-z0-9])(Q[HJK][1-9A-HJ-NP-Za-km-z]{49})(?![A-Za-z0-9])')
RE_DASH_WIF       = re.compile(rb'(?<![A-Za-z0-9])(X[1-9A-HJ-NP-Za-km-z]{51})(?![A-Za-z0-9])')

# ── Ethereum / EVM ───────────────────────────────────────────────────────────
RE_ETH_HEX        = re.compile(rb'(?<![0-9a-fA-F])(0x)?([0-9a-fA-F]{64})(?![0-9a-fA-F])')
RE_ETH_KEYSTORE   = re.compile(rb'\{[^}]{0,512}"version"\s*:\s*3[^}]{0,512}"crypto"', re.DOTALL | re.IGNORECASE)

# ── BIP32 extended keys ───────────────────────────────────────────────────────
RE_XPRV           = re.compile(rb'(?<![A-Za-z0-9])([xyz]prv[1-9A-HJ-NP-Za-km-z]{107,108})(?![A-Za-z0-9])')
RE_TPRV           = re.compile(rb'(?<![A-Za-z0-9])(tprv[1-9A-HJ-NP-Za-km-z]{107,108})(?![A-Za-z0-9])')

# ── Bitcoin mini key ──────────────────────────────────────────────────────────
RE_MINI_KEY       = re.compile(rb'(?<![A-Za-z0-9])(S[1-9A-HJ-NP-Za-km-z]{29})(?![A-Za-z0-9])')

# ── Monero ────────────────────────────────────────────────────────────────────
RE_MONERO_KEY     = re.compile(rb'(?i)(?:spend[_ ]?key|view[_ ]?key|secret[_ ]?key)["\s:=]+([0-9a-fA-F]{64})')
RE_MONERO_SEED    = re.compile(rb'(?i)(?:mnemonic|seed phrase|wallet words)[^\n]{0,30}\n?([a-z]+(?: [a-z]+){24})')

# ── Solana / XRP / Cardano ────────────────────────────────────────────────────
RE_SOLANA_KEY     = re.compile(rb'(?<![1-9A-HJ-NP-Za-km-z])([1-9A-HJ-NP-Za-km-z]{87,88})(?![1-9A-HJ-NP-Za-km-z])')
RE_XRP_SECRET     = re.compile(rb'(?<![A-Za-z0-9])(s[1-9A-HJ-NP-Za-km-z]{28})(?![A-Za-z0-9])')
RE_CARDANO_XPRV   = re.compile(rb'(?<![A-Za-z0-9])(xprv[0-9a-z]{96,106})(?![A-Za-z0-9])')

# ── BIP39 mnemonics ───────────────────────────────────────────────────────────
RE_BIP39_12       = re.compile(rb'(?<![a-z])([a-z]{3,8}(?: [a-z]{3,8}){11})(?![a-z])')
RE_BIP39_18       = re.compile(rb'(?<![a-z])([a-z]{3,8}(?: [a-z]{3,8}){17})(?![a-z])')
RE_BIP39_24       = re.compile(rb'(?<![a-z])([a-z]{3,8}(?: [a-z]{3,8}){23})(?![a-z])')

# ── PEM keys ──────────────────────────────────────────────────────────────────
RE_PEM_EC         = re.compile(rb'-----BEGIN EC PRIVATE KEY-----.+?-----END EC PRIVATE KEY-----', re.DOTALL)
RE_PEM_PKCS8      = re.compile(rb'-----BEGIN PRIVATE KEY-----.+?-----END PRIVATE KEY-----', re.DOTALL)

# ── Brain wallet ─────────────────────────────────────────────────────────────
RE_BRAINWALLET    = re.compile(rb'(?i)brainwallet[\s:=]+([^\n\r]{8,128})')

# ── HIGH-confidence address/key indicators (from scan_crypto.sh PAT_HIGH) ────
RE_HIGH_SIGNALS = re.compile(
    rb'(bc1[a-zA-HJ-NP-Z0-9]{25,90}'
    rb'|[13][a-km-zA-HJ-NP-Z1-9]{25,34}'
    rb'|0x[0-9a-fA-F]{40}'
    rb'|4[1-9A-HJ-NP-Za-km-z]{94}'
    rb'|5[1-9A-HJ-NP-Za-km-z]{50}'
    rb'|[KL][1-9A-HJ-NP-Za-km-z]{51}'
    rb'|[xyz]prv[1-9A-HJ-NP-Za-km-z]{100,115}'
    rb'|[xyz]pub[1-9A-HJ-NP-Za-km-z]{100,115}'
    rb'|"ciphertext"\s*:\s*"[0-9a-fA-F]{64,}"'
    rb'|"crypto"\s*:'
    rb'|"kdf"\s*:)'
)

# ── LOW-confidence wallet/key context indicators ──────────────────────────────
RE_LOW_SIGNALS = re.compile(
    rb'(?i)(wallet\.dat'
    rb'|keystore'
    rb'|mnemonic'
    rb'|seed[ _.-]?phrase'
    rb'|recovery[ _.-]?phrase'
    rb'|private[ _.-]?key'
    rb'|secret[ _.-]?key'
    rb'|UTC--[0-9]'
    rb'|bitcoin|ethereum|solana|monero|litecoin|dogecoin'
    rb'|metamask|ledger|trezor|electrum|exodus|phantom|coinbase'
    rb'|trust[ _.-]?wallet)'
)

# ══════════════════════════════════════════════════════════════════════════════
# BINARY PATTERN SIGNATURES
# ══════════════════════════════════════════════════════════════════════════════
RE_DER_EC_BIN = re.compile(
    b'\x30[\x50-\x8f]\x02\x01\x01\x04\x20'
)
BIP32_VERSIONS = [
    b'\x04\x88\xAD\xE4',  # mainnet xprv
    b'\x04\x35\x83\x94',  # testnet tprv
    b'\x04\x9D\x78\x78',  # yprv (P2SH-P2WPKH)
    b'\x04\xB2\x43\x0C',  # zprv (P2WPKH)
]
WALLETDAT_KEY_MARKER = b'\x01\x01\x01\x04\x20'
BDB_MAGIC            = b'\x00\x05\x31\x62'
ED25519_OID          = b'\x06\x03\x2b\x65\x70'
SECP256K1_OID        = b'\x06\x05\x2b\x81\x04\x00\x0a'
ELECTRUM_SEED_TAG    = b'seed_version'
ARMORY_ROOT_MAGIC    = b'\xb0' * 16
RE_SOLANA_JSON_ARRAY = re.compile(
    rb'\[(?:\s*\d{1,3}\s*,){63}\s*\d{1,3}\s*\]'
)

# ══════════════════════════════════════════════════════════════════════════════
# RESULT DATACLASS
# ══════════════════════════════════════════════════════════════════════════════
@dataclass
class KeyFinding:
    schema:     str
    tier:       str          # HIGH / LOW / BIP39 / BINARY / ENTROPY
    raw:        str          # hex string for binary, encoded string for text
    offset:     int
    context:    str  = ""
    validated:  Optional[bool] = None
    notes:      str  = ""

    def to_dict(self) -> dict:
        return {
            "schema":    self.schema,
            "tier":      self.tier,
            "raw":       self.raw,
            "offset":    hex(self.offset),
            "context":   self.context,
            "validated": self.validated,
            "notes":     self.notes,
        }

# ══════════════════════════════════════════════════════════════════════════════
# BIP39 WORDLIST  (lazy-loaded)
# ══════════════════════════════════════════════════════════════════════════════
_BIP39_WORDS: Optional[set] = None
_BIP39_MNEMO = None

def _load_bip39():
    global _BIP39_WORDS, _BIP39_MNEMO
    if _BIP39_WORDS is not None:
        return
    if HAS_MNEMONIC:
        try:
            _BIP39_MNEMO = _Mnemonic("english")
            _BIP39_WORDS = set(_BIP39_MNEMO.wordlist)
            return
        except Exception:
            pass
    for p in [Path(__file__).parent / "english.txt",
              Path("/usr/share/bip39/english.txt")]:
        if p.exists():
            _BIP39_WORDS = set(p.read_text().splitlines())
            return
    _BIP39_WORDS = set()

# ══════════════════════════════════════════════════════════════════════════════
# TEXT VALIDATION HELPERS
# ══════════════════════════════════════════════════════════════════════════════

def _b58_check(data: bytes) -> Optional[bool]:
    if not HAS_BASE58:
        return None
    try:
        return _base58lib.b58decode_check(data) is not None
    except Exception:
        return False

def _validate_wif(raw: bytes) -> Optional[bool]:
    return _b58_check(raw)

def _validate_eth_hex(raw: bytes) -> Optional[bool]:
    try:
        n = int(raw, 16)
        return 0 < n < SECP256K1_ORDER
    except Exception:
        return None

def _validate_mini_key(raw: bytes) -> Optional[bool]:
    try:
        return hashlib.sha256(raw + b'?').digest()[0] == 0x00
    except Exception:
        return None

def _validate_bip39_bytes(raw: bytes) -> Optional[bool]:
    _load_bip39()
    if not _BIP39_WORDS:
        return None
    phrase = raw.decode(errors='ignore').lower()
    words  = phrase.split()
    if len(words) not in (12, 18, 24):
        return False
    if not all(w in _BIP39_WORDS for w in words):
        return False
    if _BIP39_MNEMO:
        try:
            return _BIP39_MNEMO.check(phrase)
        except Exception:
            pass
    return True   # words valid, checksum unknown

def _validate_xprv(raw: bytes) -> Optional[bool]:
    return _b58_check(raw)

# ══════════════════════════════════════════════════════════════════════════════
# BINARY VALIDATION HELPERS
# ══════════════════════════════════════════════════════════════════════════════

def _valid_secp256k1(b: bytes) -> bool:
    if len(b) != 32:
        return False
    n = int.from_bytes(b, 'big')
    return 0 < n < SECP256K1_ORDER

def _valid_ed25519(b: bytes) -> bool:
    if len(b) != 32:
        return False
    n = int.from_bytes(b, 'little')
    return 0 < n < (2**256 - 1)

def _byte_entropy(data: bytes) -> float:
    if not data:
        return 0.0
    freq = [0]*256
    for b in data:
        freq[b] += 1
    n = len(data)
    return -sum((c/n)*math.log2(c/n) for c in freq if c)

def _key_like(data: bytes, min_ent: float = 3.5) -> bool:
    if len(data) < 16:
        return False
    if len(set(data)) < 8:
        return False
    if all(0x20 <= b < 0x7F for b in data):
        return False
    return _byte_entropy(data) >= min_ent

def _valid_bip32_blob(blob: bytes) -> bool:
    return (len(blob) >= 78 and blob[45] == 0x00
            and _valid_secp256k1(blob[46:78]))

def _hex_ctx(chunk: bytes, off: int, w: int = 20) -> str:
    s   = max(0, off - w)
    e   = min(len(chunk), off + 32 + w)
    raw = chunk[s:e]
    asc = ''.join(chr(b) if 0x20 <= b < 0x7F else '.' for b in raw)
    return f"{raw.hex()} | {asc}"

# ══════════════════════════════════════════════════════════════════════════════
# TEXT PATTERN REGISTRY
# ══════════════════════════════════════════════════════════════════════════════
#  (schema_name, tier, regex, capture_group, validator_fn)
TEXT_PATTERNS: List[Tuple] = [
    ("Bitcoin WIF (uncompressed)",  TIER_HIGH,   RE_BTC_WIF_UNCOMP, 1, _validate_wif),
    ("Bitcoin WIF (compressed)",    TIER_HIGH,   RE_BTC_WIF_COMP,   1, _validate_wif),
    ("Litecoin WIF",                TIER_HIGH,   RE_LTC_WIF,        1, _validate_wif),
    ("Dogecoin WIF",                TIER_HIGH,   RE_DOGE_WIF,       1, _validate_wif),
    ("Dash WIF",                    TIER_HIGH,   RE_DASH_WIF,       1, _validate_wif),
    ("Ethereum/EVM hex key",        TIER_HIGH,   RE_ETH_HEX,        2, _validate_eth_hex),
    ("Ethereum keystore v3",        TIER_HIGH,   RE_ETH_KEYSTORE,   0, None),
    ("BIP32 xprv/yprv/zprv",        TIER_HIGH,   RE_XPRV,           1, _validate_xprv),
    ("BIP32 testnet tprv",          TIER_HIGH,   RE_TPRV,           1, _validate_xprv),
    ("Bitcoin mini key",            TIER_HIGH,   RE_MINI_KEY,       1, _validate_mini_key),
    ("Monero spend/view key",       TIER_HIGH,   RE_MONERO_KEY,     1, None),
    ("Monero mnemonic seed",        TIER_BIP39,  RE_MONERO_SEED,    1, None),
    ("Solana keypair (base58)",     TIER_HIGH,   RE_SOLANA_KEY,     1, None),
    ("XRP secret key",              TIER_HIGH,   RE_XRP_SECRET,     1, None),
    ("BIP39 mnemonic (12 words)",   TIER_BIP39,  RE_BIP39_12,       1, _validate_bip39_bytes),
    ("BIP39 mnemonic (18 words)",   TIER_BIP39,  RE_BIP39_18,       1, _validate_bip39_bytes),
    ("BIP39 mnemonic (24 words)",   TIER_BIP39,  RE_BIP39_24,       1, _validate_bip39_bytes),
    ("PEM EC private key",          TIER_HIGH,   RE_PEM_EC,         0, None),
    ("PEM PKCS#8 private key",      TIER_HIGH,   RE_PEM_PKCS8,      0, None),
    ("Cardano xprv key",            TIER_HIGH,   RE_CARDANO_XPRV,   1, None),
    ("Brain wallet hint",           TIER_LOW,    RE_BRAINWALLET,    1, None),
]

# ══════════════════════════════════════════════════════════════════════════════
# BINARY KEY SCANNER
# ══════════════════════════════════════════════════════════════════════════════
class BinaryKeyScanner:
    def __init__(self, entropy_threshold: float = 3.8, entropy_stride: int = 4,
                 do_entropy: bool = True):
        self.entropy_threshold = entropy_threshold
        self.entropy_stride    = entropy_stride
        self.do_entropy        = do_entropy

    # ── individual detectors ──────────────────────────────────────────────────

    def _der_ec(self, chunk: bytes) -> List[Tuple]:
        out = []
        for m in RE_DER_EC_BIN.finditer(chunk):
            s    = m.start()
            blob = chunk[s:s+150]
            key  = blob[7:39] if len(blob) >= 39 else b''
            out.append(("Binary DER EC key (RFC 5915)",
                        TIER_BINARY, key.hex() if key else blob[:7].hex(),
                        s, _valid_secp256k1(key) if len(key)==32 else None,
                        f"hdr={blob[:7].hex()}"))
        return out

    def _bip32_blob(self, chunk: bytes) -> List[Tuple]:
        out = []
        for ver in BIP32_VERSIONS:
            pos = 0
            while True:
                idx = chunk.find(ver, pos)
                if idx == -1: break
                blob = chunk[idx:idx+78]
                if len(blob)==78 and _valid_bip32_blob(blob):
                    key = blob[46:78]; cc = blob[13:45]
                    out.append((f"Binary BIP32 xprv blob ({ver.hex()[:8]})",
                                TIER_BINARY, key.hex(), idx, True,
                                f"depth={blob[4]} child={int.from_bytes(blob[9:13],'big')} cc={cc[:8].hex()}…"))
                pos = idx+1
        return out

    def _raw_wif(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(b'\x80', pos)
            if idx == -1: break
            key = chunk[idx+1:idx+33]
            if (len(key)==32 and _valid_secp256k1(key)
                    and _key_like(key, 4.0)):
                comp = chunk[idx+33:idx+34] == b'\x01'
                out.append(("Binary raw WIF (0x80 prefix)",
                            TIER_BINARY, key.hex(), idx, True,
                            f"compressed={comp}"))
            pos = idx+1
        return out

    def _bip32_child(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(b'\x00', pos)
            if idx == -1: break
            if idx >= 32:
                key = chunk[idx+1:idx+33]
                cc  = chunk[idx-32:idx]
                if (len(key)==32 and _valid_secp256k1(key)
                        and _key_like(key, 4.5) and _key_like(cc, 4.0)):
                    out.append(("Binary BIP32 child key (0x00 prefix + chaincode)",
                                TIER_BINARY, key.hex(), idx, True,
                                f"cc={cc[:8].hex()}…"))
            pos = idx+1
        return out

    def _wallet_dat(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(WALLETDAT_KEY_MARKER, pos)
            if idx == -1: break
            ks = idx+len(WALLETDAT_KEY_MARKER)
            key = chunk[ks:ks+32]
            if len(key)==32 and _valid_secp256k1(key):
                out.append(("Binary wallet.dat key record",
                            TIER_BINARY, key.hex(), idx, True,
                            "marker: 01 01 01 04 20"))
            pos = idx+1
        bdb = chunk.find(BDB_MAGIC)
        if bdb != -1:
            out.append(("Berkeley DB page (wallet.dat structure)",
                        TIER_LOW, chunk[bdb:bdb+16].hex(), bdb, None,
                        "BDB magic 00 05 31 62 — use db_dump/pywallet"))
        return out

    def _solana_array(self, chunk: bytes) -> List[Tuple]:
        out = []
        for m in RE_SOLANA_JSON_ARRAY.finditer(chunk):
            try:
                nums = [int(x) for x in re.findall(rb'\d+', m.group(0))]
                if len(nums)==64 and all(0<=n<=255 for n in nums):
                    seed=bytes(nums[:32]); pub=bytes(nums[32:])
                    out.append(("Binary Solana id.json keypair",
                                TIER_BINARY, seed.hex(), m.start(),
                                _valid_ed25519(seed),
                                f"pub={pub.hex()[:16]}…"))
            except Exception:
                pass
        return out

    def _ed25519_der(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(ED25519_OID, pos)
            if idx == -1: break
            area = chunk[idx:idx+80]
            m = re.search(b'\x04\x22\x04\x20(.{32})|\x04\x20(.{32})',
                          area, re.DOTALL)
            if m:
                seed = m.group(1) or m.group(2)
                out.append(("Binary Ed25519 seed (DER OID 1.3.101.112)",
                            TIER_BINARY, seed.hex(), idx,
                            _valid_ed25519(seed), f"oid@{hex(idx)}"))
            pos = idx+1
        return out

    def _pkcs8_secp256k1(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(SECP256K1_OID, pos)
            if idx == -1: break
            area = chunk[idx:idx+120]
            m = re.search(b'\x04\x20(.{32})', area, re.DOTALL)
            if m:
                key = m.group(1)
                out.append(("Binary PKCS#8 secp256k1 key",
                            TIER_BINARY, key.hex(), idx,
                            _valid_secp256k1(key),
                            f"secp256k1 OID @{hex(idx)}"))
            pos = idx+1
        return out

    def _electrum_seed(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(ELECTRUM_SEED_TAG, pos)
            if idx == -1: break
            area = chunk[idx+len(ELECTRUM_SEED_TAG):
                         idx+len(ELECTRUM_SEED_TAG)+80]
            for i in range(len(area)-16):
                c = area[i:i+16]
                if _key_like(c, 3.5):
                    out.append(("Binary Electrum 16-byte seed",
                                TIER_BINARY, c.hex(),
                                idx+len(ELECTRUM_SEED_TAG)+i,
                                None, "adj. to 'seed_version' tag"))
                    break
            pos = idx+1
        return out

    def _armory(self, chunk: bytes) -> List[Tuple]:
        out = []; pos = 0
        while True:
            idx = chunk.find(ARMORY_ROOT_MAGIC, pos)
            if idx == -1: break
            ks = idx+len(ARMORY_ROOT_MAGIC)
            key = chunk[ks:ks+32]
            if len(key)==32 and _key_like(key):
                out.append(("Binary Armory wallet root key",
                            TIER_BINARY, key.hex(), idx,
                            _valid_secp256k1(key),
                            "preceded by 16× 0xB0 magic"))
            pos = idx+1
        return out

    def _entropy_windows(self, chunk: bytes) -> List[Tuple]:
        out = []
        for i in range(0, len(chunk)-32, self.entropy_stride):
            w = chunk[i:i+32]
            if _key_like(w, self.entropy_threshold) and _valid_secp256k1(w):
                out.append(("Binary entropy candidate (secp256k1-valid window)",
                            TIER_ENTROPY, w.hex(), i, True,
                            f"H={_byte_entropy(w):.2f} bpb"))
        return out

    # ── main entry ────────────────────────────────────────────────────────────
    def scan_chunk(self, chunk: bytes, chunk_offset: int) -> List[KeyFinding]:
        findings: List[KeyFinding] = []
        seen: set = set()

        def _add(schema, tier, raw_hex, local_off, validated, notes):
            abs_off = chunk_offset + local_off
            if abs_off in seen: return
            seen.add(abs_off)
            findings.append(KeyFinding(
                schema=schema, tier=tier, raw=raw_hex, offset=abs_off,
                context=_hex_ctx(chunk, local_off),
                validated=validated, notes=notes))

        for t in self._der_ec(chunk):         _add(*t)
        for t in self._bip32_blob(chunk):     _add(*t)
        for t in self._raw_wif(chunk):        _add(*t)
        for t in self._wallet_dat(chunk):     _add(*t)
        for t in self._solana_array(chunk):   _add(*t)
        for t in self._ed25519_der(chunk):    _add(*t)
        for t in self._pkcs8_secp256k1(chunk):_add(*t)
        for t in self._electrum_seed(chunk):  _add(*t)
        for t in self._armory(chunk):         _add(*t)
        for t in self._bip32_child(chunk):    _add(*t)
        if self.do_entropy:
            for t in self._entropy_windows(chunk): _add(*t)
        return findings

# ══════════════════════════════════════════════════════════════════════════════
# STRINGS EXTRACTION  (mirrors scan_crypto.sh raw strings pass)
# ══════════════════════════════════════════════════════════════════════════════
def _extract_strings_subprocess(data: bytes, min_len: int = MIN_STR_LEN) -> List[Tuple[int,str]]:
    """
    Use the system `strings` binary for fast extraction if available,
    otherwise fall back to pure-Python extraction.
    Returns list of (offset_in_data, string).
    """
    if shutil.which("strings"):
        try:
            proc = subprocess.run(
                ["strings", "-a", f"-{min_len}", "-t", "x"],
                input=data, capture_output=True, timeout=120
            )
            results = []
            for line in proc.stdout.decode(errors='replace').splitlines():
                line = line.strip()
                if not line: continue
                parts = line.split(None, 1)
                if len(parts) == 2:
                    try:
                        off = int(parts[0], 16)
                        results.append((off, parts[1]))
                    except ValueError:
                        pass
            return results
        except Exception:
            pass
    # Pure-Python fallback
    return _extract_strings_pure(data, min_len)

def _extract_strings_pure(data: bytes, min_len: int = MIN_STR_LEN) -> List[Tuple[int,str]]:
    results = []
    current = []
    start   = 0
    for i, b in enumerate(data):
        if 0x20 <= b < 0x7F:
            if not current:
                start = i
            current.append(chr(b))
        else:
            if len(current) >= min_len:
                results.append((start, ''.join(current)))
            current = []
    if len(current) >= min_len:
        results.append((start, ''.join(current)))
    return results

# ══════════════════════════════════════════════════════════════════════════════
# FREE-SPACE CHECK
# ══════════════════════════════════════════════════════════════════════════════
def _free_gb(path: Path) -> float:
    try:
        st = shutil.disk_usage(path)
        return st.free / (1024**3)
    except Exception:
        return 999.0

def _check_free_space(path: Path, min_gb: float):
    free = _free_gb(path)
    if free < min_gb:
        _die(f"Insufficient free space: {free:.1f} GB available, "
             f"{min_gb} GB required. Use --min-free-gb to lower reserve.")

def _die(msg: str):
    print(f"{Fore.RED}FATAL: {msg}{Style.RESET_ALL}", file=sys.stderr)
    sys.exit(1)

# ══════════════════════════════════════════════════════════════════════════════
# DEVICE DISCOVERY  (Linux/macOS)
# ══════════════════════════════════════════════════════════════════════════════
def discover_removable_devices() -> List[str]:
    """Return list of removable block device paths (Linux + macOS)."""
    devices = []
    if platform.system() == "Darwin":
        try:
            out = subprocess.check_output(
                ["diskutil", "list", "-plist"], stderr=subprocess.DEVNULL
            )
            # simple grep for external disk identifiers
            lines = subprocess.check_output(
                ["diskutil", "list"], stderr=subprocess.DEVNULL
            ).decode(errors='replace').splitlines()
            for line in lines:
                if "external" in line.lower() or "removable" in line.lower():
                    parts = line.split()
                    if parts:
                        devices.append(f"/dev/{parts[0].strip('*')}")
        except Exception:
            pass
    else:  # Linux
        try:
            lsblk = subprocess.check_output(
                ["lsblk", "-J", "-o", "NAME,HOTPLUG,TYPE,RM"],
                stderr=subprocess.DEVNULL
            ).decode(errors='replace')
            data = json.loads(lsblk)
            for dev in data.get("blockdevices", []):
                if (dev.get("hotplug") or dev.get("rm")) \
                        and dev.get("type") in ("disk", "part"):
                    devices.append(f"/dev/{dev['name']}")
        except Exception:
            # fallback: look for removable flag in sysfs
            for p in Path("/sys/block").iterdir():
                try:
                    if (p / "removable").read_text().strip() == "1":
                        devices.append(f"/dev/{p.name}")
                except Exception:
                    pass
    return sorted(set(devices))

# ══════════════════════════════════════════════════════════════════════════════
# MAIN SCANNER
# ══════════════════════════════════════════════════════════════════════════════
class CryptoKeyScanner:
    def __init__(
        self,
        image_path:        str,
        output_dir:        Optional[str]  = None,
        output_format:     str            = "text",
        validate:          bool           = True,
        skip_unvalidated:  bool           = False,
        sector_start:      int            = 0,
        sector_end:        Optional[int]  = None,
        schema_filter:     Optional[List] = None,
        # pass toggles
        do_strings_pass:   bool           = True,
        do_regex_pass:     bool           = True,
        do_binary_pass:    bool           = True,
        do_entropy:        bool           = True,
        # tuning
        min_str_len:       int            = MIN_STR_LEN,
        entropy_threshold: float          = 3.8,
        entropy_stride:    int            = 4,
        min_free_gb:       float          = MIN_FREE_GB,
        verbose:           bool           = False,
    ):
        self.image_path        = image_path
        self.output_dir        = Path(output_dir) if output_dir else None
        self.output_format     = output_format
        self.validate          = validate
        self.skip_unvalidated  = skip_unvalidated
        self.sector_start      = sector_start
        self.sector_end        = sector_end
        self.schema_filter     = schema_filter
        self.do_strings_pass   = do_strings_pass
        self.do_regex_pass     = do_regex_pass
        self.do_binary_pass    = do_binary_pass
        self.do_entropy        = do_entropy
        self.min_str_len       = min_str_len
        self.entropy_threshold = entropy_threshold
        self.entropy_stride    = entropy_stride
        self.min_free_gb       = min_free_gb
        self.verbose           = verbose

        self.findings:  List[KeyFinding] = []
        self.tier_stats: Dict[str, int]  = {
            TIER_HIGH: 0, TIER_LOW: 0, TIER_BIP39: 0,
            TIER_BINARY: 0, TIER_ENTROPY: 0
        }
        self.schema_stats: Dict[str, int] = {}
        self.bytes_scanned = 0
        self.start_time:   Optional[datetime] = None
        self.run_id        = datetime.now().strftime("%Y%m%d_%H%M%S")

        self._bin_scanner = BinaryKeyScanner(
            entropy_threshold = entropy_threshold,
            entropy_stride    = entropy_stride,
            do_entropy        = do_entropy,
        ) if do_binary_pass else None

        if self.output_dir:
            self.output_dir.mkdir(parents=True, exist_ok=True)
            _check_free_space(self.output_dir, self.min_free_gb)

    # ── helpers ───────────────────────────────────────────────────────────────

    def _active_text_patterns(self):
        if not self.schema_filter:
            return TEXT_PATTERNS
        sf = [s.lower() for s in self.schema_filter]
        return [p for p in TEXT_PATTERNS
                if any(f in p[0].lower() for f in sf)]

    def _record(self, f: KeyFinding, seen: set) -> bool:
        """Add to findings if not duplicate and passes filters."""
        if f.offset in seen:
            return False
        if self.skip_unvalidated and f.validated is False:
            return False
        seen.add(f.offset)
        self.findings.append(f)
        self.tier_stats[f.tier] = self.tier_stats.get(f.tier, 0) + 1
        self.schema_stats[f.schema] = self.schema_stats.get(f.schema, 0) + 1
        return True

    # ── strings pass ─────────────────────────────────────────────────────────
    def _strings_pass(self, chunk: bytes, chunk_offset: int,
                      seen: set) -> List[KeyFinding]:
        """
        Extract printable strings, apply HIGH/LOW signal regexes.
        This mirrors the scan_crypto.sh raw strings pass — fast triage.
        """
        findings = []
        strings  = _extract_strings_subprocess(chunk, self.min_str_len)

        for str_off, s in strings:
            sb = s.encode()
            abs_off = chunk_offset + str_off

            # Noise filter (DRM, Spotlight, MPEG, etc.)
            if _is_noisy_line(s):
                continue

            # Check HIGH signals
            if RE_HIGH_SIGNALS.search(sb):
                ctx = s[:120]
                f   = KeyFinding(schema="High-signal indicator (strings pass)",
                                 tier=TIER_HIGH, raw=s[:256],
                                 offset=abs_off, context=ctx,
                                 validated=None,
                                 notes="strings pass HIGH signal")
                if self._record(f, seen):
                    findings.append(f)

            # Check LOW signals (wallet context keywords)
            elif RE_LOW_SIGNALS.search(sb):
                f = KeyFinding(schema="Wallet/key context (strings pass)",
                               tier=TIER_LOW, raw=s[:256],
                               offset=abs_off, context=s[:80],
                               validated=None,
                               notes="strings pass LOW signal")
                if self._record(f, seen):
                    findings.append(f)

        return findings

    # ── regex pass ────────────────────────────────────────────────────────────
    def _regex_pass(self, chunk: bytes, chunk_offset: int,
                    seen: set, patterns) -> List[KeyFinding]:
        findings = []
        for schema, tier, regex, group, validator in patterns:
            for m in regex.finditer(chunk):
                raw_bytes = m.group(group) if group else m.group(0)
                raw_str   = raw_bytes.decode(errors='replace').strip()
                offset    = chunk_offset + m.start()

                # Noise filter
                if _is_noisy_line(raw_str):
                    continue

                ctx = chunk[max(0,m.start()-32):m.end()+32]
                ctx_str = ''.join(chr(b) if 32<=b<127 else '.' for b in ctx)

                validated = None
                if self.validate and validator:
                    try:
                        validated = validator(raw_bytes)
                    except Exception:
                        pass

                f = KeyFinding(schema=schema, tier=tier, raw=raw_str,
                               offset=offset, context=ctx_str,
                               validated=validated, notes="")
                if self._record(f, seen):
                    findings.append(f)
        return findings

    # ── binary pass ───────────────────────────────────────────────────────────
    def _binary_pass(self, chunk: bytes, chunk_offset: int,
                     seen: set) -> List[KeyFinding]:
        if not self._bin_scanner:
            return []
        findings = []
        for f in self._bin_scanner.scan_chunk(chunk, chunk_offset):
            if self._record(f, seen):
                findings.append(f)
        return findings

    # ── main scan loop ────────────────────────────────────────────────────────
    def scan(self) -> List[KeyFinding]:
        image = Path(self.image_path)
        if not image.exists():
            raise FileNotFoundError(f"Not found: {self.image_path}")

        file_size  = image.stat().st_size
        byte_start = self.sector_start * SECTOR_SIZE
        byte_end   = (self.sector_end * SECTOR_SIZE) if self.sector_end else file_size
        byte_end   = min(byte_end, file_size)
        total_scan = byte_end - byte_start

        patterns = self._active_text_patterns()
        seen: set = set()

        self.start_time = datetime.now()
        _print_header(self.image_path, file_size, total_scan, byte_start,
                      self.do_strings_pass, self.do_regex_pass,
                      self.do_binary_pass, self.do_entropy)

        with open(image, 'rb') as fh:
            offset = byte_start
            fh.seek(offset)
            while offset < byte_end:
                read_size = min(CHUNK_SIZE + OVERLAP, byte_end - offset)
                chunk = fh.read(read_size)
                if not chunk:
                    break

                new_findings: List[KeyFinding] = []

                if self.do_strings_pass:
                    new_findings += self._strings_pass(chunk, offset, seen)

                if self.do_regex_pass:
                    new_findings += self._regex_pass(chunk, offset, seen, patterns)

                if self.do_binary_pass:
                    new_findings += self._binary_pass(chunk, offset, seen)

                for f in new_findings:
                    _print_finding(f)

                self.bytes_scanned += len(chunk)
                pct = min(100.0, (offset - byte_start + len(chunk)) / total_scan * 100)
                _print_progress(pct, offset, len(self.findings))

                offset += len(chunk) - OVERLAP if len(chunk) > OVERLAP else len(chunk)
                fh.seek(offset)

        elapsed = (datetime.now() - self.start_time).total_seconds()
        _print_footer(self.findings, self.tier_stats, self.schema_stats,
                      elapsed, self.bytes_scanned)

        if self.output_dir:
            self._write_outputs()

        return self.findings

    # ── output ────────────────────────────────────────────────────────────────
    def _write_outputs(self):
        base = self.output_dir / f"run_{self.run_id}"
        base.mkdir(parents=True, exist_ok=True)

        # Summary text
        summary = base / "summary.txt"
        lines = [
            f"# Crypto Key Scanner — Summary",
            f"# Image:   {self.image_path}",
            f"# Date:    {self.start_time.isoformat()}",
            f"# Total:   {len(self.findings)} findings",
            f"# Tiers:   {self.tier_stats}",
            "",
        ]
        for tier in (TIER_HIGH, TIER_BIP39, TIER_BINARY, TIER_LOW, TIER_ENTROPY):
            hits = [f for f in self.findings if f.tier == tier]
            if not hits: continue
            lines.append(f"{'='*60}")
            lines.append(f"  {tier}  ({len(hits)} findings)")
            lines.append(f"{'='*60}")
            for f in hits:
                lines += [
                    f"  [{f.schema}]",
                    f"    Offset   : {hex(f.offset)}",
                    f"    Raw      : {f.raw[:120]}{'…' if len(f.raw)>120 else ''}",
                    f"    Validated: {f.validated}",
                    f"    Notes    : {f.notes}",
                    f"    Context  : {f.context[:100]}",
                    "",
                ]
        summary.write_text('\n'.join(lines))

        # CSV manifest
        csv_file = base / "results.csv"
        csv_lines = ["tier,schema,offset,raw,validated,notes,context"]
        for f in self.findings:
            def _esc(s): return '"' + str(s).replace('"','""')[:200] + '"'
            csv_lines.append(','.join([
                _esc(f.tier), _esc(f.schema), _esc(hex(f.offset)),
                _esc(f.raw[:80]), _esc(f.validated),
                _esc(f.notes), _esc(f.context[:60])
            ]))
        csv_file.write_text('\n'.join(csv_lines))

        # JSON
        json_file = base / "results.json"
        json_file.write_text(json.dumps({
            "scan_time":   self.start_time.isoformat(),
            "image":       self.image_path,
            "tier_stats":  self.tier_stats,
            "schema_stats":self.schema_stats,
            "findings":    [f.to_dict() for f in self.findings],
        }, indent=2))

        # Carving hints (offsets of HIGH/BIP39 for use with foremost/scalpel)
        carve_file = base / "carving_offsets.txt"
        carve_lines = ["# Carving hint offsets (HIGH + BIP39 tier)"]
        carve_lines += [
            f"{hex(f.offset)}\t{f.schema}"
            for f in self.findings
            if f.tier in (TIER_HIGH, TIER_BIP39, TIER_BINARY)
        ]
        carve_file.write_text('\n'.join(carve_lines))

        print(f"\n{Fore.CYAN}Output written to: {base}{Style.RESET_ALL}")
        print(f"  {Fore.WHITE}summary.txt{Style.RESET_ALL}          — human-readable report")
        print(f"  {Fore.WHITE}results.csv{Style.RESET_ALL}          — evidence manifest CSV")
        print(f"  {Fore.WHITE}results.json{Style.RESET_ALL}         — machine-readable JSON")
        print(f"  {Fore.WHITE}carving_offsets.txt{Style.RESET_ALL}  — offsets for foremost/scalpel")

# ══════════════════════════════════════════════════════════════════════════════
# TERMINAL OUTPUT
# ══════════════════════════════════════════════════════════════════════════════
_TIER_COLOR = {
    TIER_HIGH:    Fore.GREEN,
    TIER_BIP39:   Fore.MAGENTA,
    TIER_BINARY:  Fore.CYAN,
    TIER_LOW:     Fore.YELLOW,
    TIER_ENTROPY: Fore.BLUE,
}
_TIER_LABEL = {
    TIER_HIGH:    "[HIGH  ]",
    TIER_BIP39:   "[BIP39 ]",
    TIER_BINARY:  "[BIN   ]",
    TIER_LOW:     "[LOW   ]",
    TIER_ENTROPY: "[ENTR  ]",
}

def _print_header(path, file_size, scan_size, byte_start,
                  strings_on, regex_on, binary_on, entropy_on):
    W = 72
    print(f"\n{Style.BRIGHT}{Fore.CYAN}{'═'*W}")
    print(f"  CRYPTO KEY SCANNER  v{VERSION}  —  Unified Forensic Edition")
    print(f"{'═'*W}{Style.RESET_ALL}")
    print(f"  Image      : {Fore.WHITE}{path}{Style.RESET_ALL}")
    print(f"  Size       : {Fore.WHITE}{file_size:,} bytes  ({file_size/1024/1024:.1f} MB){Style.RESET_ALL}")
    print(f"  Scan range : {Fore.WHITE}{byte_start:,} → {byte_start+scan_size:,}{Style.RESET_ALL}")
    flags = []
    flags.append(f"Strings:{Fore.GREEN+'ON' if strings_on else Fore.RED+'OFF'}{Style.RESET_ALL}")
    flags.append(f"Regex:{Fore.GREEN+'ON' if regex_on else Fore.RED+'OFF'}{Style.RESET_ALL}")
    flags.append(f"Binary:{Fore.GREEN+'ON' if binary_on else Fore.RED+'OFF'}{Style.RESET_ALL}")
    flags.append(f"Entropy:{Fore.GREEN+'ON' if entropy_on else Fore.RED+'OFF'}{Style.RESET_ALL}")
    print(f"  Passes     : " + "  ".join(flags))
    if not HAS_BASE58:
        print(f"  {Fore.YELLOW}⚠ pip install base58    — enables WIF/xprv checksum validation{Style.RESET_ALL}")
    if not HAS_MNEMONIC:
        print(f"  {Fore.YELLOW}⚠ pip install mnemonic  — enables BIP39 checksum validation{Style.RESET_ALL}")
    print(f"{Style.BRIGHT}{Fore.CYAN}{'─'*W}{Style.RESET_ALL}\n")

def _print_finding(f: KeyFinding):
    tc    = _TIER_COLOR.get(f.tier, Fore.WHITE)
    tl    = _TIER_LABEL.get(f.tier, f"[{f.tier}]")
    vstag = (f"{Fore.GREEN}✓ VALID{Style.RESET_ALL}"
             if f.validated
             else (f"{Fore.YELLOW}? UNCONFIRMED{Style.RESET_ALL}"
                   if f.validated is None
                   else f"{Fore.RED}✗ INVALID{Style.RESET_ALL}"))
    raw_d = f.raw[:88] + ('…' if len(f.raw) > 88 else '')
    print(f"\n{tc}{Style.BRIGHT}{tl} {f.schema}{Style.RESET_ALL}")
    print(f"  {Fore.WHITE}@{hex(f.offset)}{Style.RESET_ALL}  {vstag}")
    print(f"  {Fore.WHITE}{raw_d}{Style.RESET_ALL}")
    if f.notes:
        print(f"  {Style.DIM}{f.notes}{Style.RESET_ALL}")
    if f.context:
        print(f"  {Style.DIM}{f.context[:100]}{Style.RESET_ALL}")

def _print_progress(pct: float, offset: int, found: int):
    bar = '█'*int(40*pct/100) + '░'*(40-int(40*pct/100))
    print(f"\r  {Fore.CYAN}[{bar}] {pct:5.1f}%  @{hex(offset)}  found={found}{Style.RESET_ALL}",
          end='', flush=True)

def _print_footer(findings, tier_stats, schema_stats, elapsed, scanned):
    W = 72
    print(f"\n\n{Style.BRIGHT}{Fore.CYAN}{'═'*W}{Style.RESET_ALL}")
    print(f"  SCAN COMPLETE")
    if elapsed > 0:
        print(f"  Scanned  : {scanned:,} bytes in {elapsed:.1f}s  "
              f"({scanned/elapsed/1024/1024:.1f} MB/s)")
    print(f"  Findings : {Style.BRIGHT}{Fore.GREEN}{len(findings)}{Style.RESET_ALL}  "
          + "  ".join(
              f"{_TIER_COLOR.get(t,'')+t+Style.RESET_ALL}={c}"
              for t, c in tier_stats.items() if c))
    if schema_stats:
        print(f"\n  {Style.BRIGHT}Schema breakdown:{Style.RESET_ALL}")
        for schema, count in sorted(schema_stats.items(), key=lambda x: -x[1]):
            tc = _TIER_COLOR.get(
                next((f.tier for f in findings if f.schema==schema), ""), "")
            print(f"    {tc}{schema:<55}{Style.RESET_ALL}: {count}")
    print(f"{Style.BRIGHT}{Fore.CYAN}{'═'*W}{Style.RESET_ALL}\n")

# ══════════════════════════════════════════════════════════════════════════════
# CLI
# ══════════════════════════════════════════════════════════════════════════════
def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="crypto_key_scanner.py",
        description="Crypto Private Key Scanner — Unified Forensic Edition",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=f"""
Version: {VERSION}

PASS MODES
  Default       : all three passes (strings + regex + binary)
  --fast        : strings + regex only  (skip binary engine, ~5× faster)
  --binary-only : binary + entropy only (skip strings/regex)
  --no-strings  : skip strings extraction pass
  --no-binary   : skip binary scanner
  --no-entropy  : skip entropy sliding-window (within binary pass)

EXAMPLES
  # Full scan, save all outputs to a run folder
  python3 crypto_key_scanner.py disk.img -o ~/scan_output/

  # Raw block device (needs root)
  sudo python3 crypto_key_scanner.py /dev/sdb -o ~/scan_output/

  # Fast triage (strings + regex, no binary)
  python3 crypto_key_scanner.py disk.img --fast

  # Bitcoin + Ethereum only, skip unvalidated hits
  python3 crypto_key_scanner.py disk.img --schemas bitcoin ethereum \\
          --skip-unvalidated

  # Scan specific partition (sectors 2048–1953024)
  python3 crypto_key_scanner.py disk.img --sector-start 2048 \\
          --sector-end 1953024

  # Auto-discover removable USB/SD devices (Linux/macOS, needs root)
  sudo python3 crypto_key_scanner.py --discover -o ~/scan_output/

  # Tighter entropy (fewer false positives, higher threshold)
  python3 crypto_key_scanner.py disk.img --entropy-threshold 4.5 \\
          --entropy-stride 8

  # List every supported schema
  python3 crypto_key_scanner.py --list-schemas

INTEGRATION WITH scan_crypto.sh
  The binary pass can be called as a companion to scan_crypto.sh:
    sudo zsh scan_crypto.sh --fast          # raw/strings triage
    python3 crypto_key_scanner.py /dev/disk2s1 --binary-only -o ~/scan_output/
  Results in carving_offsets.txt are compatible with foremost/scalpel.
""")

    p.add_argument("image", nargs="?", help="Disk image or block device path")
    p.add_argument("-o", "--output-dir", metavar="DIR",
                   help="Output directory (creates run_TIMESTAMP subfolder)")
    p.add_argument("--sector-start",   type=int, default=0)
    p.add_argument("--sector-end",     type=int, default=None)
    p.add_argument("--schemas",        nargs="+", metavar="SCHEMA",
                   help="Filter to schemas containing these keywords")
    p.add_argument("--skip-unvalidated", action="store_true",
                   help="Only output cryptographically valid hits")
    p.add_argument("--no-validate",    action="store_true",
                   help="Skip all cryptographic validation")

    # Pass toggles
    pg = p.add_argument_group("Pass toggles")
    pg.add_argument("--fast",          action="store_true",
                    help="Strings + regex only (skip binary engine)")
    pg.add_argument("--binary-only",   action="store_true",
                    help="Binary + entropy pass only")
    pg.add_argument("--no-strings",    action="store_true",
                    help="Skip strings extraction pass")
    pg.add_argument("--no-regex",      action="store_true",
                    help="Skip regex pattern pass")
    pg.add_argument("--no-binary",     action="store_true",
                    help="Skip binary scanner")
    pg.add_argument("--no-entropy",    action="store_true",
                    help="Skip entropy sliding-window scan")

    # Tuning
    tg = p.add_argument_group("Tuning")
    tg.add_argument("--entropy-threshold", type=float, default=3.8,
                    metavar="BITS",
                    help="Shannon entropy floor for entropy scan (default 3.8)")
    tg.add_argument("--entropy-stride",    type=int,   default=4,
                    metavar="N",
                    help="Stride for entropy window scan (default 4; larger=faster)")
    tg.add_argument("--min-str-len",       type=int,   default=MIN_STR_LEN,
                    metavar="N",
                    help=f"Min printable string length (default {MIN_STR_LEN})")
    tg.add_argument("--min-free-gb",       type=float, default=MIN_FREE_GB,
                    metavar="GB",
                    help=f"Min free space in output dir (default {MIN_FREE_GB} GB)")

    # Misc
    p.add_argument("--discover",       action="store_true",
                   help="Auto-discover removable USB/SD devices and scan all")
    p.add_argument("--list-schemas",   action="store_true",
                   help="List all supported schemas and exit")
    p.add_argument("-v", "--verbose",  action="store_true")
    p.add_argument("--version",        action="version",
                   version=f"crypto_key_scanner {VERSION}")
    return p


def main():
    parser = build_parser()
    args   = parser.parse_args()

    # ── list schemas ──────────────────────────────────────────────────────────
    if args.list_schemas:
        print(f"\n{Style.BRIGHT}Text / regex schemas:{Style.RESET_ALL}")
        for schema, tier, *_ in TEXT_PATTERNS:
            tc = _TIER_COLOR.get(tier, "")
            print(f"  {tc}{_TIER_LABEL.get(tier,'')} {schema}{Style.RESET_ALL}")
        print(f"\n{Style.BRIGHT}Binary schemas:{Style.RESET_ALL}")
        for s in [
            "Binary DER EC key (RFC 5915)",
            "Binary BIP32 xprv blob (78-byte structure)",
            "Binary raw WIF (0x80 prefix)",
            "Binary BIP32 child key (0x00 + chaincode heuristic)",
            "Binary wallet.dat key record",
            "Berkeley DB page (wallet.dat structure)",
            "Binary Solana id.json keypair",
            "Binary Ed25519 seed (DER OID 1.3.101.112)",
            "Binary PKCS#8 secp256k1 key",
            "Binary Electrum 16-byte seed",
            "Binary Armory wallet root key",
            "Binary entropy candidate (secp256k1-valid window)",
        ]:
            print(f"  {Fore.CYAN}[BIN  ] {s}{Style.RESET_ALL}")
        print()
        sys.exit(0)

    # ── resolve target(s) ─────────────────────────────────────────────────────
    targets = []
    if args.discover:
        targets = discover_removable_devices()
        if not targets:
            print(f"{Fore.YELLOW}No removable devices found.{Style.RESET_ALL}")
            sys.exit(0)
        print(f"{Fore.CYAN}Discovered devices:{Style.RESET_ALL}")
        for t in targets:
            print(f"  {t}")
    elif args.image:
        targets = [args.image]
    else:
        parser.print_help()
        sys.exit(1)

    # ── build pass flags ──────────────────────────────────────────────────────
    do_strings = not args.no_strings and not args.binary_only
    do_regex   = not args.no_regex   and not args.binary_only
    do_binary  = not args.no_binary  and not args.fast
    do_entropy = not args.no_entropy

    # ── scan each target ──────────────────────────────────────────────────────
    for image_path in targets:
        try:
            scanner = CryptoKeyScanner(
                image_path        = image_path,
                output_dir        = args.output_dir,
                validate          = not args.no_validate,
                skip_unvalidated  = args.skip_unvalidated,
                sector_start      = args.sector_start,
                sector_end        = args.sector_end,
                schema_filter     = args.schemas,
                do_strings_pass   = do_strings,
                do_regex_pass     = do_regex,
                do_binary_pass    = do_binary,
                do_entropy        = do_entropy,
                min_str_len       = args.min_str_len,
                entropy_threshold = args.entropy_threshold,
                entropy_stride    = args.entropy_stride,
                min_free_gb       = args.min_free_gb,
                verbose           = args.verbose,
            )
            scanner.scan()
        except KeyboardInterrupt:
            print(f"\n{Fore.YELLOW}Interrupted.{Style.RESET_ALL}")
            sys.exit(1)
        except FileNotFoundError as e:
            print(f"{Fore.RED}Error: {e}{Style.RESET_ALL}")
            if len(targets) == 1:
                sys.exit(2)
        except PermissionError:
            print(f"{Fore.RED}Permission denied: {image_path}\n"
                  f"Try: sudo python3 {sys.argv[0]} ...{Style.RESET_ALL}")
            if len(targets) == 1:
                sys.exit(3)
        except Exception as e:
            print(f"{Fore.RED}Unexpected error on {image_path}: {e}{Style.RESET_ALL}")
            if args.verbose:
                import traceback; traceback.print_exc()


if __name__ == "__main__":
    main()