Obfuscating Python Scripts¶

Use commandobfuscate to obfuscate python scripts. In the most simplecase, set the current directory to the location of your programmyscript.pyand execute:

pyarmorobfuscatemyscript.py

PyArmor obfuscatesmyscript.py and all the*.py in the same folder:

• Create.pyarmor_capsule.zip in theHOME folder if it doesn’t exists.
• Creates a folderdist in the same folder as the script if it does not exist.
• Writes the obfuscatedmyscript.py in thedist folder.
• Writes all the obfuscated*.py in the same folder as the script in thedist folder.
• Copy runtime files used to run obfuscated scripts to thedist folder.

In thedist folder the obfuscated scripts and all the required files aregenerated:

dist/myscript.pypytransform/__init__.py_pytransform.so/.dll/.dylib

The extra folderpytransform calledRuntime Package, it’s required torun the obfuscated script.

Normally you name one script on the command line. It’s entry script. The contentofmyscript.py would be like this:

frompytransformimportpyarmor_runtimepyarmor_runtime()__pyarmor__(__name__,__file__,b'\x06\x0f...')

The first 2 lines calledBootstrap Code, are only in the entryscript. They must be run before using any obfuscated file. For all the otherobfuscated*.py, there is only last line:

__pyarmor__(__name__,__file__,b'\x0a\x02...')

Run the obfuscated script:

cddistpythonmyscript.py

By default, only the*.py in the same path as the entry script areobfuscated. To obfuscate all the*.py in the sub-folder recursively,execute this command:

pyarmorobfuscate--recursivemyscript.py

Distributing Obfuscated Scripts¶

Just copy all the files in the output pathdist to end users. Note that exceptthe obfuscated scripts, theRuntime Package need to be distributed to endusers too.

PyArmor only deals with.py files, if there are data files or binary extensionin the package, copy them todist manually.

TheRuntime Package may not with the obfuscated scripts, it could bemoved to any Python path, only ifimport pytransform works.

About the security of obfuscated scripts, refer toThe Security of PyArmor

Generating License For Obfuscated Scripts¶

Use commandlicenses to generate newlicense.lic for obfuscatedscripts.

Generate an expired license for obfuscated script:

pyarmorlicenses--expired2019-01-01r001

PyArmor generates new license file:

• Read data from.pyarmor_capsule.zip in theHOME folder
• Createlicense.lic in thelicenses/r001 folder
• Createlicense.lic.txt in thelicenses/r001 folder

Obfuscate the scripts with this new one:

pyarmorobfuscate--with-licenselicenses/r001/license.licmyscript.py

Now run obfuscated script, It will report error after Jan. 1, 2019:

cddistpythonmyscript.py

Generate license to bind obfuscated scripts to fixed machine, first get hardwareinformation:

pyarmorhdinfo

Then generate new license bind to harddisk serial number and mac address:

pyarmorlicenses--bind-disk"100304PBN2081SF3NJ5T"--bind-mac"20:c1:d2:2f:a0:96"code-002

Run obfuscated script with new license:

pyarmorobfuscate--with-licenselicenses/code-002/license.licmyscript.pycddist/pythonmyscript.py

It also could be use an outer license filelicense.lic with the obfuscatedscripts. By outer license, just obfuscate scripts once, then generate newlicense to overwrite the old license on demand. This is the tradional way, refertoHow to use outer license file

Extending License Type¶

It’s easy to extend any other licese type for obfuscated scripts:just addauthentication code in the entry script. The script can’t be changed any moreafter it is obfuscated, so do whatever you want in your script. In this case theRuntime Module pytransform would be useful.

The prefer way isUsing Plugin to Extend License Type. The advantage isthat your scripts needn’t be changed at all. Just write authentication code in aseparated script, and inject it in the obfuscated scripts as obfuscating. Formore information, refer toHow to Deal With Plugins

Here are some plugin examples

https://github.com/dashingsoft/pyarmor/tree/master/plugins

Obfuscating Single Module¶

To obfuscate one module exactly, use option--exact:

pyarmorobfuscate--exactfoo.py

Onlyfoo.py is obfuscated, now import this obfuscated module:

cddistpython-c"import foo"

Obfuscating Whole Package¶

Run the following command to obfuscate a package:

pyarmorobfuscate--recursive--outputdist/mypkgmykpg/__init__.py

To import the obfuscated package:

cddistpython-c"import mypkg"

Packing Obfuscated Scripts¶

Use commandpack to pack obfuscated scripts into the bundle.

First installPyInstaller:

pipinstallpyinstaller

Set the current directory to the location of your programmyscript.py and execute:

pyarmorpackmyscript.py

PyArmor packsmyscript.py:

• Executepyarmorobfuscate to obfuscatemyscript.py
• Executepyinstallermyscipt.py to createmyscript.spec
• Updatemyscript.spec, replace original scripts with obfuscated ones
• Executepyinstallermyscript.spec to bundle the obfuscated scripts

In thedist/myscript folder you find the bundled app you distribute to yourusers.

Run the final executeable file:

dist/myscript/myscript

Generate an expired license for the bundle:

pyarmorlicenses--expired2019-01-01code-003pyarmorpack--with-licenselicenses/code-003/license.licmyscript.pydist/myscript/myscript

For complicated cases, refer to commandpack andHow To Pack Obfuscated Scripts.

Improving Security Further¶

ThesePyArmor features could import security further:

1. UsingSuper Plus Mode to obufscate scripts if possible, otherwiseUsing Super Mode, otherwise enableAdvanced Mode if the platformis supported. In Windows and the performance meets the requirement, enableVM Mode
2. Try toBinding obfuscated scripts to Python interpreter if they’redistributed as one executable bundle.
3. Make sure the entry script is patched bycross protection code,and try toCustomizing cross protection code
4. Use the correspondingRestrict Mode to make sure no one can import theobfuscated module.
5. Use the high security code obfuscation–obf-code=2
6. Using Plugin To Improve Security by injecting your private checkpointsin the obfuscated scripts, there is one decoratorassert_armored() andone functioncheck_armored() in thepytransform used toprevent monkey trick hacking. You can also add any other check points to makesure the obfuscated scripts are not hacked.
7. If data files need to be protected, refer toHow to protect data files

About the security of obfuscated scripts, refer toThe Security of PyArmor