cryptolith 0.1.1

Advanced Python source code obfuscator and compiler protection.

Cryptolith: Professional Python Obfuscator & Compiler 🛡️🚀

Cryptolith is a next-generation protection suite for Python intellectual property. It goes beyond simple source-code obfuscation by providing a multi-layered defense strategy: AST-based symbolic renaming, control flow flattening, string encryption, and native C compilation.

💎 Tiered Licensing Model

Cryptolith is available in two distinct editions to serve both hobbyists and professional developers.

[Community Edition] (Free)

A powerful introductory tool for small projects and educational use.

• ✅ AST Symbolic Renaming: Deep recursive renaming of functions, classes, and variables.
• ✅ Control Flow Flattening: Obfuscates the logic flow of your functions.
• ✅ Advanced Scoping: Fine-grained control with --include and --exclude glob patterns.
• ✅ Standard Packaging: Bundles your app into a standalone binary.
• ⚠️ Watermark: Injects a mandatory startup message.

[Pro Edition] (Professional)

The ultimate protection suite for enterprise-grade intellectual property.

• 🚀 Everything in Community +
• ⚛️ VM Virtualization: Translate critical logic into a private, non-standard instruction set.
• 🔐 String Encryption: Sensitive strings are encrypted and decrypted only in memory.
• 💎 Asset VFS: Encrypt and bundle data files and AI models with memory-only decryption.
• 🏎️ BCC & Turbo Mode: Transpile performance-critical kernels to native C and bypass the GIL.
• 🛡️ Hardware Locking: Bind binaries to specific MAC IDs or IP addresses.
• ⏳ Time Boxing: Set hard expiration dates with Network Time Server protection.
• 🛡️ No Watermarks: Produce clean, professional binaries for distribution.

---

📚 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

---

🧪 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.