BX2trace 1.0.0__py3-none-any.whl

bx2trace/__init__.py

@@ -0,0 +1,70 @@
+# bx2trace - Windows Process Tracer & Live Memory Extractor
+# =========================================================
+
+# Core contracts & data types
+from bx2trace.core.models import (
+    TraceEvent,
+    TraceMode,
+    Severity,
+    EngineConfig,
+    BaseDetector,
+    CURRENT_SCHEMA_VERSION,
+)
+
+# Execution engines
+from bx2trace.core.debug_thread import DebugThread, TrackedProcess
+from bx2trace.core.memory_scanner import MemoryScannerThread
+from bx2trace.core.process_launcher import (
+    create_process_debug,
+    ArchitectureMismatchError,
+)
+
+# Raw memory access
+from bx2trace.memory.reader import (
+    open_process_for_dump,
+    enumerate_regions,
+    read_region,
+    read_committed_regions,
+)
+
+# Extractors (platform-agnostic)
+from bx2trace.extractors.strings import (
+    extract_strings,
+    extract_ascii_strings,
+    extract_utf16le_strings,
+    diff_new_strings,
+    URL_PATTERN,
+    IPV4_PATTERN,
+)
+from bx2trace.extractors.entropy import (
+    shannon_entropy,
+    entropy_by_page,
+)
+
+# Useful constants
+from bx2trace.core.constants import (
+    PAGE_EXECUTE_READWRITE,
+    PAGE_EXECUTE_READ,
+    PAGE_READWRITE,
+    PAGE_READONLY,
+    MEM_COMMIT,
+    PROTECTIONS_OF_INTEREST,
+)
+
+__version__ = "0.1.0"
+__author__ = "bx2trace contributors"
+
+__all__ = [
+    "TraceEvent", "TraceMode", "Severity", "EngineConfig", "BaseDetector",
+    "CURRENT_SCHEMA_VERSION",
+    "DebugThread", "TrackedProcess", "MemoryScannerThread",
+    "create_process_debug", "ArchitectureMismatchError",
+    "open_process_for_dump", "enumerate_regions",
+    "read_region", "read_committed_regions",
+    "extract_strings", "extract_ascii_strings", "extract_utf16le_strings",
+    "diff_new_strings", "URL_PATTERN", "IPV4_PATTERN",
+    "shannon_entropy", "entropy_by_page",
+    "PAGE_EXECUTE_READWRITE", "PAGE_EXECUTE_READ",
+    "PAGE_READWRITE", "PAGE_READONLY",
+    "MEM_COMMIT", "PROTECTIONS_OF_INTEREST",
+]

bx2trace/core/api_hooker.py

@@ -0,0 +1,192 @@
+"""
+core/api_hooker.py
+==================
+Management of API hooks using the INT3 (0xCC) software breakpoint method.
+Provides resolution of API addresses and management of the original bytes.
+"""
+
+import ctypes
+from ctypes import wintypes
+from typing import Dict, Optional, Tuple
+
+
+class HookManager:
+    """
+    Manages API hooks for a debugged process.
+    Handles address resolution, INT3 placement, and original byte tracking.
+    """
+
+    def __init__(self):
+        self.hooks = {}  # (pid, addr) -> byte  # Address -> Original Byte
+        self.api_names: Dict[int, str] = {}  # Address -> API Name
+        self.kernel32 = ctypes.windll.kernel32
+
+    def resolve_api(self, dll_name: str, function_name: str) -> Optional[int]:
+        """
+        Resolves the address of an API in the target process.
+        Since system DLLs are loaded at the same address across processes (ASLR),
+        we can resolve it locally.
+        """
+        try:
+            h_module = self.kernel32.GetModuleHandleW(dll_name)
+            if not h_module:
+                h_module = self.kernel32.LoadLibraryW(dll_name)
+
+            if not h_module:
+                return None
+
+            addr = self.kernel32.GetProcAddress(h_module, function_name.encode('ascii'))
+            if addr == 0:
+                return None
+
+            # Check for JMP/Forwarder (simple check)
+            first_byte = ctypes.c_ubyte()
+            ctypes.memmove(ctypes.byref(first_byte), addr, 1)
+            if first_byte.value == 0xE9:  # JMP
+                # This is a jump, we might be hitting a hot-patch point or a wrapper
+                pass
+
+            return addr
+        except Exception:
+            return None
+
+    def apply_hook(self, process_handle: int, address: int, api_name: str, pid: int) -> bool:
+        """
+        Places an INT3 (0xCC) hook at the specified address.
+        Backups the original byte for restoration later.
+        """
+        if (pid, address) in self.hooks:
+            return True  # Already hooked
+
+        try:
+            # Read original byte
+            old_byte = ctypes.c_ubyte()
+            bytes_read = ctypes.c_size_t()
+            if not self.kernel32.ReadProcessMemory(
+                    process_handle,
+                    ctypes.c_void_p(address),
+                    ctypes.byref(old_byte),
+                    1,
+                    ctypes.byref(bytes_read)
+            ) or bytes_read.value != 1:
+                return False
+
+            # Check if it's already 0xCC (maybe another debugger or already hooked)
+            if old_byte.value == 0xCC:
+                # Still store it so we can handle the breakpoint if it's hit
+                if (pid, address) not in self.hooks:
+                    self.hooks[(pid, address)] = 0xCC  # We don't know original, but we track it
+                    self.api_names[address] = api_name
+                return True
+
+            # Ensure memory is writable (VirtualProtectEx)
+            old_protect = wintypes.DWORD()
+            PAGE_EXECUTE_READWRITE = 0x40
+            if not self.kernel32.VirtualProtectEx(
+                    process_handle,
+                    ctypes.c_void_p(address),
+                    1,
+                    PAGE_EXECUTE_READWRITE,
+                    ctypes.byref(old_protect)
+            ):
+                return False
+
+            # Write 0xCC (INT3)
+            int3 = ctypes.c_ubyte(0xCC)
+            bytes_written = ctypes.c_size_t()
+
+            success = self.kernel32.WriteProcessMemory(
+                process_handle,
+                ctypes.c_void_p(address),
+                ctypes.byref(int3),
+                1,
+                ctypes.byref(bytes_written)
+            ) and bytes_written.value == 1
+
+            # Restore protection
+            temp_protect = wintypes.DWORD()
+            self.kernel32.VirtualProtectEx(
+                process_handle,
+                ctypes.c_void_p(address),
+                1,
+                old_protect,
+                ctypes.byref(temp_protect)
+            )
+
+            if not success:
+                return False
+
+            self.hooks[(pid, address)] = old_byte.value
+            self.api_names[address] = api_name
+
+            # Flush instruction cache
+            self.kernel32.FlushInstructionCache(process_handle, ctypes.c_void_p(address), 1)
+
+            # Verify write
+            verify_byte = ctypes.c_ubyte()
+            self.kernel32.ReadProcessMemory(process_handle, ctypes.c_void_p(address), ctypes.byref(verify_byte), 1,
+                                            None)
+            if verify_byte.value != 0xCC:
+                # print(f"Verification failed at {hex(address)}: expected 0xCC, got {hex(verify_byte.value)}")
+                return False
+
+            return True
+        except Exception:
+            return False
+
+    def remove_hook(self, process_handle: int, address: int, pid: int) -> bool:
+        """
+        Restores the original byte at the specified address.
+        """
+        if (pid, address) not in self.hooks:
+            return False
+
+        try:
+            # Ensure memory is writable (VirtualProtectEx)
+            old_protect = wintypes.DWORD()
+            PAGE_EXECUTE_READWRITE = 0x40
+            if not self.kernel32.VirtualProtectEx(
+                    process_handle,
+                    ctypes.c_void_p(address),
+                    1,
+                    PAGE_EXECUTE_READWRITE,
+                    ctypes.byref(old_protect)
+            ):
+                return False
+
+            original_byte = ctypes.c_ubyte(self.hooks[(pid, address)])
+            bytes_written = ctypes.c_size_t()
+
+            success = self.kernel32.WriteProcessMemory(
+                process_handle,
+                ctypes.c_void_p(address),
+                ctypes.byref(original_byte),
+                1,
+                ctypes.byref(bytes_written)
+            ) and bytes_written.value == 1
+
+            # Restore protection
+            temp_protect = wintypes.DWORD()
+            self.kernel32.VirtualProtectEx(
+                process_handle,
+                ctypes.c_void_p(address),
+                1,
+                old_protect,
+                ctypes.byref(temp_protect)
+            )
+
+            if not success:
+                return False
+
+            self.kernel32.FlushInstructionCache(process_handle, ctypes.c_void_p(address), 1)
+            return True
+        except Exception:
+            return False
+
+    def is_our_hook(self, address: int, pid: int) -> bool:
+        """Checks if the breakpoint hit is one of our hooks."""
+        return (pid, address) in self.hooks
+
+    def get_api_name(self, address: int) -> str:
+        """Returns the name of the API at the hooked address."""
+        return self.api_names.get(address, "UnknownAPI")

bx2trace/core/constants.py

@@ -0,0 +1,124 @@
+"""
+core/constants.py
+==================
+All raw Windows API constants in one place.
+Rule: Any magic number in the code is written here only once, and the rest of the files import it by name.
+
+Reference source for all these values: winbase.h / winnt.h (Official Microsoft Documentation).
+Do not modify a value here unless verified against official documentation — any error here fails silently
+in a completely different place from this file.
+"""
+
+# ============================================================
+# Process Creation Flags (Passed to CreateProcessW)
+# ============================================================
+
+# ⚠️ CRITICAL FIX: The following two values are easily inverted by mistake because they are numerically sequential.
+DEBUG_PROCESS = 0x00000001
+# ↑ Monitors the launched process + every child process it spawns (via CreateProcess internally)
+#   automatically, without any extra effort. This is the correct choice for our project.
+
+DEBUG_ONLY_THIS_PROCESS = 0x00000002
+# ↑ Monitors only the launched process. Any child process it spawns runs completely free
+#   without any monitoring or reporting. Only use this if you intentionally want to ignore children.
+
+CREATE_NEW_CONSOLE = 0x00000010
+CREATE_SUSPENDED = 0x00000004
+# ↑ Useful in the future: starts the process "frozen" before executing any instruction, giving you a chance
+#   to set Hardware Breakpoints before anything runs at all.
+
+# ============================================================
+# ContinueDebugEvent — How we respond to each event
+# ============================================================
+
+DBG_CONTINUE = 0x00010002
+# ↑ "Handle this exception as if it didn't happen" — we use this for our own events
+#   (like Single-Step from a Hardware Breakpoint we set).
+
+DBG_EXCEPTION_NOT_HANDLED = 0x80010001
+# ↑ "Pass this exception to the target program's own exception handler"
+#   This is the correct default for any exception we didn't intentionally cause — many Packers
+#   use intentional exceptions as part of their unpacking mechanism, and if you accidentally
+#   reply DBG_CONTINUE, the target program crashes because its internal handler
+#   never received the exception it was expecting.
+
+INFINITE = 0xFFFFFFFF
+
+# ============================================================
+# Debug Event Type Codes (DEBUG_EVENT.dwDebugEventCode)
+# ============================================================
+
+EXCEPTION_DEBUG_EVENT = 1
+CREATE_THREAD_DEBUG_EVENT = 2
+CREATE_PROCESS_DEBUG_EVENT = 3
+EXIT_THREAD_DEBUG_EVENT = 4
+EXIT_PROCESS_DEBUG_EVENT = 5
+LOAD_DLL_DEBUG_EVENT = 6
+UNLOAD_DLL_DEBUG_EVENT = 7
+OUTPUT_DEBUG_STRING_EVENT = 8
+RIP_EVENT = 9
+
+EVENT_CODE_NAMES = {
+    EXCEPTION_DEBUG_EVENT: "EXCEPTION",
+    CREATE_THREAD_DEBUG_EVENT: "CREATE_THREAD",
+    CREATE_PROCESS_DEBUG_EVENT: "CREATE_PROCESS",
+    EXIT_THREAD_DEBUG_EVENT: "EXIT_THREAD",
+    EXIT_PROCESS_DEBUG_EVENT: "EXIT_PROCESS",
+    LOAD_DLL_DEBUG_EVENT: "LOAD_DLL",
+    UNLOAD_DLL_DEBUG_EVENT: "UNLOAD_DLL",
+    OUTPUT_DEBUG_STRING_EVENT: "OUTPUT_DEBUG_STRING",
+    RIP_EVENT: "RIP",
+}
+
+# ============================================================
+# Common Exception Codes (EXCEPTION_RECORD.ExceptionCode)
+# ============================================================
+
+EXCEPTION_BREAKPOINT = 0x80000003
+EXCEPTION_SINGLE_STEP = 0x80000004
+# ↑ We receive this code after any Hardware Breakpoint we set (DR0-DR3) —
+#   important for the future "function tracing" feature.
+EXCEPTION_ACCESS_VIOLATION = 0xC0000005
+
+# ============================================================
+# CONTEXT Flags (x64)
+# ============================================================
+CONTEXT_AMD64 = 0x00100000
+CONTEXT_CONTROL = CONTEXT_AMD64 | 0x00000001
+CONTEXT_INTEGER = CONTEXT_AMD64 | 0x00000002
+CONTEXT_SEGMENTS = CONTEXT_AMD64 | 0x00000004
+CONTEXT_FLOATING_POINT = CONTEXT_AMD64 | 0x00000008
+CONTEXT_DEBUG_REGISTERS = CONTEXT_AMD64 | 0x00000010
+CONTEXT_FULL = CONTEXT_CONTROL | CONTEXT_INTEGER | CONTEXT_FLOATING_POINT
+CONTEXT_ALL = CONTEXT_CONTROL | CONTEXT_INTEGER | CONTEXT_SEGMENTS | CONTEXT_FLOATING_POINT | CONTEXT_DEBUG_REGISTERS
+
+# ============================================================
+# Memory Protections (VirtualQueryEx / VirtualProtect)
+# ============================================================
+
+PAGE_NOACCESS = 0x01
+PAGE_READONLY = 0x02
+PAGE_READWRITE = 0x04
+PAGE_EXECUTE = 0x10
+PAGE_EXECUTE_READ = 0x20
+PAGE_EXECUTE_READWRITE = 0x40
+# ↑ This specific combination (Executable + Writable at the same time) is the most important
+#   "Red Flag" for catching self-unpacking moments — very few legitimate programs
+#   need a page with this combination during normal execution.
+
+MEM_COMMIT = 0x1000
+MEM_FREE = 0x10000
+
+PROTECTIONS_OF_INTEREST = {
+    PAGE_EXECUTE_READWRITE,
+    PAGE_READWRITE,
+    PAGE_EXECUTE_READ,
+}
+
+# ============================================================
+# OpenProcess Access Rights (Used in MEMORY_DUMP mode only — already running process)
+# ============================================================
+
+PROCESS_QUERY_INFORMATION = 0x0400
+PROCESS_VM_READ = 0x0010
+PROCESS_DUMP_ACCESS = PROCESS_QUERY_INFORMATION | PROCESS_VM_READ