obfus

A comprehensive Python code obfuscation engine.

Features

• String Obfuscation - Multiple encoding methods (XOR, Base64, ROT13, multi-layer)
• Name Mangling - Local variables, arguments, code names, attributes
• Code Object Obfuscation - Bytecode encryption and protection
• Module Protection - Prevent modification and inspection
• Wrap Mode - Dynamic deobfuscation at runtime
• RFT (Refactoring) - Complete identifier renaming
• Import Obfuscation - Hide import statements
• Control Flow Obfuscation - Opaque predicates, dead code injection
• Zero Dependencies - Pure Python, no external packages required

Installation

pip install obfus

Or install from source:

git clone https://github.com/rodmena-limited/obfus.git
cd obfus
pip install -e .

Quick Start

Basic Usage

from obfus import ObfuscationConfig, ObfuscationEngine

# Use preset configurations
config = ObfuscationConfig.minimal()    # Light obfuscation
config = ObfuscationConfig.standard()   # Balanced obfuscation
config = ObfuscationConfig.aggressive() # Heavy obfuscation

# Create engine and obfuscate
engine = ObfuscationEngine(config)
obfuscated = engine.obfuscate_source('''
def hello(name):
    return f"Hello, {name}!"

print(hello("World"))
''')
print(obfuscated)

Convenience Functions

from obfus import obfuscate, obfuscate_file, obfuscate_directory

# Obfuscate a string
result = obfuscate("print('Hello')")

# Obfuscate a file
obfuscate_file("input.py", "output.py")

# Obfuscate entire directory
obfuscate_directory("src/", "dist/")

Command Line

# Obfuscate a single file
obfus input.py -o output.py

# Obfuscate a directory
obfus src/ -o dist/

# With specific preset
obfus input.py -o output.py --preset aggressive

Configuration

Presets

Custom Configuration

from obfus import ObfuscationConfig, ObfuscationEngine, WrapMode

config = ObfuscationConfig(
    # Name obfuscation
    mix_localnames=True,      # Obfuscate local variable names
    mix_argnames=False,       # Keep argument names (for keyword args)
    mix_coname=1,             # Hide code object names (0-2)
    mix_attr=False,           # Obfuscate attribute names

    # String obfuscation
    mix_str=True,             # Obfuscate string constants
    mix_str_threshold=8,      # Min string length to obfuscate

    # Module protection
    obf_module=True,          # Obfuscate module bytecode
    obf_code=1,               # Code object obfuscation level (0-2)
    wrap_mode=WrapMode.SIMPLE, # Dynamic deobfuscation

    # Advanced features
    enable_rft=False,         # Full identifier renaming
    enable_control_flow=False, # Control flow obfuscation
    enable_dead_code=False,   # Dead code injection
)

engine = ObfuscationEngine(config)

Configuration Options Reference

Name Obfuscation

String Obfuscation

Module Protection

Advanced Features

RFT (Refactoring) Mode

RFT mode performs complete identifier renaming across your codebase:

config = ObfuscationConfig(
    enable_rft=True,
    rft_excludes={'main', 'setup'},  # Names to preserve
    rft_preserve_exports=True,        # Keep __all__ names
)

RFT Options

Limitations and Compatibility

Works With

• Pure Python code
• Standard library usage
• Internal class hierarchies
• Async/await patterns
• Generators and iterators
• Context managers
• Decorators
• Metaclasses
• Dataclasses and enums

May Break

Safe Usage Guidelines

# For libraries with external interfaces
config = ObfuscationConfig.minimal()

# For standalone scripts
config = ObfuscationConfig.aggressive()

# For maximum protection (internal tools only)
config = ObfuscationConfig.maximum()

Performance

Obfuscation adds minimal runtime overhead:

Test suite performance is typically within 5% of original code.

Examples

Obfuscate a Package

from obfus import obfuscate_directory, ObfuscationConfig

config = ObfuscationConfig.standard()
obfuscate_directory(
    "mypackage/",
    "dist/mypackage/",
    config=config,
    recursive=True,
)

Preserve Specific Names

config = ObfuscationConfig(
    enable_rft=True,
    rft_excludes={
        'main',
        'run',
        'setup',
        'teardown',
        '__init__',
        '__call__',
    },
)

Skip Certain Files

from pathlib import Path
from obfus import ObfuscationEngine, ObfuscationConfig

config = ObfuscationConfig.standard()
engine = ObfuscationEngine(config)

for py_file in Path("src").rglob("*.py"):
    # Skip test files and configs
    if "test" in py_file.name or py_file.name == "config.py":
        continue

    source = py_file.read_text()
    obfuscated = engine.obfuscate_source(source)

    output = Path("dist") / py_file.relative_to("src")
    output.parent.mkdir(parents=True, exist_ok=True)
    output.write_text(obfuscated)

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=obfus --cov-report=html

# Run specific test class
pytest tests/test_obfuscator.py::TestAllFeatures -v

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.