# ahron-chet/pe-to-shellcode architecture

> Architecture diagram of the GitHub repository ahron-chet/pe-to-shellcode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahron-chet/pe-to-shellcode
- Repository: https://github.com/ahron-chet/pe-to-shellcode

## Overview

##### Project Type & Purpose
- It is a specialized CLI tool for converting PE files (Windows executables) into shellcode.
- Its purpose is to support all types of PE files, embedding custom arguments and building a standalone shellcode buffer capable of in-memory execution.
- Key features include handling dynamic imports, TLS callbacks, relocations, and proper section permissions through a custom-built PE loader implemented in assembly.

##### Main Components
- PE to Shellcode Generator:
- This is the main conversion engine encapsulated in the PE-To-Shellcode executable.
- Responsible for reading input PE files, processing them (including handling imports, TLS callbacks, and relocations), embedding given arguments, and outputting a unified shellcode binary (output.bin).
- Custom PE Loader (within the assets):
- These include assembly stubs (loaderstub.asm, startofstub64.bin, endofstub64.bin) that are used to set up the execution environment for the shellcode.
- Testing & Demonstration Utilities:
- Example PE with Arguments (ExamplePeWithArgs): A sample executable to validate that embedded arguments are correctly integrated and handled.
- Shellcode Runner (RunShellcode): A test utility that loads and executes the generated shellcode.

##### Relationships & Interactions
- The user provides a PE file (and optional arguments) to the PE-To-Shellcode generator.
- The generator processes the input by internally invoking the custom PE loader routines (linking in the assembly stubs from the assets folder) and embeds any provided arguments.
- The result of this process is a shellcode binary (saved as output.bin) that can be injected or run.
- For verification, the developer can use:
- ExamplePeWithArgs to mimic expected behavior of argument passing.
- RunShellcode to load and execute the generated shellcode, thus simulating a real injection scenario.
- These components are built and maintained as separate Visual Studio projects (as evident from the .vcxproj files) and later compiled into executables stored in bin/Release.

##### Architectural Patterns & Design Principles
- Separation of concerns:
- The shellcode generation, PE loading, and argument embedding are encapsulated in the converter.
- Test and demonstration utilities are kept separate, ensuring that the core functionality remains modular.
- Use of low-level assembly for critical operations:
- The design clearly isolates performance-critical and security-sensitive operations (e.g., loader stubs) from higher-level C/C++ code.
- Clear dependency and build time separation:
- Visual Studio project files and directory structuring (PE-To-Shellcode, RunShellcode, ExamplePeWithArgs) reflect organized, modular development.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    A("Input PE File & Arguments"):::input

    %% Conversion Layer
    subgraph "Conversion Layer"
        B("PE-To-Shellcode Generator\n(PE Parsing, DynamicImports, TLSCallbacks, Relocations, ArgEmbedding)"):::generator
        C("Custom PE Loader\n(Assembly stubs: loaderstub.asm, startofstub64.bin, endofstub64.bin)"):::loader
    end

    %% Output & Testing Layer
    subgraph "Output & Testing Layer"
        D("Output Binary (Shellcode)"):::output
        E("Example PE with Arguments"):::utility
        F("Shellcode Runner"):::utility
    end

    %% Data Flow Connections
    A -->|"provides"| B
    B -->|"generates"| D
    B -->|"invokes"| C
    B -->|"validatesArgs"| E
    D -->|"loadsExecutes"| F

    %% Click Events for PE-To-Shellcode Generator
    click B "https://github.com/ahron-chet/pe-to-shellcode/blob/main/PE-To-Shellcode/PE-To-Shellcode.c"
    click B "https://github.com/ahron-chet/pe-to-shellcode/blob/main/PE-To-Shellcode/PE-To-Shellcode.vcxproj"

    %% Click Events for Custom PE Loader
    click C "https://github.com/ahron-chet/pe-to-shellcode/blob/main/assets/loaderstub.asm"
    click C "https://github.com/ahron-chet/pe-to-shellcode/blob/main/assets/startofstub64.bin"
    click C "https://github.com/ahron-chet/pe-to-shellcode/blob/main/assets/endofstub64.bin"

    %% Click Events for Example PE with Arguments
    click E "https://github.com/ahron-chet/pe-to-shellcode/blob/main/ExamplePeWithArgs/ExamplePeWithArgs.cpp"
    click E "https://github.com/ahron-chet/pe-to-shellcode/blob/main/ExamplePeWithArgs/ExamplePeWithArgs.vcxproj"

    %% Click Events for Shellcode Runner
    click F "https://github.com/ahron-chet/pe-to-shellcode/blob/main/RunShellcode/RunShellcode.c"
    click F "https://github.com/ahron-chet/pe-to-shellcode/blob/main/RunShellcode/RunShellcode.vcxproj"

    %% Styles
    classDef input fill:#ffe0e0,stroke:#f66,stroke-width:2px;
    classDef generator fill:#cce5ff,stroke:#339,stroke-width:2px;
    classDef loader fill:#d4edda,stroke:#2a662a,stroke-width:2px;
    classDef output fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#818182,stroke-width:2px;
```
