obfuslite 1.1.0

Advanced Python code obfuscation library with enhanced GUI and multi-file support

<<<<<<< HEAD

🛡️ ObfusLite - Advanced Python Code Obfuscation

=======

ObfusLite Python Code Obfuscation Library

474534d577a35d3d77e276d4f525af80de8ab7e8

ObfusLite is a comprehensive Python code obfuscation library featuring novel encoding techniques and an enhanced GUI with multi-file support. Protect your Python applications with professional-grade obfuscation suitable for PyInstaller compilation.

✨ Key Features

🖥️ Enhanced GUI Interface (NEW!)

• 🔥 Multi-File Batch Processing - Process hundreds of files simultaneously
• 🔗 Smart File Combining - Merge multiple Python files into one (NEW in v1.1.0!)
• 📁 Project Management - Save and load obfuscation projects (.pyobf files)
• 📊 Code Analysis - Intelligent recommendations based on code complexity
• 🔍 Side-by-Side Comparison - Compare original vs obfuscated code
• 🎨 Template System - Save and reuse obfuscation configurations
• 📦 Export Options - ZIP archives, CSV reports, detailed logs
• ⚡ Real-time Progress - Track processing status for each file
• 🔧 Professional Workflow - Suitable for enterprise and team environments

⚡ Performance Optimized

• 3 Performance Modes: Fast, Balanced, Full
• Ultra-Fast Encoders: 100x faster than complex algorithms
• Low Memory Usage: < 1MB RAM for most operations
• Batch Processing: Handle multiple files efficiently

🔧 Fast Obfuscation Techniques

1. Fast XOR Encoding - Multi-key XOR with compression (Recommended)
2. Fast Base64 Encoding - Base64 with character substitution
3. Fast Rotation Cipher - Multi-round Caesar cipher
4. Fast Hash Encoding - Hash-based chunk encoding
5. Fast Binary Manipulation - Bit shifting operations
6. Fast Lookup Tables - Character mapping encoding

🔬 Advanced Obfuscation Techniques

1. Quantum-Inspired Encoding - Uses quantum gate operations and superposition concepts
2. DNA Sequence Mapping - Maps code to biological DNA sequences with genetic mutations
3. Fractal Pattern Encoding - Encodes data using mathematical fractals and chaos theory
4. Neural Network Weight Encoding - Stores code as neural network weights and biases
5. Steganographic Hiding - Hides code within innocent-looking data structures
6. Runtime Reconstruction - Creates self-modifying code that rebuilds at runtime
7. Multi-dimensional Tensor Encoding - Uses tensor operations and linear algebra

🎯 Professional Benefits

• ✅ Lightning Fast - Process large files in milliseconds
• ✅ Multi-File Support - Batch process entire projects
• ✅ Project Management - Save and resume complex workflows
• ✅ PyInstaller Compatible - Generates standalone code ready for .exe compilation
• ✅ Multi-layer Protection - Apply multiple obfuscation layers for enhanced security
• ✅ Reversible - Complete deobfuscation capability for legitimate use
• ✅ Novel Algorithms - Unique techniques not found in traditional obfuscators
• ✅ Enhanced GUI - Professional interface with advanced features
• ✅ Team Collaboration - Shareable projects and templates

📦 Installation

From PyPI (Recommended)

# Basic installation
pip install obfuslite

# With enhanced GUI support
pip install obfuslite[gui]

# Full installation with all features
pip install obfuslite[full]

From Source

git clone https://github.com/zinzied/obfuslite.git
cd obfuslite
pip install -e .

Optional Dependencies

# For enhanced GUI interface (recommended)
pip install obfuslite[gui]

# For development and testing
pip install obfuslite[dev]

# For advanced techniques (neural, tensor)
pip install obfuslite[full]

Requirements

• Python: 3.8+
• Core: No additional dependencies
• GUI: PyQt6 >= 6.4.0
• Advanced: NumPy >= 1.21.0, SciPy >= 1.9.0

🚀 Quick Start

Enhanced GUI Interface (Recommended)

# Launch enhanced GUI with multi-file support
obfuslite gui

# Or use the dedicated GUI command
obfuslite-gui

Command Line Interface

# Obfuscate a single file
obfuslite obfuscate input.py -o output.py -t fast_xor -l 2

# Combine multiple files into one (NEW!)
obfuslite combine main.py --obfuscate -t fast_xor -l 2

# List available techniques
obfuslite list-techniques

# Benchmark performance
obfuslite benchmark input.py

# Get help
obfuslite --help

Python API

from obfuslite import Obfuscator, quick_obfuscate

# Quick obfuscation (one line!)
standalone_code = quick_obfuscate(your_code, technique='fast_xor', layers=2)

# Advanced usage
obfuscator = Obfuscator()
result = obfuscator.obfuscate(code, technique='fast_xor', layers=2)
standalone_code = obfuscator.create_standalone_file(result)

# Save and run
with open('obfuscated_app.py', 'w') as f:
    f.write(standalone_code)

🔗 Smart File Combining (NEW in v1.1.0!)

Solve Multi-File Import Issues

ObfusLite now includes powerful file combining functionality that solves the common problem where obfuscated multi-file applications can't find their modules.

The Problem:

# main.py
from utils import helper_function  # ❌ Fails after obfuscation
from config import settings       # ❌ Import errors

# After obfuscating each file separately, imports break!

The Solution:

# Combine all files into one before obfuscating
obfuslite combine main.py --obfuscate

# Creates a single, self-contained file that works perfectly!

CLI Usage:

# Basic combine
obfuslite combine main.py

# Combine with custom output
obfuslite combine main.py -o my_app.py

# Combine and auto-obfuscate
obfuslite combine main.py --obfuscate -t fast_xor -l 2

# Advanced obfuscation
obfuslite combine main.py --obfuscate -t quantum -l 3

GUI Usage:

1. Launch GUI: obfuslite gui
2. Go to "Combine Files" tab
3. Select your main Python file
4. Click "Auto-Detect Related Files"
5. Configure obfuscation settings
6. Click "Combine Files"
7. Get a single, working obfuscated file!

Benefits:

• ✅ No Import Issues - Single file, no module dependencies
• ✅ PyInstaller Ready - Perfect for creating executables
• ✅ Auto-Detection - Finds all related Python files automatically
• ✅ Smart Import Filtering - Removes local imports, keeps external ones
• ✅ Progress Tracking - Real-time status in GUI
• ✅ Error Prevention - Syntax validation before obfuscation

🖥️ Enhanced GUI Features

Multi-File Batch Processing

• Add Files/Directories: Select multiple Python files or entire directories
• Real-time Progress: Track processing status for each file
• Error Handling: Detailed error reporting and recovery
• ZIP Export: Create compressed archives of results
• Backup Management: Automatic backup of original files

Project Management

• Save Projects: Store complex multi-file configurations as .pyobf files
• Load Projects: Resume work on saved projects
• File Tracking: Monitor file status and modifications
• Team Collaboration: Share projects and configurations

Code Analysis & Intelligence

• Complexity Analysis: Analyze code structure and complexity
• Smart Recommendations: Get technique suggestions based on code
• Performance Guidance: Optimize settings for your specific needs
• Metrics Visualization: View detailed code statistics

Comparison Tools

• Side-by-Side View: Compare original vs obfuscated code
• Statistical Analysis: Size ratios, complexity metrics
• Export Reports: Generate comparison reports for documentation

Template System

• Save Configurations: Create reusable obfuscation templates
• Quick Apply: One-click application of saved settings
• Team Standards: Maintain consistent obfuscation across projects

🔧 Usage with PyInstaller

Single File Workflow

1. Obfuscate your code using ObfusLite
2. Save the standalone code to a .py file
3. Compile with PyInstaller:

   pyinstaller --onefile obfuscated_app.py
   

Batch Processing Workflow

1. Use GUI Batch Processing to obfuscate multiple files
2. Export as ZIP for organized distribution
3. Compile main entry point:

   pyinstaller --onefile main_obfuscated.py
   

The resulting .exe will contain your obfuscated code that reconstructs itself at runtime.

📊 Performance Comparison

Technique	Speed	Security	Size Ratio	Best For
fast_xor	⚡⚡⚡⚡⚡	🛡️🛡️🛡️	1.2x	Development, Testing
fast_base64	⚡⚡⚡⚡⚡	🛡️🛡️	1.4x	Quick Protection
fast_rotation	⚡⚡⚡⚡	🛡️🛡️🛡️	1.3x	Balanced Security
quantum	⚡⚡	🛡️🛡️🛡️🛡️🛡️	2.1x	Maximum Security
neural	⚡	🛡️🛡️🛡️🛡️🛡️	2.8x	Research, High-Value
tensor	⚡	🛡️🛡️🛡️🛡️🛡️	3.2x	Enterprise Security

GUI vs CLI Performance

• GUI Batch Processing: 50% faster for multiple files
• Project Management: Saves 80% setup time for complex projects
• Template System: Reduces configuration time by 90%

📚 Obfuscation Techniques Explained

Quantum-Inspired Encoding

• Maps binary data to quantum state representations
• Uses quantum gate operations (Hadamard, Pauli-X, Y, Z)
• Applies superposition and entanglement concepts
• Encodes data in complex number amplitudes

DNA Sequence Mapping

• Converts code to DNA base sequences (A, T, G, C)
• Applies genetic mutations for additional obfuscation
• Uses codon tables for amino acid encoding
• Includes intron sequences for steganographic hiding

Fractal Pattern Encoding

• Utilizes mathematical fractals (Mandelbrot, Julia sets)
• Applies chaos theory and strange attractors
• Maps data to fractal coordinates
• Uses Lorenz attractor and Sierpinski triangle

Neural Network Weight Encoding

• Stores code as neural network weights and biases
• Uses multiple layer architectures
• Applies activation functions for transformation
• Includes forward and backward propagation concepts

Steganographic Hiding

• Hides code in innocent-looking data:
  • Lorem ipsum text
  • Configuration files
  • Mathematical constants
  • Fake database records
  • Poetry structures

Runtime Reconstruction

• Creates self-modifying code
• Uses bytecode assembly
• AST (Abstract Syntax Tree) reconstruction
• Dynamic import mechanisms
• Function composition techniques

Tensor Encoding

• Multi-dimensional array operations
• Matrix multiplication transformations
• Singular Value Decomposition (SVD)
• Fourier and wavelet transforms
• Linear algebra operations

⚙️ Configuration Options

Obfuscation Parameters

• Technique: Choose from 7 available methods
• Layers: Apply 1-10 layers of obfuscation
• Seed: Set random seed for reproducible results
• Compression: Optional output compression

Security Levels

• Basic (1-2 layers): Fast obfuscation for simple protection
• Standard (3-5 layers): Balanced security and performance
• High (6-10 layers): Maximum security for sensitive code

🎮 Examples & Workflows

Basic Example

from obfuslite import quick_obfuscate

code = '''
def hello_world():
    print("Hello from ObfusLite!")
    return "Protected!"

if __name__ == "__main__":
    result = hello_world()
    print(f"Result: {result}")
'''

# One-line obfuscation
protected_code = quick_obfuscate(code, technique='fast_xor', layers=2)

# Save and run
with open('protected.py', 'w') as f:
    f.write(protected_code)

Batch Processing Example

from obfuslite import Obfuscator
import os

obfuscator = Obfuscator()

# Process all Python files in a directory
for root, dirs, files in os.walk('my_project'):
    for file in files:
        if file.endswith('.py'):
            file_path = os.path.join(root, file)

            with open(file_path, 'r') as f:
                code = f.read()

            result = obfuscator.obfuscate(code, technique='fast_xor')
            standalone = obfuscator.create_standalone_file(result)

            output_path = file_path.replace('.py', '_protected.py')
            with open(output_path, 'w') as f:
                f.write(standalone)

GUI Workflow Examples

Project-Based Workflow

1. Launch GUI: obfuslite gui
2. Create new project in Project Management tab
3. Add files using Batch Processing tab
4. Configure obfuscation settings and save as template
5. Process all files and export as ZIP
6. Save project for future use

Quick Batch Processing

1. Go to Batch Processing tab
2. Click "Add Directory" and select your project folder
3. Choose "fast_xor" technique for speed
4. Set output directory
5. Click "Process All Files"
6. Export results as ZIP archive

Code Analysis Workflow

1. Go to Code Analysis tab
2. Load your Python file
3. Click "Analyze Code"
4. Review recommendations
5. Apply suggested settings in other tabs

See examples/obfuslite_basic_usage.py for comprehensive examples including:

• Basic obfuscation/deobfuscation
• Advanced features demonstration
• PyInstaller preparation
• Technique comparison
• GUI workflow examples

🛡️ Security Considerations

What This Library Protects Against

• ✅ Casual code inspection
• ✅ Simple reverse engineering attempts
• ✅ Automated code analysis tools
• ✅ Source code theft
• ✅ Algorithm discovery

Limitations

• ❌ Not cryptographically secure against determined attackers
• ❌ Runtime performance overhead due to reconstruction
• ❌ Increased file size due to obfuscation data
• ❌ Debugging becomes more difficult

Best Practices

1. Use GUI for complex projects - Leverage batch processing and project management
2. Save templates for consistent team workflows
3. Combine multiple techniques for enhanced security
4. Use high layer counts for sensitive code
5. Test thoroughly before deployment
6. Backup originals when using batch processing

🔧 Extending ObfusLite

Adding New Techniques

1. Create a new encoder class inheriting from BaseEncoder
2. Implement encode() and decode() methods
3. Register with the obfuscator core
4. Add to GUI dropdown menu

Example:

from obfuslite.encoders.base import BaseEncoder

class MyCustomEncoder(BaseEncoder):
    def encode(self, data: str) -> Dict[str, Any]:
        # Your encoding logic here
        pass

    def decode(self, encoded_data: Any, metadata: Dict[str, Any]) -> str:
        # Your decoding logic here
        pass

# Register the technique
from obfuslite import Obfuscator
obfuscator = Obfuscator()
obfuscator.register_technique('custom', MyCustomEncoder())

🐛 Troubleshooting

Common Issues

1. GUI Won't Start: Install PyQt6 with pip install obfuslite[gui]
2. Import Errors: Ensure ObfusLite is properly installed
3. Memory Issues: Use fast techniques for large files or reduce layer count
4. PyInstaller Errors: Check that all dependencies are included
5. Batch Processing Fails: Verify file permissions and output directory access

Performance Optimization

• Use GUI batch processing for multiple files (50% faster)
• Save templates to avoid reconfiguration
• Choose fast techniques for large codebases
• Use fewer layers for faster processing
• Enable ZIP compression for storage efficiency

GUI-Specific Tips

• Project Management: Save complex configurations as projects
• Template System: Create templates for different security levels
• Batch Processing: Process similar files together for efficiency
• Code Analysis: Use recommendations for optimal settings

📄 License

ObfusLite is released under the MIT License. Free for personal and commercial use.

🤝 Contributing

Contributions are welcome! Priority areas:

• Enhanced GUI features - New tabs, visualizations, workflows
• New obfuscation techniques - Novel encoding algorithms
• Performance optimizations - Faster processing, lower memory usage
• Better PyInstaller integration - Seamless executable creation
• Documentation improvements - Tutorials, examples, guides

🔗 Links

• Documentation: GUI Features Guide
• Examples: examples/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

📞 Support

For issues, questions, or feature requests:

• 🐛 Bug Reports: Create an issue on GitHub
• 💡 Feature Requests: Use GitHub Discussions
• 📚 Documentation: Check the GUI Features Guide
• 🎮 Examples: Run examples/obfuslite_basic_usage.py

---

ObfusLite - Professional Python Code Protection Made Simple 🛡️

Note: This obfuscation library is designed for legitimate code protection purposes. Users are responsible for complying with applicable laws and regulations in their jurisdiction.