Protect Python Project by PyProtector

--With PyProtector, a Python extension package, Developer has capability to protect python project to bytecode level, which effective to prevent attacker to decompile python project.

Introduction to Python

Python is a very popular general-purpose interpreted, interactive, object-oriented, and high-level programming language, easy to read and cross platform support with rich library available, Python is very highly in demand and it has been widely used in various areas of applications such as Machine Learning, Artificial Intelligence, web development, IoT, and more area. Many of major companies select and use Python to develop websites, software components, and applications or to work with Data Science, AI, and ML technologies.

Python file extension name

Python file extension	Description
py	Python script source code
pyc	Python byte code (compiled script)
pyd etc.	dll in windows,
pyz	Python script archive file
pyx	Cython source code to be converted to C/C++

Python Security:

How to protect the Python script (py) before distribute or deploy to customer premise

As Python is an interpreted language; When user execute the python project, The Python Interpreter require to compiles the python source code (pyfile) to bytecode (pyc) and executed in the python VM. Even the developer may deploy the bytecode (pyc file) in the user premise only without use python script file (py ) file, but it is not difficult to third party attacker to decompile and reverse the bytecode (pyc file) to the original py file, with the Python decompile tool (for example, uncompyle6 . so, it is not good idea to deploy the bytecode file to customer premise without additional protection/encryption. It is always the challenge to Python developer when they distribute their Python project to users, especially when deployed python project in customer premise.

The Python interpreter execution consisted 2 phase when execute the python source file:

1. Python source code (py file) is compiled into byte code (pyc file)

2. Python byte codes (pyc file) executed in the Python Virtual Machine (PYM)

When a Python project executed, Python interpreter will check if valid pyc file available,

if the pyc file is valid, execute the pyc file;

If the pyc file doesn't existed, or the python script py file has been update, the python interpreter will recompile the py file to new pyc file and execute it.

Bytecode generation saves repeated compilation time; In case python version on the machine changed, the Bytecode will be regenerated (pyc file is much dependent with python version on the machine execution).

Typical protection method to Python Project

1. Obfuscate the python script file:

   Obfuscate and change the functions name, variable names; (usually obfuscation is not effective way to prevent the third party to decompile your python script, it just makes reverse process harder and spend longer time.)

2. Archive and pack the python script file into exe file;

   use py2exe, pyinstaller or other similar packer tool to archive/pack to the exe file, only for windows environment;

   (the challenge would be, it is easier to be decompiled by use of python reverse tool, such as pyinstxtractor to reverse to the pyc file, and use the decompiler to decompile the pyc file and get original source py source code )

3. Compile the python script file to be .C file and compile to dynamic link library (.so in linux and .pyd in windows). for example, use the cython to implement (compile) the process above;

For the python web project deployed and implemented in customer premise, usually, the developer select the 3rd way to protect python source code being used illegally;

Virbox Protector: Python extension package (PyProtector)

With Virbox Protector, Developer may have 2 way to protect Python project:

1. For normal python project, no special security requirement, Developer may use DS Protector, a plug in unit, with Virbox Protector native license to protect Python project;

2. For those Python project which require highly security to protect py file, Virbox provides "Python extension package (PYProtector)" and support developer to protect python file to "Bytecode" level. Compare with other Python protection solution in the market, Virbox Python protection solution provides the most secured performance to the python project. with Virbox Python extension package (PY Protector), developer may protect python project to bytecode level to prevent the Python file from being decompiled and being tampered. Python extension package (PyProtector) are much suitable and best choice to those Python project deployed in user premise.

3. It is require developer to download the "Python extension package (PY Protector) and install "PYProtector" with Virbox Protector. in this document, we focus to introduce the whole protect process with Virbox Python extension package. ( Python license required)

Version release (PyProtector)

Start from Release version 3.2.xxxx, Virbox Protector introduce the enhanced Python protection solution, with new extension package: pyprotector , with pyprotector, it increase the security to protect the Python script. Compare with using DS Protector tool previously, the pyprotector, protect the python project to bytecode level, which guaranty the python script can not being decompiled and reversed directly. and make sure your python project security when deployed in customer premise.

pyprotector use dynamic encryption/decryption technology to protect Python script file, that means pyprotector encrypt original python script file py file and decrypt these script file only when execution, and re encrypt the script file when execution completed. and pyprotector also use multiple mechanism to verify script, code object etc.

Solution advantage

1. Protect/encrypt the python script in bytecode level

When Python application executed, no python script (source code) can be exposure, when the third party use python decompiler to decompile in running environment. it can not get correct bytecode and decompiled to source code accordingly.

2. Python bytecode has been encrypted and only being decrypted before execute, and it will be re encrypted the bytecode after executed. to prevent being dump to get the script file from the memory.

3. Compatibility: In most of cases, the encrypted python file (.py file) is compatible with original .py file and can be replaced seamlessly;

4. Compatible with multiple version of Python execution environment: the protected python project can be executed in the 3.6~3.11 version released.

5.The condition of Seamless replacement: The Python interpreter can load the C extension library of virbox_pyruntime correctly, with condition of writable right to virbox_pyruntime library;

6. Comparison between DSProtector & PYProtector：

previously, when developer use the Virbox Protector to protect python project, the plugin tool used is DSProtector, here we compare and list the difference between DSProtector and PYProtector:

	DsProtector	PyProtector
Mechanism	when developer use dsprotector to protect Python script file, it is mandatory to encrypt/protect the python.exe, enable dsprotector and replace the python.exe with encrypted Python.exe when execution.	No need to encrypt python.exe
Security	Possibility to dump the python script code in memory;	code object (binary) in memory when execution. impossible to dump.

Supported Python environment

1. Applicable Python project version to be protected：

Python version: 3.6-3.11

Support to protect/encrypt the py file only, it doesn't support to protect pycbytecode file.

2. The workable Python version to protected python project ：

Python 3.6-3.11

Note: If the operation system doesn't support python 3.8, then it will failed to encrypt the python py file

Operation System Supported

Operation System	x86	x64	arm32	arm64
Windows	✔️	✔️	N/A	not support yet
Linux	✖️	✔️	✔️	✔️
macOS	N/A	✔️	N/A	not support yet,

How does it works (Mechanism)

The execution process of protected python project

1. Load the module: virbox_pyruntime

2. Call the virbox functions in the virbox_pyruntime module,

   To verify whether the python script file has been modified or not;

   Fix the bytecode encryption/decryption functions, bytecode string/attribute decryption functions, verify functions, etc.

3. Execute the code objective;

4. Decrypt the bytecode body at the beginning of function;

5. Encrypt the bytecode body at the ending of function;

Basic Feature to protect Python project (Python Options Tab)

1. Drag Python folder into Virbox Protector, and then Developer select those py file which developer want to protect/encrypt in the Python tab;

2. Developer click to select those protection options to your python script in Pyhon Options tab:

Functions Verification (Check)

Verify the functions when execution to prevent the functions being replaced in memory dynamically;

Python Module Verification (Check)

Verify the Python module imported when execution to prevent being replaced; and prevent the unprotected python module being imported;

String Encryption

Encrypt the those critical plaintext string contained in the Python script, to increase the barrier for reverse engineering;

Attribute Encryption

To encrypt the class attribute of the Python code (object);

Local Variable Obfuscation

Obfuscate the local variable in the Python functions and rename it to meaningless string; to prevent to track python code logic by variable name;

Bytecode Dynamic Encryption

With Bytecode dynamic encryption feature, the encrypted bytecode will be decrypted when execute the functions only;

Tampering Proof

Block the protected Python script to add additional code (allow to add "code comments")

Code Object Name Obfuscation

Rename the code object, to prevent the attacker to trace code logic;

Getting Started (Protection process)

To protect Python script (py file), when you installed the Virbox Protector in your machine, it is necessary to install additional Python extension package and install in your machine.

Installation & Setup

Prerequisite:

1. Virbox Protector release version or Trial version >3.2.2.xxxx;

2. contact Virbox support team or download by yourself to get Python extension zip package;

Note:

If the Virbox protector installed in your machine is lower than 3.2.2, please download the latest version Virbox Protector installation package（for trial user, download the latest version of Virbox Protector Trial Package) and install Virbox Protector to your machine.

Open Virbox Protector GUI tools, and drag the whole Python folder (not only python file) into Virbox Protector GUI tools, then, additional "Python Files" tab will be added in the Virbox Protector GUI tools,

click:

Install extension package

to install python extension package,

Another way to download Virbox Protector Python extension package

Please go to Virbox Protector website and install it via Virbox Protector GUI tools;

After complete the installation the python extension package, you can use Virbox Protector to protect your Python Script in bytecode level:

Use Virbox Protector GUI tool to protect Python

Go to the installation directory of the Virbox Protector, entry the sub directory \bin\

Execute virboxprotector.exe, login with email and password;

Drag the **whole Python folder(**which folder contained the python.exe and correspondent py file) into Virbox Protector GUI tools:

then, after parsing your Python project, Virbox Protector GUI will prompt message and new Python tab will added:

Developer can select and set protection option in following tabs.

1. Python Options

   select the py file need to be protected in this tab;

2. Protection Option tabs

   Select the protection option to those selected py files, all protection feature can be selected here.

3. Click “Protect Selected Project" in the menu, to start python project protection process, then

   a new protected python project will be generated under specified folder:

   Python simple_protected

   a new package has been generated in this folder: virbox_pyruntime

Note:

1. When you execute the protected python project, it will dependence with c extension library contained in this virbox_pyruntime package generated.

2. Python file Password:

​ 1) When there are dependencies between encrypted py files, if the password settings of the two protection/encryption are different, the protected py files cannot be used compatible, if the password settings are the same, the encrypted PY file can be used;

​ 2) When there is no dependency between encrypted py files, no matter for the password settings of the two protections are the same or not, the protected py file can be used normally.

Note：
1.In case the `\protected` folder missing in the python file located folder, then the python project execution will be failed.
2.It is recommend to put the `virbox_pyruntime` folder under the folder of python environmenet. then it is not necessary to copy the folder `virbox_pyruntime` under the protected python folder.

Use Virbox Protector CLI tool to protect Python

Virbox Protector supports developer to protect python project with CLI also, the on default pyprotector CLI tools:

pyprotector_con

PYProtector CLI location, develop find the PYProtector CLI tool at:

Windows:
Commercial release：C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe
Trial package：C:\Program Files\senseshield\Virbox Protector 3 Trial\bin\pyprotector_con.exe

Linux:
Commercial release：/usr/share/virboxprotector/bin/pyprotector_con
Trial package：/usr/share/virboxprotector-trial/bin/pyprotector_con

macOS:
Commercial release：/Applications/Virbox Protector 3.app/Contents/MacOS/bin/pyprotector_con
Trial package：/Applications/Virbox Protector 3 trial.app/Contents/MacOS/bin/pyprotector_con

The CLI options:

1. The options

Options	Command	On default value
Install py extension package	--install=<zip_path>	0
Specify the python execution version for the protected py script file	--target-python-version=	0
Function check	--function-check=<value>	0
Module Check	--module-check=<value>	0
String Encryption	--str-enc=<value>	0
Attribute Encryption	--attr-enc=<value>	0
Local Variable Obfuscation	--local-var-rename=<value>	0
Bytecode Dynamic Encryption	--bc-dyn-enc=<value>	0
exclude the files by filter to protect	--excludes=	0
Output path	-o=<output_path>	0
View and list the version Python CLI tool	-V

2. Command line Sample

1）Use the CLI tool to install the Python extension pacakge

"C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe" --install=D:\Desktop\python_extension.zip

2）To exclude the py file which located at the nested folder

"C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe" <py-demo> --excludes=<py-demo>/<dirs> -o <py-demo_protected>

3）To exclude the specified nested py file,

"C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe" <py-demo> --excludes=*/demo.py -o <py-demo_protected>

or, to specify the absolute path of py file specified:

--excludes=specify the absolute path of pyfile.

4）To protect the python project (enable function check/string encryption/Bytecode dynamic encryption):

"C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe" <py-demo> --function-check=1 --str-enc=1 --bc-dyn-enc=1 -o <py-demo_protected>

5）To specify Python system version to the protected python execution environment(for example to specify the python execution version is 3.9, then the protected python project will be executed under the python version 3.9 only:

"C:\Program Files\senseshield\Virbox Protector 3\bin\pyprotector_con.exe" <py-demo> --target-python-version=3.9 -o <py-demo_protected>

Comparison the py file

Before protection (original py file)

After protection (encrypted py file)

Comparison to execution performance

No matter we use what kind of code hardening solution to protect Python script, it is always to consider and balance the python code security and python project execution performance, Here we execute the original py script (not protected) and execute the Python project which select different kind of Protection Option to protect.

see attached project execution performance comparison (in seconds)

Conclusion：

The String encryption and Attribute encryption these 2 options selected to protect and encrypt, is the most protection option which bring negative impact to execution performance. compare with other option selected. it almost no performance impact when you select the other options.

Why String encryption may bring negative impact to project execution performance: the reason is because when you select these 2 protection options, there will be many of string and attribute encryption and decryption happened to the protected python project. 

Let's take the protection of algorithm to support vector in the python as a example, we use the tools cProfile to record the time to call the function in several millions, see attached chart.