# carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack architecture

> Architecture diagram of the GitHub repository carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack
- Repository: https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack

## Overview

##### Project type and purpose
- Project type: A single-executable Windows command-line security tool written in native C++/Win32.
- Purpose: Demonstrates a novel “Process Hypnosis” technique—using the Windows debugging APIs to hijack a target process’s control flow and inject code without classic APIs like VirtualAllocEx or CreateRemoteThread.

##### File structure
- Top-level files:
– ProcessHypnosis.sln (Visual Studio solution)
– README.md (explanation of attack technique)
- Project folder ProcessHypnosis/ProcessHypnosis:
– ProcessHypnosis.cpp (all core logic lives here)
– ProcessHypnosis.vcxproj* (build configuration)
– x64/Debug output folder with built executable, logs, symbol PDBs
- No separate frontend/backend; no external service components—just one native process.

##### Key insights from the README
- Core components it interacts with:
– Windows Debugging API (CreateProcessW with DEBUG_ONLY_THIS_PROCESS, WaitForDebugEvent, DebugActiveProcessStop)
– Kernel functions under the hood (PsFreezeProcess/PsThawProcess via NtSetInformationJobObject)
– Memory-write routines (WriteProcessMemory internally calls NtProtectVirtualMemory)
– Symbol lookup APIs (SymFromName)
- Sequence of operations:
1. Spawn target in debug-only mode
2. Handle debug events (CREATE_PROCESS, LOAD_DLL, CREATE_THREAD)
3. Patch target’s entry point via WriteProcessMemory
4. Detach debugger to unfreeze and resume target

##### Detail but avoid overcomplication
- Break the attacker tool into as many logical subcomponents as it helps clarity.
- Frozen/unfrozen state transitions of the target’s main thread around the DebugActiveProcessStop call.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Attacker Process and Modules
    subgraph "Attacker Process" 
        direction TB
        AP["ProcessHypnosis.exe\n(Attacker Process)"]:::usermode
        subgraph "Modules"
            direction TB
            L["Launcher\n(CreateProcessW)"]:::usermode
            E["Event Loop\n(WaitForDebugEvent)"]:::usermode
            I["Injector\n(WriteProcessMemory)"]:::usermode
            D["Detacher\n(DebugActiveProcessStop)"]:::usermode
        end
    end

    %% OS / Kernel
    OS["OS/Kernel\n(Freezes/Unfreezes Threads,\nDelivers Debug Events)"]:::kernel

    %% Target Process
    TP["Target Process\n(Frozen Thread, Entry Point)"]:::usermode

    %% Symbol Resolution
    DBG["Symbol Resolution\n(SymFromName)"]:::side

    %% Project Artifacts
    subgraph "Project Artifacts"
        direction TB
        SLN["ProcessHypnosis.sln"]:::artifact
        VCX["ProcessHypnosis.vcxproj"]:::artifact
        FIL["ProcessHypnosis.vcxproj.filters"]:::artifact
        USR["ProcessHypnosis.vcxproj.user"]:::artifact
        CPP["ProcessHypnosis.cpp"]:::artifact
        DBGF["x64/Debug/"]:::artifact
        RMD["README.md"]:::artifact
    end

    %% Connections
    AP -->|"1. CreateProcessW(DEBUG_ONLY_THIS_PROCESS)"| OS
    OS -->|"2. Debug Event (CREATE_PROCESS, LOAD_DLL, CREATE_THREAD)"| E
    E -->|"dispatch to handlers"| I
    I -->|"3. WriteProcessMemory → NtProtectVirtualMemory"| OS
    I -->|"patch entry point"| TP
    E -->|"lookup symbols"| DBG
    DBG -->|"SymFromName result"| I
    D -->|"4. DebugActiveProcessStop"| OS
    OS -->|"5. Resume Target Thread"| TP

    %% Click Events
    click AP "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis/x64/Debug/ProcessHypnosis.exe"
    click SLN "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis.sln"
    click VCX "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis/ProcessHypnosis.vcxproj"
    click FIL "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis/ProcessHypnosis.vcxproj.filters"
    click USR "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis/ProcessHypnosis.vcxproj.user"
    click CPP "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/ProcessHypnosis/ProcessHypnosis/ProcessHypnosis.cpp"
    click DBGF "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/tree/main/ProcessHypnosis/ProcessHypnosis/x64/Debug/"
    click RMD "https://github.com/carlosg13/process-hypnosis-debugger-assisted-control-flow-hijack/blob/main/README.md"

    %% Styles
    classDef usermode fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef kernel   fill:#F7D6AE,stroke:#333,stroke-width:1px
    classDef side     fill:#C8F7AE,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef artifact fill:#E0E0E0,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
