BoringSecretHunter 1.2.1__py3-none-any.whl

boring_secret_hunter/__init__.py

@@ -0,0 +1,40 @@
+"""BoringSecretHunter - Extract ssl_log_secret() offsets from BoringSSL/RustLS binaries."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("BoringSecretHunter")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+from boring_secret_hunter.analyzer import (
+    analyze,
+    analyze_binary,
+    analyze_parallel,
+    discover_binaries,
+)
+from boring_secret_hunter.binary_classifier import BinaryType, classify_binary
+from boring_secret_hunter.config import find_ghidra, find_java
+from boring_secret_hunter.ghidra_runner import GhidraError
+from boring_secret_hunter.result import AnalysisResult, BatchResult, FunctionMatch
+
+__all__ = [
+    "__version__",
+    # Analysis
+    "analyze",
+    "analyze_binary",
+    "analyze_parallel",
+    "discover_binaries",
+    # Data models
+    "AnalysisResult",
+    "BatchResult",
+    "FunctionMatch",
+    # Config helpers
+    "find_ghidra",
+    "find_java",
+    # Classification
+    "BinaryType",
+    "classify_binary",
+    # Errors
+    "GhidraError",
+]

boring_secret_hunter/__main__.py

@@ -0,0 +1,6 @@
+"""Support running as `python -m boring_secret_hunter`."""
+
+from boring_secret_hunter.cli import main
+
+if __name__ == "__main__":
+    main()

boring_secret_hunter/analyzer.py

@@ -0,0 +1,287 @@
+"""Main analysis orchestrator — ports ghidra_analysis.sh."""
+
+import logging
+from concurrent.futures import ThreadPoolExecutor
+
+import shutil
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from boring_secret_hunter.archive_extractor import extract_binaries, is_archive
+from boring_secret_hunter.arch_detector import detect_architecture, detect_from_siblings
+from boring_secret_hunter.binary_classifier import (
+    BinaryType,
+    classify_binary,
+    is_archive_extension,
+)
+from boring_secret_hunter.ghidra_runner import GhidraError, parse_output, run_analysis
+from boring_secret_hunter.result import AnalysisResult, BatchResult, FunctionMatch
+
+log = logging.getLogger(__name__)
+
+# Threshold for "large dump" mode (in bytes)
+LARGE_DUMP_THRESHOLD = 100 * 1024 * 1024  # 100 MB
+
+
+def discover_binaries(path: Path) -> List[Path]:
+    """Discover all supported binaries at the given path.
+
+    If path is a file, returns [path] if it's a supported binary or archive.
+    If path is a directory, returns all supported binaries in the directory.
+    """
+    if path.is_file():
+        return [path]
+
+    if not path.is_dir():
+        log.error("Path does not exist: %s", path)
+        return []
+
+    binaries = []
+    for item in sorted(path.iterdir()):
+        if not item.is_file():
+            continue
+        if is_archive_extension(item):
+            continue
+        bin_type = classify_binary(item)
+        if bin_type != BinaryType.UNKNOWN:
+            binaries.append(item)
+    return binaries
+
+
+def _parse_function_matches(parsed_output: str) -> List[FunctionMatch]:
+    """Parse function match info from the BoringSecretHunter output."""
+    functions = []
+    current = FunctionMatch()
+
+    for line in parsed_output.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+
+        # Look for function label patterns
+        if "Function Label:" in line or "function label:" in line.lower():
+            if current.label:
+                functions.append(current)
+                current = FunctionMatch()
+            current.label = line.split(":", 1)[1].strip()
+        elif "Ghidra Offset:" in line or "ghidra offset:" in line.lower():
+            current.ghidra_offset = line.split(":", 1)[1].strip()
+        elif "IDA Offset:" in line or "ida offset:" in line.lower():
+            current.ida_offset = line.split(":", 1)[1].strip()
+        elif "Byte Pattern:" in line or "byte pattern:" in line.lower():
+            current.byte_pattern = line.split(":", 1)[1].strip()
+
+    if current.label:
+        functions.append(current)
+
+    return functions
+
+
+def _detect_tls_library(parsed_output: str) -> str:
+    """Detect TLS library type from output."""
+    lower = parsed_output.lower()
+    if "boringssl" in lower:
+        return "BoringSSL"
+    elif "rustls" in lower:
+        return "RustLS"
+    elif "openssl" in lower:
+        return "OpenSSL"
+    return "unknown"
+
+
+def analyze_binary(
+    binary_path: Path,
+    ghidra_dir: str,
+    debug: bool = False,
+    large_dump_mode: Optional[str] = None,
+    processor_override: Optional[str] = None,
+) -> AnalysisResult:
+    """Analyze a single binary.
+
+    Args:
+        binary_path: Path to the binary
+        ghidra_dir: Path to Ghidra installation
+        debug: Enable debug output
+        large_dump_mode: Mode for large dumps ('normal', 'fast', 'skip')
+        processor_override: Override processor detection with this value
+    """
+    result = AnalysisResult(
+        binary_name=binary_path.name,
+        binary_path=str(binary_path),
+    )
+
+    bin_type = classify_binary(binary_path)
+    result.binary_type = bin_type.value
+
+    # Detect architecture
+    arch = detect_architecture(binary_path)
+    if arch:
+        result.architecture = arch
+
+    # Build extra args for raw data files
+    extra_args = []
+    if bin_type == BinaryType.RAW_DATA:
+        proc = processor_override or detect_from_siblings(
+            binary_path.parent, processor_override
+        )
+        result.architecture = proc
+        extra_args = ["-processor", proc, "-loader", "BinaryLoader"]
+        log.info("    Raw data file detected, using processor: %s", proc)
+
+        # Check size for large dump handling
+        file_size = binary_path.stat().st_size
+        if file_size > LARGE_DUMP_THRESHOLD:
+            size_mb = file_size // (1024 * 1024)
+            mode = large_dump_mode or "normal"
+            if mode == "skip":
+                log.info(
+                    "    Skipping %s (%d MB) per user choice.",
+                    binary_path.name,
+                    size_mb,
+                )
+                result.error = f"Skipped (large dump: {size_mb} MB)"
+                return result
+
+    try:
+        raw_output = run_analysis(
+            binary_path=binary_path,
+            ghidra_dir=ghidra_dir,
+            extra_args=extra_args if extra_args else None,
+            debug=debug,
+            large_dump_mode=large_dump_mode,
+        )
+        result.raw_output = raw_output
+
+        parsed = parse_output(raw_output)
+        if parsed.strip():
+            result.success = True
+            result.functions = _parse_function_matches(parsed)
+            result.tls_library_type = _detect_tls_library(parsed)
+        else:
+            log.warning(
+                "    No results found in Ghidra output for %s", binary_path.name
+            )
+            if debug:
+                log.debug("Raw output:\n%s", raw_output)
+
+        if debug:
+            log.debug("Raw Ghidra output:\n%s", raw_output)
+
+    except GhidraError as e:
+        result.error = str(e)
+        log.error("    Analysis failed: %s", e)
+
+    return result
+
+
+def analyze(
+    path: Path,
+    ghidra_dir: str,
+    debug: bool = False,
+    large_dump_mode: Optional[str] = None,
+    processor_override: Optional[str] = None,
+    on_result: Optional[Callable[[AnalysisResult, str], None]] = None,
+) -> BatchResult:
+    """Analyze one or more binaries.
+
+    Handles archives (APK/IPA/ZIP), single files, and directories.
+
+    Args:
+        path: Path to binary, archive, or directory
+        ghidra_dir: Path to Ghidra installation
+        debug: Enable debug output
+        large_dump_mode: Mode for large dumps
+        processor_override: Override processor for raw dumps
+    """
+    batch = BatchResult()
+    temp_dirs = []
+
+    try:
+        # Handle archives
+        if path.is_file() and is_archive(path):
+            extracted, tmp_dir = extract_binaries(path)
+            temp_dirs.append(tmp_dir)
+            binaries = extracted
+        else:
+            binaries = discover_binaries(path)
+
+        batch.total = len(binaries)
+
+        if not binaries:
+            log.warning(
+                "No supported binaries found. Supported types: ELF, Mach-O, PE32, raw data files."
+            )
+            return batch
+
+        if len(binaries) == 1:
+            log.info("Found 1 binary to analyze:")
+        else:
+            log.info("Found %d binaries to analyze:", len(binaries))
+        for i, b in enumerate(binaries, 1):
+            log.info("    %d. %s", i, b.name)
+
+        for i, binary in enumerate(binaries, 1):
+            log.info("[%d/%d] Analyzing %s...", i, batch.total, binary.name)
+
+            result = analyze_binary(
+                binary_path=binary,
+                ghidra_dir=ghidra_dir,
+                debug=debug,
+                large_dump_mode=large_dump_mode,
+                processor_override=processor_override,
+            )
+            batch.results.append(result)
+
+            if result.success:
+                batch.successful += 1
+                parsed = parse_output(result.raw_output)
+                if parsed.strip():
+                    log.debug("Parsed output for %s:\n%s", binary.name, parsed)
+                    if on_result is not None:
+                        on_result(result, parsed)
+
+    finally:
+        for tmp_dir in temp_dirs:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    return batch
+
+
+def analyze_parallel(
+    binaries: List[Path],
+    ghidra_dir: str,
+    max_workers: int = 4,
+    debug: bool = False,
+    large_dump_mode: Optional[str] = None,
+    processor_override: Optional[str] = None,
+) -> Dict[Path, AnalysisResult]:
+    """Analyze multiple binaries in parallel using threads.
+
+    Args:
+        binaries: List of binary paths to analyze
+        ghidra_dir: Path to Ghidra installation
+        max_workers: Maximum number of concurrent analyses
+        debug: Enable debug output
+        large_dump_mode: Mode for large dumps ('normal', 'fast', 'skip')
+        processor_override: Override processor for raw dumps
+
+    Returns:
+        Dictionary mapping each binary path to its AnalysisResult.
+    """
+    results: Dict[Path, AnalysisResult] = {}
+
+    def _run(binary_path: Path) -> tuple:
+        result = analyze_binary(
+            binary_path=binary_path,
+            ghidra_dir=ghidra_dir,
+            debug=debug,
+            large_dump_mode=large_dump_mode,
+            processor_override=processor_override,
+        )
+        return binary_path, result
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        for path, result in executor.map(_run, binaries):
+            results[path] = result
+
+    return results

boring_secret_hunter/arch_detector.py

@@ -0,0 +1,118 @@
+"""Detect CPU architecture from binary headers."""
+
+import struct
+from pathlib import Path
+from typing import Optional
+
+from boring_secret_hunter.binary_classifier import (
+    BinaryType,
+    classify_binary,
+    _MACHO_MAGIC_64_LE,
+    _MACHO_MAGIC_32_LE,
+    _MACHO_MAGIC_64_BE,
+    _MACHO_MAGIC_32_BE,
+    _MACHO_FAT_BE,
+    _MACHO_FAT_LE,
+)
+
+
+# ELF e_machine values (at offset 18, 2 bytes)
+_ELF_MACHINES = {
+    0x03: "x86:LE:32:default",  # EM_386
+    0x3E: "x86:LE:64:default",  # EM_X86_64
+    0x28: "ARM:LE:32:v8",  # EM_ARM
+    0xB7: "AARCH64:LE:64:v8A",  # EM_AARCH64
+    0x08: "MIPS:BE:32:default",  # EM_MIPS
+    0xF3: "RISCV:LE:64:default",  # EM_RISCV
+}
+
+# Mach-O cputype values (at offset 4, 4 bytes)
+_MACHO_CPUTYPES_LE = {
+    0x0C: "ARM:LE:32:v8",  # CPU_TYPE_ARM
+    0x0100000C: "AARCH64:LE:64:v8A",  # CPU_TYPE_ARM64
+    0x07: "x86:LE:32:default",  # CPU_TYPE_X86
+    0x01000007: "x86:LE:64:default",  # CPU_TYPE_X86_64
+}
+
+DEFAULT_PROCESSOR = "AARCH64:LE:64:v8A"
+
+
+def detect_architecture(path: Path) -> Optional[str]:
+    """Detect Ghidra processor string from binary headers.
+
+    Returns a Ghidra-compatible processor string like 'AARCH64:LE:64:v8A'
+    or None if detection fails.
+    """
+    bin_type = classify_binary(path)
+
+    if bin_type == BinaryType.ELF:
+        return _detect_elf_arch(path)
+    elif bin_type == BinaryType.MACHO:
+        return _detect_macho_arch(path)
+    return None
+
+
+def _detect_elf_arch(path: Path) -> Optional[str]:
+    """Read ELF e_machine field at offset 18."""
+    try:
+        with open(path, "rb") as f:
+            f.seek(5)
+            ei_data = struct.unpack("B", f.read(1))[0]
+            endian = "<" if ei_data == 1 else ">"
+            f.seek(18)
+            e_machine = struct.unpack(f"{endian}H", f.read(2))[0]
+        return _ELF_MACHINES.get(e_machine)
+    except (OSError, struct.error):
+        return None
+
+
+def _detect_macho_arch(path: Path) -> Optional[str]:
+    """Read Mach-O cputype field at offset 4."""
+    try:
+        with open(path, "rb") as f:
+            magic = f.read(4)
+            # Determine endianness from magic
+            if magic in (_MACHO_MAGIC_64_LE, _MACHO_MAGIC_32_LE):
+                endian = "<"
+            elif magic in (_MACHO_MAGIC_64_BE, _MACHO_MAGIC_32_BE):
+                endian = ">"
+            elif magic == _MACHO_FAT_BE:
+                # Fat binary - read first arch
+                endian = ">"
+                f.seek(8)  # skip to first arch cputype
+            elif magic == _MACHO_FAT_LE:
+                endian = "<"
+                f.seek(8)
+            else:
+                return None
+            cputype = struct.unpack(f"{endian}I", f.read(4))[0]
+        return _MACHO_CPUTYPES_LE.get(cputype)
+    except (OSError, struct.error):
+        return None
+
+
+def detect_from_siblings(
+    directory: Path, processor_override: Optional[str] = None
+) -> str:
+    """Detect processor from sibling binaries in the same directory.
+
+    Used for raw data dumps where the binary itself has no headers.
+
+    Args:
+        directory: Directory to scan for sibling binaries
+        processor_override: If set, use this value directly (from CLI --processor flag)
+
+    Returns:
+        Ghidra processor string, defaults to AARCH64:LE:64:v8A
+    """
+    if processor_override:
+        return processor_override
+
+    for sibling in directory.iterdir():
+        if not sibling.is_file():
+            continue
+        arch = detect_architecture(sibling)
+        if arch:
+            return arch
+
+    return DEFAULT_PROCESSOR

boring_secret_hunter/archive_extractor.py

@@ -0,0 +1,74 @@
+"""Extract binaries from APK/IPA/ZIP archives."""
+
+import logging
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import List, Tuple
+
+from boring_secret_hunter.binary_classifier import BinaryType, classify_binary
+
+log = logging.getLogger(__name__)
+
+# Archive types recognized by extension
+_ARCHIVE_EXTENSIONS = {".apk", ".ipa", ".zip"}
+
+
+def is_archive(path: Path) -> bool:
+    """Check if a file is a supported archive type."""
+    return path.suffix.lower() in _ARCHIVE_EXTENSIONS
+
+
+def extract_binaries(archive_path: Path) -> Tuple[List[Path], Path]:
+    """Extract binaries from an archive.
+
+    For APK: extracts only .so files that are ELF binaries.
+    For IPA: extracts all Mach-O binaries.
+    For ZIP: extracts all ELF and Mach-O binaries.
+
+    Returns:
+        Tuple of (list of extracted binary paths, temp directory to clean up)
+    """
+    suffix = archive_path.suffix.lower()
+    tmp_dir = Path(tempfile.mkdtemp(prefix="bsh_extract_"))
+
+    log.info("Extracting archive: %s", archive_path.name)
+
+    try:
+        with zipfile.ZipFile(archive_path, "r") as zf:
+            zf.extractall(tmp_dir)
+    except (zipfile.BadZipFile, Exception) as e:
+        log.warning("Failed to extract %s: %s", archive_path.name, e)
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        return [], tmp_dir
+
+    extracted = []
+    for candidate in tmp_dir.rglob("*"):
+        if not candidate.is_file() or candidate.stat().st_size < 1024:
+            continue
+
+        bin_type = classify_binary(candidate)
+        should_extract = False
+
+        if suffix == ".apk":
+            if candidate.suffix == ".so" and bin_type == BinaryType.ELF:
+                should_extract = True
+        elif suffix == ".ipa":
+            if bin_type == BinaryType.MACHO:
+                should_extract = True
+        else:
+            if bin_type in (BinaryType.ELF, BinaryType.MACHO):
+                should_extract = True
+
+        if should_extract:
+            relative = candidate.relative_to(tmp_dir)
+            sanitized = str(relative).replace("/", "__").replace("\\", "__")
+            dest_name = f"{archive_path.name}__{sanitized}"
+            dest_path = tmp_dir / dest_name
+            if candidate != dest_path:
+                shutil.copy2(candidate, dest_path)
+            extracted.append(dest_path)
+            log.info("    Found: %s", relative)
+
+    return extracted, tmp_dir

boring_secret_hunter/binary_classifier.py

@@ -0,0 +1,66 @@
+"""Classify binary files by magic bytes."""
+
+import enum
+from pathlib import Path
+
+
+class BinaryType(enum.Enum):
+    ELF = "elf"
+    MACHO = "macho"
+    PE32 = "pe32"
+    RAW_DATA = "data"
+    UNKNOWN = "unknown"
+
+
+# Magic byte signatures
+_ELF_MAGIC = b"\x7fELF"
+_MACHO_MAGIC_64_LE = b"\xcf\xfa\xed\xfe"  # 64-bit little-endian
+_MACHO_MAGIC_32_LE = b"\xce\xfa\xed\xfe"  # 32-bit little-endian
+_MACHO_MAGIC_64_BE = b"\xfe\xed\xfa\xcf"  # 64-bit big-endian
+_MACHO_MAGIC_32_BE = b"\xfe\xed\xfa\xce"  # 32-bit big-endian
+_MACHO_FAT_BE = b"\xca\xfe\xba\xbe"  # Universal/fat binary
+_MACHO_FAT_LE = b"\xbe\xba\xfe\xca"  # Universal/fat binary (LE)
+_PE_MAGIC = b"MZ"
+
+
+def classify_binary(path: Path) -> BinaryType:
+    """Classify a binary file by reading its magic bytes.
+
+    Returns BinaryType enum indicating the file type.
+    """
+    try:
+        with open(path, "rb") as f:
+            header = f.read(4)
+    except (OSError, IOError):
+        return BinaryType.UNKNOWN
+
+    if len(header) < 2:
+        return BinaryType.UNKNOWN
+
+    if header[:4] == _ELF_MAGIC:
+        return BinaryType.ELF
+
+    if header[:4] in (
+        _MACHO_MAGIC_64_LE,
+        _MACHO_MAGIC_32_LE,
+        _MACHO_MAGIC_64_BE,
+        _MACHO_MAGIC_32_BE,
+        _MACHO_FAT_BE,
+        _MACHO_FAT_LE,
+    ):
+        return BinaryType.MACHO
+
+    if header[:2] == _PE_MAGIC:
+        return BinaryType.PE32
+
+    return BinaryType.RAW_DATA
+
+
+def is_supported_binary(path: Path) -> bool:
+    """Check if a file is a supported binary type (not UNKNOWN)."""
+    return classify_binary(path) != BinaryType.UNKNOWN
+
+
+def is_archive_extension(path: Path) -> bool:
+    """Check if a file has an archive extension (to skip during classification)."""
+    return path.suffix.lower() in {".apk", ".ipa", ".zip", ".jar"}