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: 1) Parse to AST: AdvancedObfuscator.obfuscate() 2) Rename + encrypt: AdvancedObfuscator._rename_and_encrypt(), RenameTransformer() 3) Flatten control flow: AdvancedObfuscator._flatten_control_flow(), ControlFlowFlattener() 4) 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](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:
    • obfuscator.py
    • transformers/rename.py
    • transformers/control_flow.py
    • transformers/symbol_tree.py
    • transformers/class_analyzer.py
    • transformers/class_mapper.py
    • transformers/attribute_transformer.py
    • utils/encryption.py
    • utils/junk_gen.py
    • utils/name_gen.py