ProxyLib

A sophisticated Windows DLL proxy library with reflective loading capabilities for advanced DLL interception and manipulation.

⚠️ Work in Progress - This project is currently under active development and may contain incomplete features or bugs.

Overview

ProxyLib is a Windows-specific library that enables transparent DLL proxying through reflective loading. It allows you to intercept and redirect function calls to existing system DLLs while maintaining full binary compatibility with the target applications.

Key Features

• Reflective DLL Loading: Load and execute DLLs directly from memory without writing to disk
• Transparent Proxying: Seamlessly proxy calls to existing Windows DLLs (e.g., version.dll, kernel32.dll**)
• Cross-Architecture Support: Supports both x86 and x64 architectures
• Advanced PE Manipulation: Handle relocations, import tables, basic TLS callbacks (preview/alpha) *
• Compile-time Code Generation: Automatically generate assembly thunks for function redirection
• Flexible Configuration: Extensive build-time and runtime configuration options
• Callback System: Register callbacks to be notified when the proxied DLL is loaded

* The reflective loader is a WIP
** More complex DLLs, such as kernel32, were not fully tested

Architecture Support

• ✅ x86 (32-bit): Fully supported
• ✅ x64 (64-bit): Fully supported
• ❌ ARM/ARM64: Not currently supported (planned for future releases)

Prerequisites

Required Tools

• Windows 10/11 (primary development and target platform)
• CMake 3.20 or later
• Python 3.10.x
• One of the following compilers:
  • MSVC 2019 or later (recommended)
  • MinGW-w64 with GCC 10+
  • Clang with MSVC-compatible frontend

Required Python Packages

pip install -r requirements.txt

Optional Tools

• Ninja Build System (recommended for faster builds)
• NASM (for non-MSVC builds)
• Visual Studio or Visual Studio Build Tools

Quick Start

1. Clone the Repository

git clone https://github.com/Guila767/ProxyLib.git
cd ProxyLib

2. Install Dependencies

pip install -r requirements.txt

3. Configure Build

Using MSVC (Recommended)

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DPROXY_SOURCE_DLL="version.dll" ^
    -DPROXY_ENABLE_LOG=ON

Using Ninja + MSVC

cmake -S . -B build -G Ninja ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DPROXY_SOURCE_DLL="version.dll" ^
    -DPROXY_ENABLE_LOG=ON

Using MinGW

cmake -S . -B build -G "MinGW Makefiles" ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DPROXY_SOURCE_DLL="version.dll"

4. Build

cmake --build build --config Release

5. Output

The build will generate:

• proxy_library.dll - The main proxy library
• proxy_exports.def - Export definition file
• proxy_thunks.asm - Generated assembly thunks
• proxy_map.json - Export mapping information

Configuration Options

CMake Build Options

Option	Default	Description
PROXY_SOURCE_DLL	"version.dll"	Target DLL to proxy
PROXY_ENABLE_LOG	OFF	Enable runtime logging
PROXY_ENABLE_CONSOLE	OFF	Attach console for log output
PROXY_INIT_LAZY	OFF	Delay payload initialization until first call
PROXY_LINK_MAP	OFF	Generate linker map files
BUILD_TESTS	OFF	Build unit tests
BUILD_LOADER	OFF	Build debugger loader executable

Example Configurations

Debug Build with Full Logging

cmake -S . -B build -G Ninja ^
    -DCMAKE_BUILD_TYPE=Debug ^
    -DPROXY_ENABLE_LOG=ON ^
    -DPROXY_ENABLE_CONSOLE=ON ^
    -DPROXY_LINK_MAP=ON ^
    -DBUILD_TESTS=ON

Release Build for Production

cmake -S . -B build -G Ninja ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DPROXY_SOURCE_DLL="your_target.dll"

Usage

Basic Integration

#include <plib/proxy_lib.hpp>

// Register a callback to be notified when the proxied DLL loads
void onDllLoaded(const RL_IMAGE& image) {
    // Your custom logic here
    printf("DLL loaded at base: %p\n", image.base);
}

int main() {
    // Register the callback
    RegisterProxyCallback(onDllLoaded);
    
    // The proxy will automatically handle DLL loading and function redirection
    return 0;
}

Advanced Usage with C++ Callbacks

#include <plib/proxy_lib.hpp>

int main() {
    // Using lambda callback
    RegisterProxyCallback([](const RL_IMAGE& image) {
        // Custom initialization logic
        setupHooks(image);
    });
    
    return 0;
}

Project Structure

ProxyLib/
├── include/plib/          # Public headers
│   ├── proxy_lib.hpp     # Main library interface
│   ├── pe/               # PE parsing utilities
│   └── rl/               # Reflective loader
├── lib/                  # Implementation
│   ├── src/              # Source files
│   ├── loader/           # Debug loader utility
│   └── include/          # Private headers
├── tools/                # Build tools
│   ├── gen_def.py        # Export/thunk generator
│   ├── get_image_size.py # PE size calculator
│   └── *.inc             # Assembly macro files
├── tests/                # Unit tests
├── thirdparty/           # External dependencies
└── CMakeLists.txt        # Build configuration

Building Tests

Enable tests during configuration:

cmake -S . -B build -DBUILD_TESTS=ON
cmake --build build --config Release
cd build && ctest -C Release

Customization

Targeting Different DLLs

To proxy a different system DLL:

cmake -S . -B build -DPROXY_SOURCE_DLL="kernel32.dll"

Custom Assembly Dialects

The build system automatically detects and uses:

• MASM for MSVC builds
• NASM for GCC/Clang builds

Advanced PE Configuration

The library automatically handles:

• Import table reconstruction
• Relocation processing
• TLS callback initialization (basic support, not fully tested)
• Exception handling setup

Note: Delay-loaded DLL resolution is not currently supported (planned for future releases).

Troubleshooting

Common Issues

1. Python pefile module not found

   pip install pefile

2. NASM not found (MinGW builds)

   # Install NASM and add to PATH
   choco install nasm

3. Target DLL not found

   • Ensure the target DLL exists in System32
   • Use full path if necessary: -DPROXY_SOURCE_DLL="C:\\Windows\\System32\\version.dll"

4. Build failures on x86

   • Ensure proper architecture selection: -A Win32 for Visual Studio
   • Verify 32-bit toolchain installation

Debug Information

Enable verbose logging for troubleshooting:

cmake -S . -B build -DPROXY_ENABLE_LOG=ON -DPROXY_ENABLE_CONSOLE=ON

Limitations

• Windows Only: Currently supports Windows platforms exclusively
• ARM Architecture: ARM and ARM64 platforms are not yet supported
• Kernel Mode: User-mode DLLs only (no kernel driver support)
• Some Protection Mechanisms: May not work with heavily protected applications

TODO

• DLL chain-load support: Allows others DLLs to be mapped into the process address space in the loading phase
• More API functionalities: Add some missing functionalities to interact with the proxy DLL
• Support for thunk override: Allows redirecting the thunk with custom implementations (AKA: hook)
• Finish support for lazy loading: Allows the proxy DLL to be lazy loaded into the process

Contributing

This project is in active development. Contributions are welcome, especially for:

• ARM/ARM64 architecture support
• Additional PE format features
• Performance optimizations
• Documentation improvements

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

Security Notice

This library is designed for legitimate security research, debugging, and development purposes. Users are responsible for ensuring compliance with applicable laws and software license agreements when using this tool.

---

Note: This project is actively developed and tested primarily on Windows 10/11 with MSVC. While MinGW and Clang support is provided, MSVC is recommended for the most reliable builds.