Initial commit

README.md

@@ -0,0 +1,71 @@
+# 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.