cryptolith 0.1.12

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.

[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 (MSVC on Windows, GCC/Clang on Linux/macOS).

---

🚀 Quick Usage

1. Basic Build

The simplest way to protect a script and bundle it into an EXE:

cryptolith build main.py --output dist/protected

2. High-Performance Build (Pro)

Enable native transpilation and release the GIL:

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

3. Ultimate Security (Pro)

Enable virtualization and private mode to defeat all known decompilers:

cryptolith build app.py --enable-vm --private --license license.dat

4. Professional Licensing

If you have a professional license, specify it during the build:

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

Cryptolith will automatically verify the ED25519 signature and unlock all Pro features.

---

🧪 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):

1. Tag the version

git tag -a v1.0.0 -m "Release version 1.0.0"

2. Push the tag

git push origin v1.0.0

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

Licensed under the MIT License. See LICENSE for details.

Notes

• Go to your project on pypi.org.
• Go to Settings > Publishing > Add a GitHub Publisher.
• Enter your Repository name (cryptolith), the Workflow name ( publish.yml ), and the Environment name (pypi).
• Once connected, PyPI will automatically trust the tokens generated by your GitHub Actions runner.