cryptolith 0.2.4

Advanced Python source code obfuscator and compiler protection.

Cryptolith: High-Performance Python Compiler & Military-Grade Protection 🛡️🚀

The Fastest Python Compiler that also makes your code impossible to reverse engineer.

Cryptolith is the high-performance alternative to Nuitka and PyArmor. While others focus only on hiding code, Cryptolith focuses on Speed and Defense-in-Depth.

🏎️ Why Cryptolith?

• Fastest Execution: Native C compilation + GIL-Unlock (Turbo mode) allows Python to run up to 25x faster than CPython by bypassing the Global Interpreter Lock.
• Strongest Protection: Polymorphic VM virtualization + Control Flow Flattening (CFF) defeats standard decompilers (pycdc, uncompyle6) and professional reverse engineers.
• Zero Configuration: One-click protected builds for complex libraries like numpy, pandas, and tensorflow.

---

🏎️ Benchmark Results (Head-to-Head)

Workload: Multi-threaded CPU-bound mathematical loop (4 threads, 20M iterations total)

Engine	Execution Time	Binary Size	Protection
Python (Raw)	4.59s	< 1 KB	None
Nuitka (Standalone)	2.69s	18.3 MB	Native
PyArmor (Standard)	7.74s	0.6 MB	Bytecode
Cryptolith (Turbo)	0.18s	11.5 MB	Military Grade

Unlike Nuitka or PyArmor, which are still bound by the Global Interpreter Lock (GIL), Cryptolith's Turbo Mode identifies performance-critical kernels and compiles them to native C with explicit GIL release, achieving a 25.5x speedup on modern architecture.

• True Parallelism: While Nuitka threads fight for a single core, Cryptolith utilizes all available CPU cores simultaneously.
• Micro-Optimization: Our BCC compiler performs aggressive loop unrolling and SIMD-friendly math transpilation that exceeds standard CPython efficiency.

🛡️ Active Defense: Beyond Obfuscation

Standard tools offer Passive Protection (hiding code). Cryptolith offers Active Defense (detecting and misdirecting attackers).

• Silent Corruption: If a debugger or unauthorized environment is detected, Cryptolith doesn't just crash. It enters a "Hostile State" where VM calculations are subtly corrupted. Attackers waste weeks debugging "ghost bugs" while the actual logic remains safe.
• Polymorphic Opcode Mapping: Every single build of your project uses a unique, randomized instruction set. Dissecting one binary provides zero help in dissecting the next.

---

💎 Feature Matrix

Feature	PyArmor	Nuitka	Cryptolith
Bytecode Hiding	Strong (VM)	Strong (Native)	Strongest (Native + VM)
Logic Obfuscation	Yes (CFF)	Weak/None	Yes (Polymorphic CFF)
Performance	Slower (Overhead)	Faster (Native)	25x Faster (Turbo/No-GIL)
Competitive Advantage	Security only	Compilation only	Ultimate IP Performance

---

💠 Tiered Licensing Model

Cryptolith follows an Open Core strategy. We believe free users are our best evangelists.

[Community Edition] (Free Forever)

No watermarks. Build professional, protected tools for small projects and open-source use.

• ✅ Native Compilation: Compiles Python to standalone machine code (Assembly).
• ✅ Symbol Renaming: Deep recursive renaming of functions, classes, and variables.
• ✅ Full Scoping: Fine-grained project control with --include and --exclude.
• ✅ One-Click Bundling: Produces clean, professional standalone binaries.
• ✅ Auto-Pilot Mode: Smart analysis triggers optimal settings.

🛡️ Security Architecture: "The Inception Build"

Cryptolith eats its own dog food. The compiler you download is protected by itself.

1. Bootstrapped Core: The engine (.pyd) is compiled using Cryptolith's own Obfuscation + VM + Turbo pipeline.
2. Zero Source Leaks: The distribution contains NO Python source code for the core logic, only mathematically hardened binaries.
3. Tamper Proof: The compiler verifies its own integrity at runtime using encrypted checksums.

[Pro Edition] (Professional)

The ultimate performance and security suite for enterprise-grade IP.

• 🚀 Turbo Mode (GIL Unlock): Release the Global Interpreter Lock for true multi-threaded parallel performance.
• ⚛️ Polymorphic VM: Randomized instruction sets per build—unique signature every time.
• 🔐 Control Flow Flattening (CFF): Logic spaghetti injection to defeat symbolic execution and human analysis.
• 💎 String & Constant Encryption: Automated encryption with stack-only decryption.
• 🛡️ Hardware Binding: Lock binaries to specific MAC, IP, or HWID.
• 📦 Asset VFS: Securely bundle AI models and data files with zero-footprint memory loading.

🔑 For Administrators: Generating Licenses

To generate a license for a customer, use the included helper script:

1. Generate Keys (One-time):

   python scripts/admin_keygen.py generate-keys
   

2. Issue License:

   python scripts/admin_keygen.py create-license --user "Customer Name" --tier "Pro" --private-key "YOUR_PRIVATE_KEY"
   

   To lock to hardware, add --hardware-id "USER_HWID".

For full details, see the Licensing Guide.

---

📚 Reading the Documentation

We have comprehensive, high-quality documentation for both Community and Pro users.

Online/Local Website

To view the full documentation as a beautiful website with search and detailed guides:

1. Install dependencies: pip install mkdocs-material "mkdocstrings[python]"
2. Serve locally: mkdocs serve
3. View: Open http://127.0.0.1:8000 in your browser.

Documentation Chapters

• Getting Started: Introduction and value proposition.
• Installation: Set up your environment for native compilation.
• Obfuscation: Deep dive into renaming and control flow flattening.
• Turbo Mode (BCC): Extreme performance and binary-locked kernels.
• Advanced Security: Virtualization (VM), hardware binding, and asset protection.
• CLI Reference: Complete list of all build and release flags.
• API Reference: Programmatic usage of the Cryptolith engine.
• Examples: Templates for Web APIs, Data Science, and Licensing.

---

🛠️ Installation

pip install cryptolith

[!NOTE] Requirements: BCC and Turbo modes require a C compiler.

Windows: Install Visual Studio Build Tools.

• Workload: Desktop development with C++

Linux (x86/ARM):

sudo apt install build-essential python3-dev

macOS (Intel/ARM):

xcode-select --install

---

1. Auto-Pilot Mode (Recommended) 🤖

The smartest way to build. Automatically analyzes your code to enable the optimal security and performance settings. Detects deep learning libraries, web frameworks, and sensitive logic.

cryptolith build main.py --auto

Output: [+] Analysis: Torch detected. Enabling Turbo Mode. [+] Analysis: 'auth.py' detected. Enabling VM.

2. Manual Configuration (Advanced)

Full control over every optimization layer.

cryptolith build app.py --enable-bcc --enable-turbo --enable-vm --private

3. Professional Licensing

If you have a professional license, specify it to unlock Pro features:

cryptolith build main.py --license path/to/license.dat

---

🧪 Verification Suite

Cryptolith includes a rigorous automated test runner that validates the entire stack:

cryptolith test

---

🚀 CI/CD & Releases

Automated builds and releases are managed via GitHub Actions. To trigger a new release (which builds wheels for Windows, Linux, and macOS and uploads them to GitHub Releases):

The pipeline will automatically:

1. Build Wheels: Compile cross-platform binaries for all supported Python versions.
2. Generate Source Dist: Create a .tar.gz for source-based installations.
3. GitHub Release: Create a new release and attach all binaries as assets.
4. PyPI Publish: Attempt to publish to PyPI (requires valid token).

---

⚖️ License

Cryptolith is Dual-Licensed:

• Community Edition: Free for personal, educational, and open-source use.
• Pro Edition: Commercial license required for advanced features (Turbo, VM, Private Mode).

See LICENSE file for the full End User License Agreement (EULA).