How ahron-chet/pe-to-shellcode works
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.