6.2 KiB
6.2 KiB
OMG-Fuscator
Advanced Python code obfuscator for renaming identifiers, encrypting strings, flattening control flow, and injecting junk code.
Quick start: use the CLI in main.py or the library API via AdvancedObfuscator().
Features
- Symbol-tree–guided renaming via AdvancedObfuscator._build_symbol_tree() and RenameTransformer().
- String literal encryption with multi-layer XOR and Base85 unpacked at runtime via StringEncryptor.encrypt_string() and injected expressions from RenameTransformer.visit_Constant().
- Control-flow flattening (state machine) in ControlFlowFlattener(), orchestrated by AdvancedObfuscator._flatten_control_flow() and applied in ControlFlowFlattener.visit_FunctionDef().
- Junk code injection during code generation in AdvancedObfuscator._generate_final_code(); extra utilities in utils/junk_gen.py.
- Debug diagnostics and JSON emission through AdvancedObfuscator.log_debug(), AdvancedObfuscator.detect_issues(), and final write in AdvancedObfuscator.obfuscate().
Requirements
- Python 3.9+ (uses ast.unparse)
- No external dependencies; standard library only
Installation
- Clone or download this repository into a working directory.
- Optional: create and activate a virtual environment.
- There are no packages to install.
CLI usage
The CLI entrypoint is main.py with handler main().
Examples:
- Test mode (prints and executes obfuscated sample code): python main.py --test
- Obfuscate a file with verbose logging and default output name: python main.py -i path/to/app.py -v
- Obfuscate to a specific file: python main.py -i path/to/app.py -o path/to/app_obf.py
Arguments:
- -i, --input: Input .py file path
- -o, --output: Output file path (default: input_stem_obfuscated.py)
- -v, --verbose: Enable verbose console logs
- --test: Run built-in demo
Library usage
- Import from obfuscator.py: instantiate AdvancedObfuscator().
- Call AdvancedObfuscator.obfuscate() with a string of source code; it returns the obfuscated Python source string.
- Optionally pass debug_mode=True to AdvancedObfuscator() to emit a JSON report under ./debug/.
Minimal flow:
- Parse to AST: AdvancedObfuscator.obfuscate()
- Rename + encrypt: AdvancedObfuscator._rename_and_encrypt(), RenameTransformer()
- Flatten control flow: AdvancedObfuscator._flatten_control_flow(), ControlFlowFlattener()
- Generate code and inject junk: AdvancedObfuscator._generate_final_code()
Project structure
- main.py – CLI interface and example/test runner.
- obfuscator.py – Core engine (AdvancedObfuscator()).
- transformers/rename.py – Identifier renaming and string encryption (RenameTransformer()).
- transformers/control_flow.py – Control-flow flattener (ControlFlowFlattener()).
- utils/encryption.py – String encryption (StringEncryptor()).
- utils/junk_gen.py – Junk statements for noise.
- utils/name_gen.py – Obfuscated name generation.
- transformers/symbol_tree.py – Global symbol graph for consistent renames.
- transformers/class_analyzer.py, transformers/attribute_transformer.py, transformers/class_mapper.py – Class/method/attribute support utilities.
Debugging and diagnostics
- Enable debug mode by constructing AdvancedObfuscator(debug_mode=True).
- Transformation events are collected through AdvancedObfuscator.log_debug().
- Issue detection (e.g., name collisions) is performed in AdvancedObfuscator.detect_issues().
- A comprehensive JSON report is written from AdvancedObfuscator.obfuscate() under ./debug/.
Notes and limitations
- Control-flow flattening may increase code size and reduce performance for small functions; tiny functions are skipped in ControlFlowFlattener.visit_FunctionDef().
- Obfuscation can impact reflection, dynamic imports, serialization, or frameworks that rely on exact names.
- String encryption decrypts at runtime; extremely performance‑sensitive hot paths may incur overhead.
- Avoid obfuscating code that uses eval/exec on source strings that expect original identifiers.
License
Specify a license for this project (e.g., MIT). If adding a LICENSE file, reference it here.
Documentation
Generate Doxygen HTML docs for this codebase.
-
Prerequisites (install one of the following):
- Windows (chocolatey): choco install doxygen.install
- macOS (Homebrew): brew install doxygen
- Linux (apt): sudo apt-get update && sudo apt-get install doxygen
-
Generate:
- From the repository root, run: doxygen Doxyfile
- Open the generated site: docs/html/index.html
-
Notes:
- Configuration extracts Python docstrings and Markdown.
- Source browsing and inline sources are enabled.
- Key modules documented include: