← Back to Documentation

PyConfuser - User Manual

Welcome to the PyConfuser documentation. PyConfuser is a professional-grade Python obfuscator designed by the FireflyProtector Team to defend your source code against reverse engineering and tampering.

1. Introduction to PyConfuser

PyConfuser works by transforming your Python source code into a highly complex, self-defending structure. Unlike simple minifiers or packers that can be easily reversed, PyConfuser employs advanced techniques derived from compiled language protection, adapted for Python's dynamic nature.

2. Protection Layers

PyConfuser applies a multi-staged protection pipeline. Each layer addresses a specific vector of attack.

2.1. AST-Based Transformations

We parse your code into an Abstract Syntax Tree (AST) to perform deep structural changes that are syntactically valid but semantically obscure.

  • Import Obfuscation: Hides the dependencies your script uses. Instead of seeing import requests, an attacker sees a dynamic import of an encrypted string.
  • Renaming: Variables, functions, and classes are renamed to meaningless strings (e.g., _0x1a2b).
  • Junk Code Injection: We inject "dead code" — instructions that calculate nonsensical values but never affect the program's output. This pollutes the control flow graph, making it harder for automated tools to trace the real execution path.

2.2. Control Flow Flattening

This technique destroys the structure of your code (loops, if-statements) and replaces it with a single, massive loop controlled by a state variable.

  • Effect: The original logic flow is broken into small blocks.
  • Result: An analyst cannot easily see "where" the code goes next without mentally executing the state machine.

2.3. String & Data Encryption

Plaintext strings are the easiest way to understand a program's intent. PyConfuser encrypts all string literals.

  • Algorithm: We use a combination of XOR and custom encoding schemes.
  • Runtime: The strings are decrypted only at the exact moment they are needed, and then discarded from memory if possible.

2.4. Virtualization (The "Wall of Chaos")

Our most advanced layer. We compile critical sections of your Python code into a custom, randomized instruction set.

  • Custom VM: Your code is no longer Python bytecode. It is a proprietary bytecode that runs inside a Python-based interpreter we embed in your script.
  • Chinese Variable Names: To further confuse analysis and break some western-centric analysis tools, the VM uses CJK characters for internal variables.

3. Runtime Defenses

PyConfuser doesn't just hide code; it actively defends itself.

3.1. Anti-Tamper

The script calculates checksums of its own functions at runtime. If an attacker modifies a single line (e.g., to bypass a license check), the checksum changes, and the script silently fails or crashes.

3.2. Anti-Debugging

We use Python's sys.settrace and other low-level hooks to detect if a debugger (like pdb or an IDE) is attached. If detected, the script terminates.

4. Best Practices

To get the most out of PyConfuser:

  1. Test Thoroughly: Heavy obfuscation can sometimes affect performance or compatibility. Always test the protected file in a clean environment.
  2. Protect Critical Logic: You don't need to obfuscate every UI script. Focus on the core logic, licensing, and proprietary algorithms.
  3. Keep Backups: The obfuscation process is irreversible. Always keep your original source code safe.

5. FAQ

Q: Can I use PyConfuser on .pyc files? A: No, PyConfuser requires the original .py source code to perform AST transformations.

Q: Will this slow down my script? A: Yes, all obfuscation introduces some overhead. Virtualization is the most resource-intensive. Use it selectively for high-security needs.

Q: Is it 100% uncrackable? A: No software is 100% uncrackable. Given enough time and skill, a determined human can reverse anything. PyConfuser's goal is to make that cost (in time and effort) prohibitively high.