71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# 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](main.py) or the library API via [AdvancedObfuscator()](obfuscator.py:17).
|
||
|
||
## Features
|
||
- Symbol-tree–guided renaming via [AdvancedObfuscator._build_symbol_tree()](obfuscator.py:93) and [RenameTransformer()](transformers/rename.py:10).
|
||
- String literal encryption with multi-layer XOR and Base85 unpacked at runtime via [StringEncryptor.encrypt_string()](utils/encryption.py:42) and injected expressions from [RenameTransformer.visit_Constant()](transformers/rename.py:373).
|
||
- Control-flow flattening (state machine) in [ControlFlowFlattener()](transformers/control_flow.py:10), orchestrated by [AdvancedObfuscator._flatten_control_flow()](obfuscator.py:171) and applied in [ControlFlowFlattener.visit_FunctionDef()](transformers/control_flow.py:38).
|
||
- Junk code injection during code generation in [AdvancedObfuscator._generate_final_code()](obfuscator.py:185); extra utilities in [utils/junk_gen.py](utils/junk_gen.py).
|
||
- Debug diagnostics and JSON emission through [AdvancedObfuscator.log_debug()](obfuscator.py:51), [AdvancedObfuscator.detect_issues()](obfuscator.py:60), and final write in [AdvancedObfuscator.obfuscate()](obfuscator.py:250).
|
||
|
||
## 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](main.py) with handler [main()](main.py:6).
|
||
|
||
Examples:
|
||
- Test mode (prints and executes obfuscated sample code): python [main.py](main.py) --test
|
||
- Obfuscate a file with verbose logging and default output name: python [main.py](main.py) -i path/to/app.py -v
|
||
- Obfuscate to a specific file: python [main.py](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](obfuscator.py): instantiate [AdvancedObfuscator()](obfuscator.py:17).
|
||
- Call [AdvancedObfuscator.obfuscate()](obfuscator.py:250) with a string of source code; it returns the obfuscated Python source string.
|
||
- Optionally pass debug_mode=True to [AdvancedObfuscator()](obfuscator.py:17) to emit a JSON report under ./debug/.
|
||
|
||
Minimal flow:
|
||
1) Parse to AST: [AdvancedObfuscator.obfuscate()](obfuscator.py:254)
|
||
2) Rename + encrypt: [AdvancedObfuscator._rename_and_encrypt()](obfuscator.py:142), [RenameTransformer()](transformers/rename.py:10)
|
||
3) Flatten control flow: [AdvancedObfuscator._flatten_control_flow()](obfuscator.py:171), [ControlFlowFlattener()](transformers/control_flow.py:10)
|
||
4) Generate code and inject junk: [AdvancedObfuscator._generate_final_code()](obfuscator.py:185)
|
||
|
||
## Project structure
|
||
- [main.py](main.py) – CLI interface and example/test runner.
|
||
- [obfuscator.py](obfuscator.py) – Core engine ([AdvancedObfuscator()](obfuscator.py:17)).
|
||
- [transformers/rename.py](transformers/rename.py) – Identifier renaming and string encryption ([RenameTransformer()](transformers/rename.py:10)).
|
||
- [transformers/control_flow.py](transformers/control_flow.py) – Control-flow flattener ([ControlFlowFlattener()](transformers/control_flow.py:10)).
|
||
- [utils/encryption.py](utils/encryption.py) – String encryption ([StringEncryptor()](utils/encryption.py:6)).
|
||
- [utils/junk_gen.py](utils/junk_gen.py) – Junk statements for noise.
|
||
- [utils/name_gen.py](utils/name_gen.py) – Obfuscated name generation.
|
||
- [transformers/symbol_tree.py](transformers/symbol_tree.py) – Global symbol graph for consistent renames.
|
||
- [transformers/class_analyzer.py](transformers/class_analyzer.py), [transformers/attribute_transformer.py](transformers/attribute_transformer.py), [transformers/class_mapper.py](transformers/class_mapper.py) – Class/method/attribute support utilities.
|
||
|
||
## Debugging and diagnostics
|
||
- Enable debug mode by constructing [AdvancedObfuscator(debug_mode=True)](obfuscator.py:17).
|
||
- Transformation events are collected through [AdvancedObfuscator.log_debug()](obfuscator.py:51).
|
||
- Issue detection (e.g., name collisions) is performed in [AdvancedObfuscator.detect_issues()](obfuscator.py:60).
|
||
- A comprehensive JSON report is written from [AdvancedObfuscator.obfuscate()](obfuscator.py:265) 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()](transformers/control_flow.py:46).
|
||
- 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. |