RogueByte HARDTRACE

 ██████╗  ██████╗  ██████╗ ██╗   ██╗███████╗██████╗ ██╗   ██╗████████╗███████╗
 ██╔══██╗██╔═══██╗██╔════╝ ██║   ██║██╔════╝██╔══██╗╚██╗ ██╔╝╚══██╔══╝██╔════╝
 ██████╔╝██║   ██║██║  ███╗██║   ██║█████╗  ██████╔╝ ╚████╔╝    ██║   █████╗  
 ██╔══██╗██║   ██║██║   ██║██║   ██║██╔══╝  ██╔══██╗  ╚██╔╝     ██║   ██╔══╝  
 ██║  ██║╚██████╔╝╚██████╔╝╚██████╔╝███████╗██████╔╝   ██║      ██║   ███████╗
 ╚═╝  ╚═╝ ╚═════╝  ╚═════╝  ╚═════╝ ╚══════╝╚═════╝    ╚═╝      ╚═╝   ╚══════╝

Hardware Analysis, Reverse Engineering, Diagnostics & Trace Engine
A professional-grade hardware reverse-engineering and fault-correlation platform by RogueByteOfficial.

---

Project Status: 0.1.0-alpha

Initial functional MVP implementing deterministic FaultLink correlation, ELF32/64 inspection, disassembler, passive UART parsing, cryptographic hash ledger, and investigation reporting.

---

1. Project Identity & Developer Information

• Founder & Lead Developer: Fares Sid Ahmed (Sido) (@RogueByteOfficial)
• Organization: RogueByteOfficial
• Marketing Manager: Adel mouahdi
• Official Website: https://roguebyte.online/
• GitHub Organization: https://github.com/RogueByteOfficial
• Official Contact: contact@roguebyte.online
• Technical Support & Help: help@roguebyte.online
• Business Inquiries: business@roguebyte.online
• Primary License: Apache-2.0

---

2. Problem Statement & Design Goals

Embedded hardware triage is fragmented:

1. Static firmware analysis happens in disassemblers disconnected from physical test benches.
2. Serial console logs (UART) spew register dumps and panics without immediate symbol cross-referencing.
3. Root-cause hypothesis generation is performed by trial-and-error, often risking destructive changes to hardware.

RogueByte HARDTRACE solves this with HARDTRACE FaultLink, a proprietary deterministic correlation engine connecting static firmware symbols, real UART exception telemetry, and hardware state into verified, evidence-backed fault hypotheses.

HARDTRACE does not require a GPU, cloud API, or AI model for its core functionality.

---

3. Implemented Features (Current Release 0.1.0-alpha)

• Firmware Intelligence:
  • File format detection (ELF32, ELF64, Raw Binary, Intel HEX, Motorola SREC, PE).
  • SHA-256, SHA-1, and MD5 cryptographic hashing.
  • Pure-Python ELF parser: program headers, section headers, string tables, and symbol definitions.
  • Spatial Shannon entropy analysis (overall score + 64 uniform spatial visualization blocks).
  • Native instruction disassembler supporting ARM Thumb/Thumb-2, MIPS, and x86 with optional Capstone acceleration.
  • Firmware differential comparison at byte and structural section levels.
• UART & Serial Diagnostics:
  • Host serial port enumeration (/dev/ttyUSB*, /dev/ttyACM*, /dev/ttyS*).
  • Read-only passive UART capture with mandatory explicit user consent gate.
  • Automated boot stage transition detection (ROM_BOOT, STAGE_BOOTLOADER, KERNEL_INIT, USERSPACE_APP).
  • Crash signature and register dump extraction (HardFault, CFSR, HFSR, BFAR, PC, LR, SP, Brownout, Watchdog).
• FaultLink Correlation Engine:
  • Automated spatial mapping of runtime crash Program Counter (PC) and Link Register (LR) against static ELF symbols and sections.
  • Deterministic fault hypothesis ranking with rule-based confidence formulation.
  • Supporting vs Contradicting evidence breakdowns.
  • Actionable next safe diagnostic measurement steps.
• Evidence Integrity & Case Ledger:
  • Append-only SHA-256 hash-chain block ledger.
  • Automated cryptographic ledger audit and tamper detection.
  • SQLite persistence for cases, evidence records, and correlation runs.
• Reporting:
  • Standalone, dark graphite-themed HTML report generator with embedded styles.
  • Structured JSON export format.
• Interfaces:
  • Full CLI (hardtrace --help, version, doctor, firmware ..., serial ..., trace ..., case ..., report ...).
  • Modular PySide6 desktop GUI structure.
  • Full-stack interactive Web UI running in browser on port 3000.

---

4. Explicitly Planned Features (Roadmap)

• Logic analyzer VCD trace ingestion and waveform edge timing correlation.
• SWD / JTAG open-source probe integration (CMSIS-DAP, J-Link via OpenOCD daemon).
• Power rail current measurement correlation via digital multimeter (SCPI over serial).
• Ghidra headless script bridge for advanced decompiled C control-flow graphs.

---

5. Supported Platforms & Interface Compatibility

• Primary Platforms: Linux (Ubuntu 22.04+, Debian 12+, Arch, Fedora) and WSL2 on Windows 11.
• Tested Hardware Interfaces: FTDI FT232R, Silicon Labs CP2102, WCH CH340, USB CDC-ACM.
• Physical Hardware Testing Note: Current release was validated against real ARM Cortex-M4 HardFault dumps, ESP32 brownout logs, and verified synthetic ELF32 binaries. Direct physical serial connections require host USB-to-UART adapters with proper permissions.

---

6. Installation

# Clone repository
git clone https://github.com/RogueByteOfficial/HARDTRACE.git
cd HARDTRACE

# Optional: Set up virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package in editable mode
pip install -e .

To configure UART serial permissions on Linux:

sudo usermod -a -G dialout $USER
newgrp dialout

---

7. CLI Usage Examples

System Diagnostics

hardtrace doctor

Firmware Inspection & Hashing

hardtrace firmware inspect tests/fixtures/sample_arm.elf
hardtrace firmware hash tests/fixtures/sample_arm.elf
hardtrace firmware disassemble tests/fixtures/sample_arm.elf --offset 0x08000100 --count 10

Serial Port Enumeration & Trace Import

hardtrace serial list
hardtrace trace import tests/fixtures/uart_hardfault.log

Case Investigation & Correlation Workflow

# Create investigation case
hardtrace case create --name "Field Device Crash" --device "STM32F4"

# Import evidence into case
hardtrace trace import tests/fixtures/uart_hardfault.log --case-id case_XXXXXXXX

# Run FaultLink correlation
hardtrace case analyze case_XXXXXXXX

# Verify cryptographic ledger
hardtrace case verify case_XXXXXXXX

# Export standalone HTML report
hardtrace report export case_XXXXXXXX --format html --output report.html

---

8. Illustrative Output Sample

Firmware Inspection: sample_arm.elf
  Format:       ELF
  Architecture: ARM_CORTEX
  Endianness:   little
  Size:         579 bytes
  Entry Point:  0x08000100
  Mean Entropy: 3.1604 / 8.0000 (Standard Code/Data)
  SHA-256:      f081b3405e7d34b56ce41fd55128029195b59f53d0445608267bc0eb414970c6

FaultLink Correlation Analysis for case_20261023_a1b2c3:
  Total Events:      14
  Matched Functions: 1 (main at 0x0800010C)
  Leading Diagnosis: 'Firmware Memory Access Violation' with 90% Confidence
  Next Safe Step:    Inspect assembly code at main offset and check caller parameters;
                     attach SWD/JTAG debugger to read CFSR/BFAR registers.

---

9. Automated Testing

Run the test suite:

PYTHONPATH=src python3 -m unittest discover -s tests/unit -v
PYTHONPATH=src python3 -m unittest discover -s tests/security -v
PYTHONPATH=src python3 -m unittest discover -s tests/integration -v

Results: 22 tests executed, 22 passed (0 failures, 0 errors).

---

10. Legal, Safety & Authorized-Use Statement

RogueByte HARDTRACE is designed strictly for authorized hardware diagnostics, embedded security research, and engineering defect analysis.

1. Non-Destructive Operations: HARDTRACE enforces read-only passive monitoring by default and requires explicit user consent before opening host serial devices.
2. Authorized Targets Only: Users must only analyze firmware and hardware devices they own or have explicit authorization to inspect.
3. No Exploitation Payloads: HARDTRACE contains zero weaponized exploits, jailbreaks, or firmware bypass scripts.

---

11. License & Attribution

Licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License in the LICENSE file or at http://www.apache.org/licenses/LICENSE-2.0.

See NOTICE for official RogueByte attribution details and third-party notices.

For contact, licensing, and enterprise inquiries:
RogueByteOfficial · https://roguebyte.online/ · contact@roguebyte.online