minimax-python-obfuscator 1.0.4
Advanced Python obfuscation tool with memory, binary, and machine code protection
Requires Python: >=3.7
Keywords: python, obfuscation, security, code protection, pyinstaller, anti-debugging

# Python Multi-Level Obfuscator

A sophisticated Python code obfuscation tool featuring a modern liquid glass GUI and three levels of protection: memory-level, binary-level, and machine code-level obfuscation.

![Python Obfuscator](https://img.shields.io/badge/Python-3.7+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)

## 🚀 Features

### Multi-Level Protection

#### Memory-Level Obfuscation
- **Dynamic code loading** and execution
- **Runtime memory encryption/decryption**
- **Anti-debugging techniques**
- **Code injection obfuscation**
- **Variable and function name randomization**
- **String literal encryption**
- **Control flow flattening**
- **Dead code insertion**

#### Binary-Level Obfuscation
- **PyInstaller integration** for executable creation
- **Binary packing and encryption**
- **Resource protection**
- **Anti-tampering mechanisms**
- **Signature verification**
- **Integrity checking**
- **Debug detection**
- **UPX compression support**

#### Machine Code-Level Obfuscation
- **C extension compilation**
- **CPU instruction obfuscation**
- **Control flow flattening**
- **Assembly wrapper generation**
- **Opcode-level junk insertion**
- **Anti-debugging assembly**

### Modern Liquid Glass GUI
- **Glass morphism effects** with transparency
- **Rounded corners** and smooth animations
- **Gradient backgrounds** with blur effects
- **Responsive design** for all screen sizes
- **Real-time progress tracking**
- **Configuration management**
- **Batch processing support**

### Advanced Features
- **Code validation and analysis**
- **Configuration profiles**
- **Comprehensive reporting**
- **Backup and recovery**
- **Multi-platform support**

## 📦 Installation

### Prerequisites
- Python 3.7 or higher
- pip (Python package manager)

### Install Dependencies
```bash
cd code/obfuscator
pip install -r requirements.txt
```

### Optional Dependencies
```bash
# For executable compression (Linux)
sudo apt install upx-ucl

# For Windows executable creation
pip install pywin32

# For macOS specific features
pip install pyobjc
```

## 🎯 Quick Start

### GUI Mode
```bash
python run.py gui
# or
python main.py
```

### Command Line Mode
```bash
# Obfuscate a file
python run.py obfuscate input.py -o output/

# Validate a file
python run.py validate input.py

# Run demo
python run.py demo
python run.py demo --quick
```

## 📋 Usage Examples

### 1. Basic Obfuscation
```python
from main import ObfuscationEngine, ObfuscationConfig
from utils.validation_utils import CodeValidator

# Load configuration
config = ObfuscationConfig()

# Create engine
engine = ObfuscationEngine(config)

# Obfuscate file
results = engine.obfuscate_file('my_script.py', 'output_dir')
```

### 2. Custom Configuration
```python
# Modify configuration
config.set("memory_level", "rename_variables", True)
config.set("binary_level", "compress_output", True)
config.set("machine_level", "enabled", False)

# Save configuration
config.save_config()
```

### 3. Code Validation
```python
from utils.validation_utils import CodeValidator

validator = CodeValidator()
report = validator.generate_validation_report(source_code)

# Check if suitable for obfuscation
suitable, reason = validator.is_suitable_for_obfuscation(report)
print(f"Suitable: {suitable}, Reason: {reason}")
```

## 🔧 Configuration

### Configuration File Structure
```json
{
  "obfuscation": {
    "levels": {
      "memory": {
        "enabled": true,
        "rename_variables": true,
        "encrypt_strings": true,
        "add_dead_code": true,
        "flatten_control_flow": true
      },
      "binary": {
        "enabled": true,
        "use_pyinstaller": true,
        "compress_output": true,
        "add_upx": false
      },
      "machine": {
        "enabled": false,
        "create_c_extension": false,
        "opcode_obfuscation": true
      }
    }
  }
}
```

### Configuration Profiles
The obfuscator supports multiple configuration profiles:

- **Basic**: Simple obfuscation for development
- **Standard**: Balanced protection for production
- **Advanced**: Maximum protection for sensitive code

## 🎨 GUI Components

### Main Interface
- **File Selection Panel**: Browse and select Python files
- **Obfuscation Level Selector**: Choose protection levels
- **Configuration Panel**: Adjust settings
- **Progress Monitor**: Real-time obfuscation progress
- **Output Viewer**: View results and logs

### Settings Tabs
- **Memory Settings**: Configure memory-level obfuscation
- **Binary Settings**: Configure binary-level obfuscation
- **Machine Settings**: Configure machine-level obfuscation
- **Advanced Options**: Additional configuration

## 🛡️ Security Features

### Anti-Debugging
- **PEB BeingDebugged flag detection**
- **Windows API debugging checks**
- **Timing-based detection**
- **Memory protection analysis**

### Anti-Tampering
- **Digital signature verification**
- **Resource integrity checking**
- **Runtime validation**
- **Checksum verification**

### Code Protection
- **String encryption**
- **Variable name randomization**
- **Control flow obfuscation**
- **Dead code injection**

## 📊 Performance

### Obfuscation Levels Comparison
| Level | Protection | Performance Impact | Use Case |
|-------|------------|-------------------|----------|
| Memory | Medium | Low | Development, internal tools |
| Binary | High | Medium | Production applications |
| Machine | Maximum | High | Security-critical code |

### Supported File Sizes
- **Memory-level**: Up to 10MB
- **Binary-level**: Up to 100MB
- **Machine-level**: Up to 5MB

## 🔍 Validation

The obfuscator includes comprehensive code validation:

### Syntax Validation
- Python syntax checking
- AST parsing validation
- Error reporting

### Security Analysis
- Suspicious pattern detection
- Secret/hardcoded credential detection
- Malicious code identification

### Complexity Analysis
- Function count
- Class count
- Variable count
- Line count
- Dependency analysis

## 🐛 Troubleshooting

### Common Issues

#### Import Errors
```bash
# Install missing dependencies
pip install -r requirements.txt
```

#### GUI Not Displaying
```bash
# Set display environment (Linux)
export DISPLAY=:0

# Or use command line mode
python run.py obfuscate input.py
```

#### PyInstaller Errors
```bash
# Install PyInstaller
pip install pyinstaller

# Update PyInstaller
pip install --upgrade pyinstaller
```

### Debug Mode
```bash
# Run with debug output
python run.py --debug obfuscate input.py
```

## 📈 Advanced Usage

### Batch Processing
```python
import os
from pathlib import Path

# Process multiple files
input_dir = Path("input_files")
output_dir = Path("output_files")

for py_file in input_dir.glob("*.py"):
    results = engine.obfuscate_file(str(py_file), str(output_dir))
    print(f"Processed {py_file.name}: {'Success' if results['success'] else 'Failed'}")
```

### Custom Obfuscation Pipeline
```python
from obfuscators.memory_obfuscator import MemoryObfuscator
from obfuscators.binary_obfuscator import BinaryObfuscator
from obfuscators.machine_obfuscator import MachineCodeObfuscator

# Custom pipeline
memory_obf = MemoryObfuscator()
binary_obf = BinaryObfuscator()
machine_obf = MachineCodeObfuscator()

# Step 1: Memory obfuscation
protected_code = memory_obf.create_protected_module(source_code)

# Step 2: Create temporary file
temp_file = "temp_protected.py"
with open(temp_file, 'w') as f:
    f.write(protected_code)

# Step 3: Binary obfuscation
binary_obf.create_protected_executable(temp_file, "protected_app")

# Step 4: Machine obfuscation (optional)
machine_obf.create_comprehensive_protection(protected_code, "protected_extension")
```

## 🔗 API Reference

### Main Classes

#### `ObfuscationEngine`
```python
class ObfuscationEngine:
    def __init__(self, config: ObfuscationConfig)
    def obfuscate_file(self, input_file: str, output_dir: str) -> Dict[str, str]
    def set_progress_callback(self, callback)
    def set_status_callback(self, callback)
```

#### `MemoryObfuscator`
```python
class MemoryObfuscator:
    def __init__(self)
    def obfuscate_source(self, source_code: str) -> str
    def create_protected_module(self, source_code: str) -> str
    def generate_execution_wrapper(self, code: str) -> str
```

#### `BinaryObfuscator`
```python
class BinaryObfuscator:
    def __init__(self, output_dir: str = "obfuscated_binary")
    def create_protected_executable(self, script_path: str, output_name: str) -> bool
    def build_with_pyinstaller(self, script_path: str, output_name: str) -> bool
```

#### `MachineCodeObfuscator`
```python
class MachineCodeObfuscator:
    def __init__(self)
    def create_comprehensive_protection(self, python_code: str, output_name: str) -> bool
    def generate_c_extension(self, python_code: str) -> str
```

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

### Development Setup
```bash
# Clone repository
git clone <repository-url>
cd code/obfuscator

# Install development dependencies
pip install -r requirements.txt
pip install pytest black flake8

# Run tests
python -m pytest

# Format code
black .
flake8 .
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

### Documentation
- [API Reference](docs/api.md)
- [Configuration Guide](docs/configuration.md)
- [Examples](docs/examples/)

### Getting Help
- [Issues](https://github.com/your-repo/issues)
- [Discussions](https://github.com/your-repo/discussions)
- Email: support@your-domain.com

## 🔄 Changelog

### Version 1.0.0
- Initial release
- Memory-level obfuscation
- Binary-level obfuscation
- Machine-level obfuscation
- Liquid glass GUI
- Command-line interface
- Code validation
- Configuration management

## 🙏 Acknowledgments

- Python community for excellent tools and libraries
- PyInstaller team for binary packaging
- tkinter for cross-platform GUI
- All contributors and testers

---

**Note**: This tool is designed for legitimate code protection purposes. Users are responsible for ensuring compliance with applicable laws and regulations in their jurisdiction.