Pyarmor Documentation

PyArmor is a command-line tool designed to obfuscate Python scripts. It provides several layers of protection for Python code, including:

• Code Object Obfuscation: Protects constants and literal strings.
• Runtime Obfuscation: Obfuscates the co_code of each function (code object) during execution.
• Memory Protection: Clears f_locals of frames immediately after a code object completes execution.
• License Verification: Verifies a license file while the obfuscated script is running.
• Binding and Expiration: Allows binding obfuscated scripts to specific machines or setting expiration dates.

PyArmor supports Python 2.6, 2.7, and Python 3.

PyArmor is a command-line tool used to obfuscate Python scripts, bind them to specific machines, or set expiration dates. It protects code through several mechanisms:

• Obfuscating code objects to protect constants and literal strings.
• Obfuscating the co_code of each function (code object) at runtime.
• Clearing f_locals of a frame immediately after a code object completes execution.
• Verifying license files during script execution.

Pyarmor documentation is organized into five main parts to assist users at different stages of expertise:

• Part 1: Tutorials: Step-by-step instructions for obfuscating Python scripts and packages. Recommended for new users. Includes a getting-started guide.
• Part 2: How To: Advanced recipes for addressing specific problems and use-cases. Assumes existing knowledge of Python.
• Part 3: References: Detailed information on key concepts, man pages, and configurations.
• Part 4: Topics: In-depth background information and explanations of how Pyarmor works.
• Part 5: Licenses: Information regarding the EULA, different license types, and purchasing instructions.

Pyarmor is a command line tool used to obfuscate Python scripts. It allows you to balance security and performance through various methods, including:

• Seamless Replacement: Obfuscated scripts are still .py files that can replace originals.
• Irreversible Obfuscation: Renaming functions, methods, classes, variables, and arguments, or converting Python functions to optimized C binaries.
• License Binding: Binding obfuscated scripts to a fixed machine or setting expiration dates.
• Themida Protection: Protecting scripts using Themida (Windows only).

PyArmor provides security through a two-level obfuscation process:

1. Function-level obfuscation: Each individual function within a module is obfuscated.
2. Module-level obfuscation: The entire module file is obfuscated.

At runtime, only the currently called function is restored. As soon as the code object completes execution, it is re-obfuscated. This prevents attackers from using a C debugger to trace and capture the entire code structure at once, as only a small piece of the code object is available in plain text at any given time.

The PyArmor trial version is 'Free To Use But Restricted'. Key limitations include:

• Script Size: Cannot obfuscate large scripts.
• Privacy: Scripts obfuscated by the trial version are not private; anyone can generate a license file for them.
• Dynamic Libraries: Cannot download the latest dynamic libraries for extra platforms (only old versions are available).
• Modes: The 'super plus' mode is unavailable.
• Commercial Use: Use for commercial products is prohibited without permission.

Pyarmor protects Python source code by transforming it into a specialized encrypted format. Instead of relying on standard Python import mechanisms which leave bytecode vulnerable to decompilation, Pyarmor:

1. Compiles the source into a Code Object.
2. Wraps the bytecode in a try...finally block.
3. Injects calls to __armor_enter__ at the start and __armor_exit__ at the end of code blocks.
4. Encrypts the modified bytecode and constants.
5. Generates a valid Python script that calls a bootstrap function __pyarmor__ to restore and execute the code in memory.

This approach provides security comparable to protecting C binaries by operating at the bytecode level and implementing anti-debugging/anti-tamper checks within the __armor_enter__ routine.

Pyarmor uses irreversible obfuscation to protect Python scripts. However, there is a direct trade-off between security levels and execution performance. Higher security settings generally increase the overhead of the obfuscated script.

Security Limitations:

• Pyarmor is not primarily designed for memory protection or anti-debugging.
• While the pyarmor_runtime binary extension is difficult to trace via a debugger, a debugger might still be used to bypass runtime key verification.
• For advanced runtime memory protection and anti-debug features, refer to the specific protection documentation.

When you obfuscate a script (e.g., foo.py) using PyArmor, the output in the dist directory contains the obfuscated script and several 'Runtime Files' required for execution. The original script can be replaced by the obfuscated version seamlessly as long as the runtime files are in the Python path.

Typical output files in dist/:

• foo.py: The obfuscated script.
• pytransform.py: Python runtime module.
• _pytransform.so (Linux), _pytransform.dll (Windows), or _pytransform.dylib (macOS): The dynamic library.
• pytransform.key: Runtime key.
• license.lic: The license file used for verification.

To install the web interface for PyArmor, use the following command:

pip install pyarmor-webui