python-encrypt-code 0.1.1

Python-based command line tool to encrypt and decrypt Python modules.

Python Encrypt Code

A tool that integrates seamlessly with modern CI and Dockerized edge deployments.

A powerful Python CLI tool for encrypting and decrypting Python modules, enabling secure distribution and execution of Python code. Perfect for protecting intellectual property, distributing commercial Python applications, or creating secure deployment packages.

⚠️ SECURITY DISCLAIMER: This tool is currently in development and not ready for production use. In its current version, the tool writes decrypted files to temporary directories on disk during execution, which poses a security risk as sensitive code may remain accessible in the filesystem. This security vulnerability will be addressed in a future version by implementing in-memory execution. Use at your own risk for development and testing purposes only.

Features

• 🔐 Strong Encryption: AES-256 encryption using the cryptography library
• 📦 Module Packaging: Compress and encrypt entire Python packages into a single encrypted file
• 🚀 Direct Execution: Run encrypted Python modules without extracting to disk (coming in a later version)
• 🔑 Secure Password Generation: Built-in cryptographically secure password generator
• 🛠️ Developer Friendly: Full type annotations and comprehensive test coverage
• 📁 Preserve Structure: Maintains package hierarchy and imports when decrypting

Installation

Using uv (recommended)

git clone https://gitea.gt-proj.com/brian/python-encrypt-code.git
cd python-encrypt-code
uv install

Using pip

git clone https://gitea.gt-proj.com/brian/python-encrypt-code.git
cd python-encrypt-code
pip install -e .

Quick Start

1. Generate a Secure Password

uv run python-encrypt-code generate-password
# Output: Wlg2aFQ2dWhkX0U0TkxOcXBHY09acTR1ZVo5UlNPcWxSamVxOTI5a08tdz0=

2. Encrypt a Python Module

export MODULE_PATH=./src/my_package
export ENCRYPTED_FILE=my_package.pec
export PASSWORD=your-secure-password

uv run python-encrypt-code encrypt ${MODULE_PATH} -o ${ENCRYPTED_FILE} -p ${PASSWORD}

3. Decrypt an Encrypted File

uv run python-encrypt-code decrypt ${ENCRYPTED_FILE} -o ./decrypted -p ${PASSWORD}

4. Run Encrypted Module Directly

uv run python-encrypt-code run-insecure ${ENCRYPTED_FILE} --script main.py

Commands

generate-password

Generate a cryptographically secure password for encryption.

uv run python-encrypt-code generate-password

encrypt

Encrypt a Python module or package directory.

uv run python-encrypt-code encrypt <source> -o <output> -p <password> [-aad <json-string>]

Options:

• source_path: Directory containing Python files to encrypt
• -o, --output: Output path for encrypted file
• -p, --password: Password for encryption
• -aad, --additional-authenticated-data: JSON-formatted string to embed metadata in the encrypted file

decrypt

Decrypt a file and extract contents to disk.

uv run python-encrypt-code decrypt <source> -o <output>

Options:

• source: Path to encrypted file
• -o, --output: Directory to extract decrypted files

run-insecure

Decrypt and execute a Python script from an encrypted package. N.B. this writes decrypted files to a temporary folder on the disk before executing!

uv run python-encrypt-code run-insecure <source> --script <script>

Options:

• source: Path to encrypted file
• -s, --script: Python script to execute

Use Cases

1. Protecting Commercial Python Applications

# Encrypt your entire application
export PASSWORD=$(uv run python-encrypt-code generate-password)
uv run python-encrypt-code encrypt ./my_app -o my_app.pec -p ${PASSWORD}

# Setup your own authentication source and subclass the PasswordProvider
# Distribute the .pec file to customers and
# let them run it without seeing the source code
uv run python-encrypt-code run-insecure ./my_app.pec -p ${PASSWORD} --script main.py

2. Secure Deployment Packages

# Create encrypted deployment package
uv run python-encrypt-code encrypt ./production_code -o deployment.pec -p $DEPLOY_PASSWORD

# Deploy and run on target server
uv run python-encrypt-code run-insecure deployment.pec --script startup.py

3. Educational Content Protection

# Protect course materials or assignments
uv run python-encrypt-code encrypt ./course_solutions -o solutions.pec -p student_password

Development

Prerequisites

• Python 3.12+
• uv (recommended) or pip

Setup Development Environment

git clone https://github.com/yourusername/python-encrypt-code.git
cd python-encrypt-code

# Install with development dependencies
uv install --dev

# Install pre-commit hooks
uv run pre-commit install

Project Structure

python-encrypt-code/
├── src/python_encrypt_code/          # Main package
│   ├── __main__.py                   # CLI entry point
│   ├── data_zipper/                  # Compression utilities
│   ├── file_encrypter/               # Encryption/decryption
│   ├── password_provider/            # Password generation
│   └── module_importer/              # Dynamic module loading
├── tests/
│   ├── unit/                         # Unit tests
│   ├── integration/                  # Integration tests
│   └── test_data/                    # Test fixtures
├── pyproject.toml                    # Project configuration
└── README.md

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov-report=term-missing --cov=src/python_encrypt_code

# Run specific test categories
uv run pytest tests/unit/           # Unit tests only
uv run pytest tests/integration/    # Integration tests only

Code Quality

# Type checking
uv run mypy .

# Linting and formatting
uv run ruff check .
uv run ruff format .
uv run prettier --write .

# Run pre-commit checks
uv run pre-commit run --all-files

Technical Details

Encryption Method

• Algorithm: AES-256-GCM (Galois/Counter Mode)
• Key Format: Direct 32-byte key from base64-encoded password
• Authentication: Built-in authentication tag prevents tampering
• Nonce: Random 12-byte nonce for each encryption operation

File Format

Encrypted .pec files contain:

1. Nonce (12 bytes)
2. Encrypted ZIP archive with authentication tag (variable length)

Module Loading

The ModuleImporter class provides sophisticated module loading capabilities:

• Preserves package structure and relative imports
• Handles __init__.py files correctly
• Supports running specific scripts from encrypted packages
• Temporary filesystem isolation for security

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (uv run pytest)
6. Run code quality checks (uv run pre-commit run --all-files)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Security Considerations

• Password Storage: Never store passwords in plain text. Use environment variables or secure key management systems.
• Direct Key Usage: Uses base64-encoded 32-byte keys directly with AES-256-GCM (no key derivation).
• Memory Safety: Temporary decrypted files are automatically cleaned up.
• Verification: Authentication tags prevent tampering with encrypted files.
• Custom Password Providers: For production deployments, you should implement your own PasswordProvider class adapted to your specific security architecture (e.g., integration with HSMs, key vaults, or enterprise secret management systems). Custom implementations can collect available metadata such as user context, machine identifiers, environment variables, or request timestamps and send this information along with password requests to your secret management system for enhanced security and audit logging. The default implementation is suitable for development and testing only.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.1.0

• Initial release
• Basic encrypt/decrypt functionality
• CLI interface with all core commands
• Comprehensive test suite
• Type annotations and documentation

Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Open an issue
• 📖 Documentation: See inline documentation and type hints
• 🤝 Contributing: See Contributing section above

Coming Soon

• Implement key derivation: improve user friendliness as well as brute-force protection
• Support pure in-memory execution: improves security