fdebug - User-Mode Anti-Debug and Integrity Protection Engine

Overview

fdebug (Cargo package fuckDebug v0.2.4) is a user-mode software protection and integrity verification framework engineered for 64-bit Windows environments (x86_64-pc-windows-msvc and x86_64-pc-windows-gnu). The framework implements defensive mechanisms across five concentric architectural layers, combining hardware-anchored entropy derivation, sharded PE image integrity verification, low-level exception handling (VEH), indirect system call dispatching, bytecode virtualization via TinyVM 2.0, and a decentralized atomic suspicion state machine.

Rather than halting process execution with an abrupt crash or error dialogue when analysis tools are detected, fdebug employs a fail-poison architecture: detection events silently perturb internal transformation keys, execution tokens, and dynamic cryptographic seeds. Application execution continues, but downstream operations mathematically coupled to these tokens yield corrupted, unusable outputs without exposing discrete failure boundaries.

---

Crate Identity and Cargo Import

Package Identity

• Cargo Package Name: fuckDebug
• Current Version: 0.2.4
• Target Platform: Windows x86_64 (x86_64-pc-windows-msvc, x86_64-pc-windows-gnu)
• Edition: Rust 2021

NOTE: The Rust compiler issues a non-fatal naming convention warning during compilation (warning: crate fuckDebug should have a snake case name) due to the mixed-case identifier declared in Cargo.toml.

Direct Import

To reference the crate under its canonical package name:

# Cargo.toml
[dependencies]
fuckDebug = "0.2.4"

use fuckDebug::protector::{
    init_protector,
    setup_anti_debug,
    get_dynamic_seed,
    get_suspicion_score,
    Protector,
    SecureVault,
    ShieldedExecution,
};
use fuckDebug::guarded_value;

Package Aliasing (Recommended)

To reference the crate using standard lowercase conventions:

# Cargo.toml
[dependencies]
fdebug = { package = "fuckDebug", version = "0.2.4" }

use fdebug::protector::{
    init_protector,
    setup_anti_debug,
    get_dynamic_seed,
    get_suspicion_score,
    Protector,
    SecureVault,
    ShieldedExecution,
};
use fdebug::guarded_value;

---

Protection Philosophy: Fail-Poison Paradigm

Traditional anti-debugging mechanisms rely on a fail-stop architecture: once a debugger, hook, or environment modification is detected, the process terminates immediately via ExitProcess, abort(), or an intentional crash. This design exposes distinct control-flow patch points: an analyst can trace execution backward from the termination instruction, locate the conditional branch (test/cmp followed by jz/jnz), and invert or replace it with NOP instructions to permanently disable the check.

fdebug adopts a fail-poison paradigm:

Traditional Fail-Stop Model:
  Detection Event ---> ExitProcess / Crash ---> Clear Patch Point for Reverse Engineers

fdebug Fail-Poison Model:
  Detection Event ---> Silent Key Mutation ---> Downstream Operations Produce Corrupted Results
                                           ---> No Immediate Termination or Crash
                                           ---> Reverse Engineer Cannot Locate Decision Boundary

When a sensor detects analysis artifacts:

1. Silent State Accumulation: Detection points are dispersed across 128 atomic shards (64 active, 64 decoy) and an irreversible MSB poison latch is set.
2. Key Corruption: Cryptographic tokens, dynamic seeds, and virtual machine keys (POISON_SEED, GLOBAL_ENCRYPTION_KEY, GLOBAL_VIRTUAL_MACHINE_KEY) are mutated using non-involutory transformations.
3. Mathematical Coupling: Downstream business logic, decryptors, and memory vaults derive intermediate results from these tokens. Execution proceeds normally, but produces invalid calculations, garbled strings, or corrupted records, preventing dynamic analysts from isolating the detection trigger through control-flow tracing.

---

Five-Layer Concentric Architecture

The defense engine is structured into five concentric operational layers. Higher layers rely functionally and cryptographically on the invariants enforced by lower layers.

+-----------------------------------------------------------------------------------+
| Layer 5: Distributed Global State & Silent Corruption                             |
|   - 128 Atomic Shards (64 Active / 64 Decoy) with XOR Masking & Decoupled Rotation|
|   - Dynamic 64-Bit Pair Map Evolution & SipHash-2-4 Cryptographic Integrity       |
|   - Bounded Decoy Noise, Dispersed Scattering & Irreversible MSB Poison Latch     |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Layer 4: Polymorphic Virtual Execution (TinyVM 2.0)                               |
|   - 256-Entry Indirect Threading Function Pointer Dispatch Table                  |
|   - Dynamic Logic-to-Physical (LTP) Permutation with Poison-Reactive Chaos Trap   |
|   - Rolling-Key Stream Cipher with Salt & Anti-Trace Cycle Watchdog               |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Layer 3: Memory Stealth, Master VEH & Indirect Syscalls                           |
|   - 5-Phase Master Vectored Exception Handler (VEH) with 1232-Byte CONTEXT ABI    |
|   - TEB Stack Bounds Validation (gs:[0x08]/0x10) & RtlVirtualUnwind Walking       |
|   - Lock-Free Decoy Guard Pages (PAGE_GUARD) & Indirect Syscalls (0x40 Stack)     |
|   - Lock-Free KUSER_SHARED_DATA Tick Counter Watchdog                             |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Layer 2: Seed Orchestration & Bijective Key Derivation                            |
|   - Asymmetric 3-Pipeline ARX Shard Recomposition: (s1 ^ s2).wrapping_add(s3)     |
|   - Pure Bijective KDF (fmix32) with Golden Ratio Offset (Eliminates f(0) = 0)    |
|   - 4-Stage Non-Linear u8 Projection (Strict Avalanche Criterion, H ~ 7.998 bits) |
|   - Lock-Free Atomic Cache with Monotonic Reseeding Epochs                        |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Layer 1: Hardware & PE Anchoring                                                  |
|   - CPUID Processor Feature Fingerprinting (Leaves 0, 1, 0x80000000..0x80000004)  |
|   - Serialized RDTSC Timing Fallback with Monotonic Forward Progression           |
|   - Sharded PE .text Section Checksumming (1KB Blocks, .text$AAA Inert Anchor)    |
|   - Early-Bird TLS Callback Execution (.CRT$XLB) Prior to Application Entry Point |
+-----------------------------------------------------------------------------------+

Layer Summary

• Layer 1: Hardware & PE Anchoring (hardware_entropy.rs, pe_integrity.rs, anti_debug.rs, build.rs) Derives execution entropy directly from hardware CPUID leaves and serialized RDTSC counters. Validates PE image integrity by dividing the .text section into 1KB blocks, computing sharded checksums verified against compile-time anchors. Hooks early process initialization via a dedicated TLS callback in the .CRT$XLB section to sample debug registers (Dr0 to Dr7) and PEB flags (BeingDebugged, NtGlobalFlag) before main() executes.

• Layer 2: Seed Orchestration & Bijective Key Derivation (seed_orchestrator.rs) Recomposes entropy shards through an asymmetric 3-pipeline ARX function (s1 ^ s2).wrapping_add(s3) designed to break linear XOR cancellation (Delta ^ Delta = 0). Feeds recomposed state into a pure bijective KDF (fmix32 with a golden ratio offset 0x9E3779B9) that eliminates zero fixed points (f(0) != 0). Projects 32-bit seeds into 8-bit virtual machine keys via a 4-stage non-linear ARX transformation satisfying the Strict Avalanche Criterion (SAC) with Shannon entropy $H \approx 7.998$ bits.

• Layer 3: Memory Stealth, Master VEH & Indirect Syscalls (anti_dump.rs, enhanced_veh.rs, decoy_system.rs) Installs a first-priority Vectored Exception Handler (AddVectoredExceptionHandler(1, ...)) implementing a 5-phase dispatch pipeline. Validates stack integrity against Thread Environment Block (TEB) limits (gs:[0x08] / gs:[0x10]) and requires at least two valid frames via RtlVirtualUnwind. Deploys lock-free decoy memory regions configured with PAGE_GUARD to trap memory dumpers. Executes memory protection transitions (NtProtectVirtualMemory) through indirect system calls with a 64-byte 16-byte aligned stack reservation. Employs a lock-free liveness watchdog reading KUSER_SHARED_DATA interrupt ticks to detect thread suspension.

• Layer 4: Polymorphic Virtual Execution (TinyVM 2.0) (tiny_vm.rs) Executes sensitive bytecode sequences without conditional branching statements via a 256-entry indirect function pointer dispatch table. Maps logical opcodes to physical handlers using a Fisher-Yates shuffled Logic-to-Physical (LTP) map. If execution state is corrupted or an unknown opcode is encountered, the VM diverts to a Chaos Trap that synthesizes degraded outputs. Employs a rolling-key XOR stream cipher with position-dependent salting and enforces an anti-trace cycle watchdog (ANTI_TRACE_CYCLE_THRESHOLD = 2_000_000) to detect single-stepping.

• Layer 5: Distributed Global State & Silent Corruption (global_state.rs) Stores threat telemetry across 128 atomic shards (AtomicU32) divided into 64 active shards and 64 decoy shards. Partitions shards dynamically using a 64-bit pair map derived from runtime entropy and a monotonic threat counter. Masks values via rotational shifts and random bitmasks, ensuring that an attacker zeroing process memory triggers an aggregate score exceeding 500, tripping a honeytrap score of 0xFFFFFFFF. Serializes state integrity via SipHash-2-4 hashing with spin-wait CAS synchronization and latches poisoning irreversibly via an MSB bitwise OR.

---

Quickstart Guide

1. Configure Dependencies

Configure Cargo.toml with the package alias:

[dependencies]
fdebug = { package = "fuckDebug", version = "0.2.4" }

2. Implementation Example

The following example demonstrates initializing the protection engine, storing sensitive values inside a memory vault, executing coupled transformations, and querying the atmospheric suspicion score:

use fdebug::protector::{
    init_protector,
    setup_anti_debug,
    get_dynamic_seed,
    get_suspicion_score,
    Protector,
    SecureVault,
};
use fdebug::guarded_value;

fn main() {
    // Step 1: Initialize the protection runtime.
    // setup_anti_debug! executes init_protector() (arming VEH, decoy traps,
    // and anti-dump routines) and constructs a Protector bound to dynamic entropy.
    let seed = get_dynamic_seed();
    let protector = setup_anti_debug!(seed);

    println!("[*] fdebug protection engine active (seed: 0x{:08X})", seed);

    // Step 2: Encapsulate sensitive credentials inside a SecureVault.
    // Vault contents cannot be read directly; access requires providing a reference
    // to the active Protector and an execution closure receiving the dynamic key.
    let api_key = SecureVault::new(0xABCD_1234_u32);

    api_key.unlock(&protector, |raw_val, key| {
        // If an analysis tool or debugger is present, 'key' is mutated into an
        // invalid token, causing derived computations to silently fail downstream.
        let derived_token = (*raw_val as u64).wrapping_add(key);
        println!("    Derived security token: 0x{:016X}", derived_token);
    });

    // Step 3: Inline value protection via guarded_value! macro.
    // Expands to an enclosed SecureVault transaction returning (val, key).
    let (data, key) = guarded_value!(1337u64, protector);
    let final_result = data ^ key;
    println!("    Guarded expression result: 0x{:X}", final_result);

    // Step 4: Inspect process suspicion score.
    // Evaluates aggregated threat telemetry across the 128 atomic shards.
    let score = get_suspicion_score();
    println!("[*] Current atmospheric suspicion score: {}", score);

    if score >= 100 {
        println!("[!] Detection threshold reached -- execution poisoned.");
    } else {
        println!("[+] Operational environment normal.");
    }
}

---

Concurrency and Test Execution Constraints

WARNING: All test suites, integration harnesses, and examples that initialize or evaluate fdebug MUST be executed in single-threaded test runners:

cargo test -- --test-threads=1

Or for the verification harness:

cargo test --manifest-path verification_suite/Cargo.toml --lib -- --test-threads=1

Alternatively, configure the environment variable:

$env:RUST_TEST_THREADS="1"
cargo test

Technical Rationale

The protection engine relies on process-wide, mutable atomic singletons and global synchronization structures:

• POISON_SEED: Global atomic seed mutated upon threat detection.
• GLOBAL_STATE_INITIALIZED: Guard flag for the 128-shard suspicion table.
• SUSPICION_SHARDS: 128 atomic integers (AtomicU32) shared across the entire address space.
• INTEGRITY_LOCK: Global spin-wait CAS lock serializing SipHash-2-4 checksum calculation.
• DECOY_REGIONS: Global array of 8 atomic decoy memory slots registered with PAGE_GUARD.

When cargo tests run in default parallel mode (multi-threaded), multiple test functions concurrently access, reset, and mutate these global atomics. This causes cross-test race conditions, torn SipHash validations, and false-positive threat score accumulations, resulting in spurious test failures. Single-threaded execution (--test-threads=1) ensures deterministic test isolation.

---

Threat Model and Operational Boundaries

Capabilities and Mitigations

fdebug provides user-mode anti-analysis defenses designed to resist:

• User-mode software debuggers (WinDbg user-mode, x64dbg, Visual Studio Debugger, IDA Pro debugger).
• Automated disassembly and static extraction tools (IDA Pro, Ghidra, Binary Ninja) through TinyVM bytecode virtualization and instruction obfuscation.
• PE image patching and code injection (checksum verification across 1KB .text sections).
• User-mode API detours and inline hooking (prologue validation, indirect system calls for virtual memory protection).
• Standard memory dumping utilities (Scylla, Dump-It, ProcDump) via decoy guard pages and user-mode PE header erasure.
• Memory zeroing or tampering with suspicion state (128-shard active/decoy rotation and dynamic SipHash integrity verification).
• Interactive single-stepping and instruction tracing via anti-trace cycle watchdogs and serialized RDTSC timing checks.

Operational Boundaries and Limitations

fdebug operates strictly in user mode (Ring 3) on Windows x86_64. The following threat vectors reside outside the operational boundary of the framework:

1. Kernel-Mode Debugging and Rootkits (Ring 0): Kernel drivers, kernel debuggers (e.g., WinDbg via KDNET), and rootkits operate with supervisor privileges. A kernel debugger can directly read or alter user-mode physical memory, manipulate page tables, or suppress exception delivery without triggering user-mode VEH handlers or PEB inspections.

2. Hardware-Assisted Hypervisors (Ring -1): Virtual machine monitors (VMMs) utilizing Intel VT-x or AMD-V can intercept execution through Extended Page Tables (EPT) and VM-Exit events. A hypervisor can transparently single-step or freeze execution and forge timing counters, bypassing user-mode RDTSC checks.

3. Direct Memory Access (DMA) Attacks: Hardware devices capable of bus-mastering DMA over PCIe or Thunderbolt can directly read system memory without CPU intervention, bypassing all software-level integrity checks.

4. Virtualization Timing Jitter: On virtualized cloud infrastructure, heavily loaded hosts, or nested VMs, CPU scheduling jitter and hypervisor exits can cause RDTSC timing checks to exceed calibrated thresholds, leading to potential false-positive suspicion accumulation. Applications deployed in high-jitter environments should evaluate timing sensitivity accordingly.

5. Clean-Run Signature Dynamics: The internal routine verify_stealth_state() validates that memory stealth has erased the NT PE signature. On environments where header erasure is constrained by operating system policies or unwind table dependencies, this check may flag pristine runs as suspicious. Refer to the Architecture Specification for details.

---

Documentation Index

The fdebug documentation suite is organized into five modular technical specifications under the docs/ directory:

Document	Primary Scope
Architecture Specification	Exhaustive 5-layer concentric model specification, mathematical derivations, memory layouts (1232-byte CONTEXT, 128 shards), and operational invariants.
API Reference	Authoritative reference for all public Rust exports, including Protector, SecureVault, ShieldedExecution, setup_anti_debug!, and guarded_value!.
Integration Guide	Architectural design patterns (Shield, Sentinel, Checksum), real-world implementation samples, and VM opcode extension guidance.
Build Guide	Build script customization (build.rs), build-time entropy injection (FDEBUG_BUILD_SECRET), toolchain prerequisites, and compilation profiles.
Formal Verification	Mathematical proof framework, Verus deductive SMT theorems, Bolero property fuzzing harnesses, and historical defect remediation ledger.

---

Repository Structure

fdebug/
|-- Cargo.toml                    # Crate definition (fuckDebug v0.2.4)
|-- build.rs                      # Build-time random seed derivation (Shard 1)
|-- src/
|   |-- lib.rs                    # Library root export (pub mod protector)
|   |-- main.rs                   # Entry point demonstration binary
|   `-- protector/
|       |-- mod.rs                # Protector, SecureVault, CoupledLogic abstractions
|       |-- seed_orchestrator.rs  # Layer 2: 3-pipeline ARX & pure bijective KDF
|       |-- hardware_entropy.rs   # Layer 1: CPUID hardware fingerprinting & RDTSC
|       |-- pe_integrity.rs       # Layer 1: Sharded PE section checksumming
|       |-- anti_debug.rs         # Layer 1/3: Multi-vector sensors & TLS callback
|       |-- anti_dump.rs          # Layer 3: Decoy guard pages & indirect syscalls
|       |-- enhanced_veh.rs       # Layer 3: 5-phase master VEH & stack unwinding
|       |-- tiny_vm.rs            # Layer 4: Indirect-threaded virtual machine 2.0
|       |-- global_state.rs       # Layer 5: 128-shard active/decoy suspicion state
|       `-- decoy_system.rs       # Layer 3: Honeypot functions & canary prologues
|-- docs/                         # Canonical technical documentation suite
|   |-- architecture.md           # Concentric 5-layer architectural specification
|   |-- api_reference.md          # Public API, trait, struct, and macro catalogue
|   |-- integration_guide.md      # Integration patterns and practical implementation
|   |-- build_guide.md            # Build system prerequisites and entropy customization
|   `-- formal_verification.md    # Formal SMT proofs, fuzzing, and defect ledger
|-- examples/                     # Practical integration examples
|   |-- basic_protection.rs       # Basic initialization and status inspection
|   |-- guarded_logic.rs          # Corruptible financial calculation pattern
|   |-- stealth_system.rs         # Memory stealth and indirect syscall sample
|   `-- custom_vm_op.rs           # VM opcode extension design notes
`-- verification_suite/           # Standalone verification and test harnesses
    |-- Cargo.toml                # Verification crate dependencies
    |-- run_verification.ps1      # PowerShell verification execution script
    |-- run_verification.bat      # Windows batch verification script
    |-- src/                      # Verus deductive proofs and Bolero harnesses
    `-- tests/                    # Integration test binaries and defect regressions

---

License

This project is licensed under the MIT License. See LICENSE for details.