From 1381e90ea65cfb00977034b99785c17008c47d1d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Sep 2025 06:57:15 +0000 Subject: [PATCH 1/4] Initial plan From 2c659ee398643e5172bdff9346ad0513a0b679e8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Sep 2025 07:01:45 +0000 Subject: [PATCH 2/4] Add comprehensive README.md with project overview, build instructions, and customizations Co-authored-by: Guila767 <31376051+Guila767@users.noreply.github.com> --- README.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..aae0d47 --- /dev/null +++ b/README.md @@ -0,0 +1,292 @@ +# 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, TLS callbacks, and delay imports +- **Runtime 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 + +## 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.7** or later +- One of the following compilers: + - **MSVC 2019** or later (recommended) + - **MinGW-w64** with GCC 10+ + - **Clang** with MSVC-compatible frontend + +### Required Python Packages + +```bash +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 + +```bash +git clone https://github.com/Guila767/ProxyLib.git +cd ProxyLib +``` + +### 2. Install Dependencies + +```bash +pip install -r requirements.txt +``` + +### 3. Configure Build + +#### Using MSVC (Recommended) + +```bash +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 + +```bash +cmake -S . -B build -G Ninja ^ + -DCMAKE_BUILD_TYPE=Release ^ + -DPROXY_SOURCE_DLL="version.dll" ^ + -DPROXY_ENABLE_LOG=ON +``` + +#### Using MinGW + +```bash +cmake -S . -B build -G "MinGW Makefiles" ^ + -DCMAKE_BUILD_TYPE=Release ^ + -DPROXY_SOURCE_DLL="version.dll" +``` + +### 4. Build + +```bash +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 +```bash +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 +```bash +cmake -S . -B build -G Ninja ^ + -DCMAKE_BUILD_TYPE=Release ^ + -DPROXY_SOURCE_DLL="your_target.dll" ^ + -DPROXY_INIT_LAZY=ON +``` + +## Usage + +### Basic Integration + +```cpp +#include + +// 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 + +```cpp +#include + +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: + +```bash +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: + +```bash +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 +- Delay-loaded DLL resolution +- Exception handling setup + +## Troubleshooting + +### Common Issues + +1. **Python pefile module not found** + ```bash + pip install pefile + ``` + +2. **NASM not found (MinGW builds)** + ```bash + # 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: + +```bash +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 + +## 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](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. \ No newline at end of file From 67d12b955d58fa03df451c2c6a18bdd6518ee87b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Sep 2025 14:05:10 +0000 Subject: [PATCH 3/4] Initial plan From e33a5331b9a0b4d5150a47ae8284fae453f3a137 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Sep 2025 14:09:21 +0000 Subject: [PATCH 4/4] Apply PR #2 review feedback: update Python requirements and clarify feature support Co-authored-by: Guila767 <31376051+Guila767@users.noreply.github.com> --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index aae0d47..d9947d0 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ProxyLib is a Windows-specific library that enables transparent DLL proxying thr - **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, TLS callbacks, and delay imports +- **Advanced PE Manipulation**: Handle relocations, import tables, basic TLS callbacks (preview/alpha) - **Runtime 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 @@ -30,7 +30,7 @@ ProxyLib is a Windows-specific library that enables transparent DLL proxying thr - **Windows 10/11** (primary development and target platform) - **CMake 3.20** or later -- **Python 3.7** or later +- **Python 3.10.x** - One of the following compilers: - **MSVC 2019** or later (recommended) - **MinGW-w64** with GCC 10+ @@ -229,10 +229,11 @@ The build system automatically detects and uses: The library automatically handles: - Import table reconstruction - Relocation processing -- TLS callback initialization -- Delay-loaded DLL resolution +- 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