BX2trace 1.0.0__tar.gz

bx2trace-1.0.0/BX2trace.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: BX2trace
+Version: 1.0.0
+Summary: bx2trace (TraceBox) — High-performance Stealth Behavioral Analysis Framework for Windows
+Author: FBX2
+License: MIT
+Project-URL: Homepage, https://github.com/fareed1-ataf/Bxtracer
+Project-URL: Repository, https://github.com/fareed1-ataf/Bxtracer.git
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Information Technology
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yara-python>=4.5.0
+Dynamic: license-file
+
+# bx2trace (TraceBox)
+
+**Developed by FBX2**
+
+GitHub Repository: [https://github.com/fareed1-ataf/Bxtracer](https://github.com/fareed1-ataf/Bxtracer)
+
+`bx2trace` is an advanced, high-performance behavioral analysis framework for Windows, specifically designed for
+cybersecurity analysts and malware researchers. It provides deep visibility into process behavior, live memory changes,
+and stealth debugging capabilities.
+
+## Overview
+
+Unlike standard debuggers, `bx2trace` is built for **automated analysis** and **stealth**. It monitors process creation,
+DLL loading, and thread activity while simultaneously scanning live memory for indicators of compromise (IoCs),
+self-unpacking behavior, and encrypted payloads using YARA and entropy analysis.
+
+## Key Features
+
+* **Stealth Engine:** Automatically patches the PEB (Process Environment Block) to clear `BeingDebugged` and
+  `NtGlobalFlag`, effectively evading many anti-debugging tricks used by modern malware.
+* **Hardware Breakpoints (DR0-DR3):** Monitor execution without modifying the target's code, making detection much
+  harder for packers.
+* **Dynamic Memory Scanner:** Periodically scans committed memory regions to detect newly appeared strings and code
+  decryption in real-time.
+* **YARA Integration:** Scan live memory against custom YARA rules to identify specific malware families or behaviors
+  instantly.
+* **Entropy Analysis:** Detect packed or encrypted memory regions by calculating Shannon entropy at the page level.
+* **Child Process Tracking:** Automatically follows process trees to catch "Process Hollowing" and multi-stage
+  execution.
+* **SQLite Storage:** All events are recorded in a structured database for post-mortem analysis and correlation.
+
+## Installation
+
+```bash
+pip install bx2trace
+```
+
+> **Important:** `bx2trace` requires **Administrator privileges** to function correctly as it needs `SeDebugPrivilege` to
+> monitor other processes.
+
+## Requirements
+
+* Windows 10/11 (x64)
+* Python 3.11+
+* Administrator rights
+
+---
+
+## Usage Guide
+
+The `bx2trace` package is a library. While it includes internal components to build complex analysis engines, most users
+will interact with the high-level components or build their own tools using the provided modules.
+
+### Python API Usage
+
+Analysts can build their own custom analysis tools by leveraging the core components of `bx2trace`.
+
+#### 1. Basic Process Monitoring
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.models import TraceMode
+
+# Event queue for collecting data
+event_queue = Queue()
+
+# Initialize and start the debugger thread
+debug_thread = DebugThread(
+    exe_path="malware.exe",
+    mode=TraceMode.FULL_TRACE,
+    raw_event_queue=event_queue
+)
+debug_thread.start()
+
+try:
+    while debug_thread.is_alive():
+        event = event_queue.get()
+        print(f"[{event.severity.value}] {event.category}/{event.action}: {event.payload}")
+except KeyboardInterrupt:
+    debug_thread.request_stop()
+```
+
+#### 2. Advanced Memory Scanning with YARA
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.memory_scanner import MemoryScannerThread
+from bx2trace.core.models import TraceMode
+
+event_queue = Queue()
+
+debug_thread = DebugThread("malware.exe", TraceMode.FULL_TRACE, event_queue)
+debug_thread.start()
+debug_thread.started_ok.wait()  # Wait for the process to launch
+
+# Setup scanner to read tracked handles from DebugThread
+scanner = MemoryScannerThread(
+    get_tracked_handles=lambda: {p.pid: p.handle for p in debug_thread.tracked.values()},
+    event_queue=event_queue,
+    interval=2.0,
+    yara_rules_path="rules.yar"
+)
+scanner.start()
+```
+
+### Building Custom Detectors
+
+You can extend the framework by creating custom detection logic that consumes events from the `event_queue`. This allows
+you to implement specialized behavioral rules (e.g., detecting specific API call sequences or network patterns).
+
+---
+
+## Technical Assessment
+
+### Strengths
+
+1. **Architecture:** Decoupled design using a thread-safe event queue allows adding new detection modules (Detectors)
+   without touching the core engine.
+2. **Performance:** Memory scanning is optimized with shared buffers and batch SQLite writes to ensure minimal impact on
+   the host system.
+3. **Accuracy:** Correlating high-entropy memory regions with the appearance of new strings provides a high-confidence
+   signal for self-unpacking.
+
+### Potential Weaknesses
+
+1. **Polling Latency:** Very fast fileless malware might execute between scan intervals. (Planned: Event-driven scanning
+   via API hooks).
+2. **Architecture Mismatch:** Currently focused on x64 targets; 32-bit (WOW64) support is limited.
+
+## Disclaimer
+
+This tool is intended for educational and research purposes only. The authors are not responsible for any misuse or
+damage caused by this software. Use it only on systems you own or have explicit permission to analyze.
+
+---
+**Developed for Security Engineers who need precision and stealth.**

bx2trace-1.0.0/BX2trace.egg-info/SOURCES.txt

@@ -0,0 +1,41 @@
+LICENSE
+README.md
+pyproject.toml
+./bx2trace/__init__.py
+./bx2trace/core/__init__.py
+./bx2trace/core/api_hooker.py
+./bx2trace/core/constants.py
+./bx2trace/core/debug_thread.py
+./bx2trace/core/memory_scanner.py
+./bx2trace/core/models.py
+./bx2trace/core/process_launcher.py
+./bx2trace/core/win_structs.py
+./bx2trace/extractors/__init__.py
+./bx2trace/extractors/entropy.py
+./bx2trace/extractors/strings.py
+./bx2trace/memory/__init__.py
+./bx2trace/memory/reader.py
+BX2trace.egg-info/PKG-INFO
+BX2trace.egg-info/SOURCES.txt
+BX2trace.egg-info/dependency_links.txt
+BX2trace.egg-info/requires.txt
+BX2trace.egg-info/top_level.txt
+bx2trace/__init__.py
+bx2trace.egg-info/PKG-INFO
+bx2trace.egg-info/SOURCES.txt
+bx2trace.egg-info/dependency_links.txt
+bx2trace.egg-info/requires.txt
+bx2trace.egg-info/top_level.txt
+bx2trace/core/__init__.py
+bx2trace/core/api_hooker.py
+bx2trace/core/constants.py
+bx2trace/core/debug_thread.py
+bx2trace/core/memory_scanner.py
+bx2trace/core/models.py
+bx2trace/core/process_launcher.py
+bx2trace/core/win_structs.py
+bx2trace/extractors/__init__.py
+bx2trace/extractors/entropy.py
+bx2trace/extractors/strings.py
+bx2trace/memory/__init__.py
+bx2trace/memory/reader.py

bx2trace-1.0.0/BX2trace.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bx2trace-1.0.0/BX2trace.egg-info/requires.txt

@@ -0,0 +1 @@
+yara-python>=4.5.0

bx2trace-1.0.0/BX2trace.egg-info/top_level.txt

@@ -0,0 +1 @@
+bx2trace

bx2trace-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FBX2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bx2trace-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: BX2trace
+Version: 1.0.0
+Summary: bx2trace (TraceBox) — High-performance Stealth Behavioral Analysis Framework for Windows
+Author: FBX2
+License: MIT
+Project-URL: Homepage, https://github.com/fareed1-ataf/Bxtracer
+Project-URL: Repository, https://github.com/fareed1-ataf/Bxtracer.git
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Information Technology
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yara-python>=4.5.0
+Dynamic: license-file
+
+# bx2trace (TraceBox)
+
+**Developed by FBX2**
+
+GitHub Repository: [https://github.com/fareed1-ataf/Bxtracer](https://github.com/fareed1-ataf/Bxtracer)
+
+`bx2trace` is an advanced, high-performance behavioral analysis framework for Windows, specifically designed for
+cybersecurity analysts and malware researchers. It provides deep visibility into process behavior, live memory changes,
+and stealth debugging capabilities.
+
+## Overview
+
+Unlike standard debuggers, `bx2trace` is built for **automated analysis** and **stealth**. It monitors process creation,
+DLL loading, and thread activity while simultaneously scanning live memory for indicators of compromise (IoCs),
+self-unpacking behavior, and encrypted payloads using YARA and entropy analysis.
+
+## Key Features
+
+* **Stealth Engine:** Automatically patches the PEB (Process Environment Block) to clear `BeingDebugged` and
+  `NtGlobalFlag`, effectively evading many anti-debugging tricks used by modern malware.
+* **Hardware Breakpoints (DR0-DR3):** Monitor execution without modifying the target's code, making detection much
+  harder for packers.
+* **Dynamic Memory Scanner:** Periodically scans committed memory regions to detect newly appeared strings and code
+  decryption in real-time.
+* **YARA Integration:** Scan live memory against custom YARA rules to identify specific malware families or behaviors
+  instantly.
+* **Entropy Analysis:** Detect packed or encrypted memory regions by calculating Shannon entropy at the page level.
+* **Child Process Tracking:** Automatically follows process trees to catch "Process Hollowing" and multi-stage
+  execution.
+* **SQLite Storage:** All events are recorded in a structured database for post-mortem analysis and correlation.
+
+## Installation
+
+```bash
+pip install bx2trace
+```
+
+> **Important:** `bx2trace` requires **Administrator privileges** to function correctly as it needs `SeDebugPrivilege` to
+> monitor other processes.
+
+## Requirements
+
+* Windows 10/11 (x64)
+* Python 3.11+
+* Administrator rights
+
+---
+
+## Usage Guide
+
+The `bx2trace` package is a library. While it includes internal components to build complex analysis engines, most users
+will interact with the high-level components or build their own tools using the provided modules.
+
+### Python API Usage
+
+Analysts can build their own custom analysis tools by leveraging the core components of `bx2trace`.
+
+#### 1. Basic Process Monitoring
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.models import TraceMode
+
+# Event queue for collecting data
+event_queue = Queue()
+
+# Initialize and start the debugger thread
+debug_thread = DebugThread(
+    exe_path="malware.exe",
+    mode=TraceMode.FULL_TRACE,
+    raw_event_queue=event_queue
+)
+debug_thread.start()
+
+try:
+    while debug_thread.is_alive():
+        event = event_queue.get()
+        print(f"[{event.severity.value}] {event.category}/{event.action}: {event.payload}")
+except KeyboardInterrupt:
+    debug_thread.request_stop()
+```
+
+#### 2. Advanced Memory Scanning with YARA
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.memory_scanner import MemoryScannerThread
+from bx2trace.core.models import TraceMode
+
+event_queue = Queue()
+
+debug_thread = DebugThread("malware.exe", TraceMode.FULL_TRACE, event_queue)
+debug_thread.start()
+debug_thread.started_ok.wait()  # Wait for the process to launch
+
+# Setup scanner to read tracked handles from DebugThread
+scanner = MemoryScannerThread(
+    get_tracked_handles=lambda: {p.pid: p.handle for p in debug_thread.tracked.values()},
+    event_queue=event_queue,
+    interval=2.0,
+    yara_rules_path="rules.yar"
+)
+scanner.start()
+```
+
+### Building Custom Detectors
+
+You can extend the framework by creating custom detection logic that consumes events from the `event_queue`. This allows
+you to implement specialized behavioral rules (e.g., detecting specific API call sequences or network patterns).
+
+---
+
+## Technical Assessment
+
+### Strengths
+
+1. **Architecture:** Decoupled design using a thread-safe event queue allows adding new detection modules (Detectors)
+   without touching the core engine.
+2. **Performance:** Memory scanning is optimized with shared buffers and batch SQLite writes to ensure minimal impact on
+   the host system.
+3. **Accuracy:** Correlating high-entropy memory regions with the appearance of new strings provides a high-confidence
+   signal for self-unpacking.
+
+### Potential Weaknesses
+
+1. **Polling Latency:** Very fast fileless malware might execute between scan intervals. (Planned: Event-driven scanning
+   via API hooks).
+2. **Architecture Mismatch:** Currently focused on x64 targets; 32-bit (WOW64) support is limited.
+
+## Disclaimer
+
+This tool is intended for educational and research purposes only. The authors are not responsible for any misuse or
+damage caused by this software. Use it only on systems you own or have explicit permission to analyze.
+
+---
+**Developed for Security Engineers who need precision and stealth.**

bx2trace-1.0.0/README.md

@@ -0,0 +1,138 @@
+# bx2trace (TraceBox)
+
+**Developed by FBX2**
+
+GitHub Repository: [https://github.com/fareed1-ataf/Bxtracer](https://github.com/fareed1-ataf/Bxtracer)
+
+`bx2trace` is an advanced, high-performance behavioral analysis framework for Windows, specifically designed for
+cybersecurity analysts and malware researchers. It provides deep visibility into process behavior, live memory changes,
+and stealth debugging capabilities.
+
+## Overview
+
+Unlike standard debuggers, `bx2trace` is built for **automated analysis** and **stealth**. It monitors process creation,
+DLL loading, and thread activity while simultaneously scanning live memory for indicators of compromise (IoCs),
+self-unpacking behavior, and encrypted payloads using YARA and entropy analysis.
+
+## Key Features
+
+* **Stealth Engine:** Automatically patches the PEB (Process Environment Block) to clear `BeingDebugged` and
+  `NtGlobalFlag`, effectively evading many anti-debugging tricks used by modern malware.
+* **Hardware Breakpoints (DR0-DR3):** Monitor execution without modifying the target's code, making detection much
+  harder for packers.
+* **Dynamic Memory Scanner:** Periodically scans committed memory regions to detect newly appeared strings and code
+  decryption in real-time.
+* **YARA Integration:** Scan live memory against custom YARA rules to identify specific malware families or behaviors
+  instantly.
+* **Entropy Analysis:** Detect packed or encrypted memory regions by calculating Shannon entropy at the page level.
+* **Child Process Tracking:** Automatically follows process trees to catch "Process Hollowing" and multi-stage
+  execution.
+* **SQLite Storage:** All events are recorded in a structured database for post-mortem analysis and correlation.
+
+## Installation
+
+```bash
+pip install bx2trace
+```
+
+> **Important:** `bx2trace` requires **Administrator privileges** to function correctly as it needs `SeDebugPrivilege` to
+> monitor other processes.
+
+## Requirements
+
+* Windows 10/11 (x64)
+* Python 3.11+
+* Administrator rights
+
+---
+
+## Usage Guide
+
+The `bx2trace` package is a library. While it includes internal components to build complex analysis engines, most users
+will interact with the high-level components or build their own tools using the provided modules.
+
+### Python API Usage
+
+Analysts can build their own custom analysis tools by leveraging the core components of `bx2trace`.
+
+#### 1. Basic Process Monitoring
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.models import TraceMode
+
+# Event queue for collecting data
+event_queue = Queue()
+
+# Initialize and start the debugger thread
+debug_thread = DebugThread(
+    exe_path="malware.exe",
+    mode=TraceMode.FULL_TRACE,
+    raw_event_queue=event_queue
+)
+debug_thread.start()
+
+try:
+    while debug_thread.is_alive():
+        event = event_queue.get()
+        print(f"[{event.severity.value}] {event.category}/{event.action}: {event.payload}")
+except KeyboardInterrupt:
+    debug_thread.request_stop()
+```
+
+#### 2. Advanced Memory Scanning with YARA
+
+```python
+from queue import Queue
+from bx2trace.core.debug_thread import DebugThread
+from bx2trace.core.memory_scanner import MemoryScannerThread
+from bx2trace.core.models import TraceMode
+
+event_queue = Queue()
+
+debug_thread = DebugThread("malware.exe", TraceMode.FULL_TRACE, event_queue)
+debug_thread.start()
+debug_thread.started_ok.wait()  # Wait for the process to launch
+
+# Setup scanner to read tracked handles from DebugThread
+scanner = MemoryScannerThread(
+    get_tracked_handles=lambda: {p.pid: p.handle for p in debug_thread.tracked.values()},
+    event_queue=event_queue,
+    interval=2.0,
+    yara_rules_path="rules.yar"
+)
+scanner.start()
+```
+
+### Building Custom Detectors
+
+You can extend the framework by creating custom detection logic that consumes events from the `event_queue`. This allows
+you to implement specialized behavioral rules (e.g., detecting specific API call sequences or network patterns).
+
+---
+
+## Technical Assessment
+
+### Strengths
+
+1. **Architecture:** Decoupled design using a thread-safe event queue allows adding new detection modules (Detectors)
+   without touching the core engine.
+2. **Performance:** Memory scanning is optimized with shared buffers and batch SQLite writes to ensure minimal impact on
+   the host system.
+3. **Accuracy:** Correlating high-entropy memory regions with the appearance of new strings provides a high-confidence
+   signal for self-unpacking.
+
+### Potential Weaknesses
+
+1. **Polling Latency:** Very fast fileless malware might execute between scan intervals. (Planned: Event-driven scanning
+   via API hooks).
+2. **Architecture Mismatch:** Currently focused on x64 targets; 32-bit (WOW64) support is limited.
+
+## Disclaimer
+
+This tool is intended for educational and research purposes only. The authors are not responsible for any misuse or
+damage caused by this software. Use it only on systems you own or have explicit permission to analyze.
+
+---
+**Developed for Security Engineers who need precision and stealth.**

bx2trace-1.0.0/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",
+]