cryptolith 0.2.4
Advanced Python source code obfuscator and compiler protection.
Requires Python: >=3.7

# 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):
    ```bash
    python scripts/admin_keygen.py generate-keys
    ```
2.  **Issue License**:
    ```bash
    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](docs/getting-started/licensing.md).

---

## 📚 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**](docs/index.md): Introduction and value proposition.
*   [**Installation**](docs/getting-started/installation.md): Set up your environment for native compilation.
*   [**Obfuscation**](docs/features/obfuscation.md): Deep dive into renaming and control flow flattening.
*   [**Turbo Mode (BCC)**](docs/features/turbo-mode.md): Extreme performance and binary-locked kernels.
*   [**Advanced Security**](docs/features/security.md): Virtualization (VM), hardware binding, and asset protection.
*   [**CLI Reference**](docs/reference/cli.md): Complete list of all build and release flags.
*   [**API Reference**](docs/reference/api.md): Programmatic usage of the Cryptolith engine.
*   [**Examples**](docs/examples/web-apps.md): Templates for Web APIs, Data Science, and Licensing.

---

## 🛠️ Installation

```bash
pip install cryptolith
```

> [!NOTE]
> **Requirements**: BCC and Turbo modes require a C compiler.
>
> **Windows**: Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
> - Workload: **Desktop development with C++**
>
> **Linux (x86/ARM)**:
> ```bash
> sudo apt install build-essential python3-dev
> ```
>
> **macOS (Intel/ARM)**:
> ```bash
> 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.
```bash
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.
```bash
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:
```bash
cryptolith build main.py --license path/to/license.dat
```

---

## 🧪 Verification Suite

Cryptolith includes a rigorous automated test runner that validates the entire stack:
```bash
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).