Add comprehensive README.md with project overview, build instructions, and customizations

README.md

@@ -0,0 +1,293 @@
+# 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)
+- **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.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
+
+```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 <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
+
+```cpp
+#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:
+
+```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 (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**
+   ```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.