Python-Obfuscation/README.md

# 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.
## 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](Doxyfile)
  - Open the generated site: [docs/html/index.html](docs/html/index.html)

- Notes:
  - Configuration extracts Python docstrings and Markdown.
  - Source browsing and inline sources are enabled.
  - Key modules documented include:
    - [obfuscator.py](obfuscator.py)
    - [transformers/rename.py](transformers/rename.py)
    - [transformers/control_flow.py](transformers/control_flow.py)
    - [transformers/symbol_tree.py](transformers/symbol_tree.py)
    - [transformers/class_analyzer.py](transformers/class_analyzer.py)
    - [transformers/class_mapper.py](transformers/class_mapper.py)
    - [transformers/attribute_transformer.py](transformers/attribute_transformer.py)
    - [utils/encryption.py](utils/encryption.py)
    - [utils/junk_gen.py](utils/junk_gen.py)
    - [utils/name_gen.py](utils/name_gen.py)