Onyx is a Python-to-native binary compiler that converts .py scripts into standalone Windows executables. It applies multi-layer protection including Cython compilation, XOR encryption, anti-debugging checks, and a RunPE crypter stage to produce hardened output binaries.
- Features
- Requirements
- Installation
- Usage
- Protection Modes
- Architecture
- Project Structure
- Configuration
- Changelog
- Contributing
- License
- Cython Compilation: Converts Python source into compiled C extensions (
.pyd) to strip away readable source code. - XOR Encryption Layer: Encrypts the compiled binary with a per-build random 32-byte key before embedding.
- C++ Loader Generation: Produces a native C++ loader that decrypts and loads the protected module at runtime.
- Anti-Debug Protection: Includes
IsDebuggerPresent,CheckRemoteDebuggerPresent, Frida detection,NtSetInformationThread(ThreadHideFromDebugger), and debugger trace checks. - Compile-Time String Obfuscation: Uses template-based MetaString obfuscation (ADVobfuscator-style) so sensitive strings never appear in plaintext in the binary.
- RunPE Crypter Stage: Wraps the final executable in a process-hollowing stub for an additional protection layer.
- Monolithic Output: Native mode links everything into a single
.exewith no external.pyddependencies. - GUI Interface: A clean, dark-themed desktop GUI built with pywebview for drag-and-drop compilation.
- CLI Support: Full command-line interface for automation and scripting workflows.
- Unique Build IDs: Each compilation generates a random build identifier, producing unique module names and file signatures per build.
- OS: Windows 10 / 11 (x64)
- Python: 3.8 or higher
- C++ Compiler: Microsoft Visual C++ Build Tools (MSVC)
- Install via Visual Studio Build Tools
- Select "Desktop development with C++" workload
- Python Packages:
pywebview-- Desktop GUI frameworkCython-- Python to C compilerpycryptodome-- Cryptographic primitivessetuptools-- Build system
- Clone the repository:
git clone https://github.com/bozopr00x/Onyx-Packer.git
cd Onyx-Packer- Install Python dependencies:
pip install -r requirements.txt- Verify that MSVC Build Tools are installed and accessible. Open a terminal and run:
cl.exeIf cl.exe is not found, open the Developer Command Prompt for Visual Studio or add the MSVC paths to your environment.
Launch the graphical interface:
python run.pywSteps:
- Click the drop zone or drag a
.pyfile onto it. - Select a protection mode (Native or Layered).
- Click COMPILE.
- Output files are generated in the current working directory.
Run the compiler engine directly:
python src/Onyx.py <target.py>You will be prompted to select a mode:
[?] Target Python file: payload.py
[?] Select Mode (1/2) [1]: 1
Or pass the target as an argument:
python src/Onyx.py payload.py| Mode | Output | Description |
|---|---|---|
| Native | <name>_native_protected.exe |
Single monolithic executable with RunPE stub |
| Layered | <name>_protected.pyd + <name>_run.exe |
Encrypted PYD module with native loader |
The full compilation pipeline:
Python Source
-> Cython (.pyx)
-> C Extension (.pyd / .obj)
-> Static Linked EXE (with embedded Python init)
-> RunPE Crypter Stub (final .exe)
This produces a single .exe file. The original Python source is compiled into a C object, linked with a native loader that includes string obfuscation and anti-debug checks, then wrapped in a RunPE process-hollowing stub. The output binary appears as a standard MSVC-compiled executable to analysis tools like Detect It Easy (DIE).
A two-stage approach:
Python Source
-> Cython PYD (Layer 1)
-> XOR Encrypted + Embedded in C++ Loader (Layer 2)
-> Protected PYD + Native EXE Launcher
This produces two files: an encrypted .pyd module and a native .exe launcher. The encrypted PYD is decrypted to a temporary hidden file at runtime, loaded into the Python interpreter, and scheduled for deletion on reboot.
+-----------------+
| Python Source |
+--------+--------+
|
+--------v--------+
| Cython Compiler |
| (source -> .pyd) |
+--------+--------+
|
+-------------+-------------+
| |
+--------v--------+ +--------v--------+
| Native Mode | | Layered Mode |
+--------+--------+ +--------+--------+
| |
+--------v--------+ +--------v--------+
| Static Linker | | XOR Encrypt PYD |
| + Anti-Debug | | + C++ Loader |
| + String Obfusc | | + Anti-Debug |
+--------+--------+ +--------+--------+
| |
+--------v--------+ +--------v--------+
| RunPE Crypter | | EXE + PYD Pair |
| (Final .exe) | +--------+--------+
+--------+--------+
|
+--------v--------+
| Protected Output |
+-----------------+
The following checks are embedded at multiple stages (Cython guard, C++ loader, and RunPE stub):
| Check | Method |
|---|---|
| Kernel debugger | IsDebuggerPresent() |
| Remote debugger | CheckRemoteDebuggerPresent() |
| Frida agent | GetModuleHandleW("frida-agent.dll") |
| Python trace | sys.gettrace() |
| Thread hiding | NtSetInformationThread(0x11) |
Onyx-Packer/
├── run.pyw # GUI entry point
├── requirements.txt # Python dependencies
├── LICENSE # Project license
├── README.md # This file
└── src/
├── Onyx.py # Core compiler engine (CLI + API)
└── gui.py # GUI application (pywebview + HTML/CSS/JS)
Onyx.py-- Contains theOnyxCompilerclass with all compilation logic: Cython transpilation, XOR encryption, C++ code generation, MSVC compilation, static linking, and the RunPE crypter builder.gui.py-- Implements the desktop GUI using pywebview with an embedded HTML/CSS/JS interface. Provides drag-and-drop file loading, mode selection, real-time console output, and a dark glass-themed UI.
Onyx does not use a configuration file. All behavior is controlled through mode selection at compile time.
| Parameter | Default | Description |
|---|---|---|
| Protection Mode | Native (1) | Monolithic EXE or Layered EXE+PYD |
| Encryption Key | Random | 32-byte key generated per build |
| Build ID | Random | 6-byte hex token for unique naming |
| Subsystem | WINDOWS | No console window on execution |
The C++ compilation uses /O2 optimization and /MT static linking by default. String obfuscation keys are derived from compile-time __TIME__ macros, making each build produce different encrypted strings.
- Initial release
- Cython-based Python to native compilation
- Two protection modes: Native (monolithic) and Layered (EXE + PYD)
- XOR encryption with per-build random keys
- C++ loader with anti-debug checks
- RunPE process-hollowing crypter stage
- Compile-time string obfuscation (ADVobfuscator-style)
- Desktop GUI with drag-and-drop support
- CLI interface for scripted builds
- Fork the repository.
- Create a feature branch:
git checkout -b feature/your-feature - Commit your changes:
git commit -m "Add your feature" - Push to your branch:
git push origin feature/your-feature - Open a Pull Request.
Guidelines:
- Keep commits focused and atomic.
- Follow existing code style and naming conventions.
- Test compilation output with both modes before submitting.
- Do not commit build artifacts or temporary directories.
This project is licensed under the MIT License. See LICENSE for details.
This tool is provided for authorized security research and legitimate software protection purposes only. The author is not responsible for any misuse. Use it in compliance with all applicable laws and regulations.