Serpent anatomy: Dissecting and reversing PyInstaller

As an example, let’s test a graphical app: to register it, you have to enter the correct serial number in response to the hardware ID displayed by the program. If you enter the serial number incorrectly, the app will respond: “No valid license code”. Detect It Easy confirms that this program is a suitable test object.

Let’s use the standard algorithm to examine the app. Searches for accompanying text strings in the exe file bring no results: the executable code and data are either packed or encrypted. Loading the app to IDA indirectly confirms this: the exe file is a loader for a large self-extracting file archive.

The next step is to load the program to the x64dbg debugger. Fortunately, the app doesn’t resist this procedure: it loads normally and can be interrupted upon request. The application of tracer makes it possible to quickly locate a code section that strongly resembles an interpreter of threaded P-code:

As you can see, the command handler table is located at the address 6C8D8; while the pointer to the current command is located in the R15 register.

At this point, I suggest to put the debugger aside for a while and refresh the theory. But first, let’s note an interesting fact: most dynamic libraries displayed in the “Debug modules” tab are physically located in the \_MEI100722 subfolder within the system folder for temporary files. Apparently, this is the directory (or one of the directories) the assembly is unpacked to while the app is running.

For better understanding, let’s remember what kind of beast Python is. Many people know it as a language used to write simple scripts (similar to JavaScript) and distinguished by a somewhat extravagant concept: code blocks are separated by indents. The project was created and subsequently developed in the best traditions of black English humor (as you know, its name refers to Monty Python, a British comedy group). In the course of its evolution, the highly specialized scripting language acquired multiple libraries (similar to Fortran).

Demand breeds supply; so, to make it easier for developers to create fully-functional commercial apps within the framework of the familiar Python concept, compilers were created for various implementations. Some people tried to create native compilers; while others attached JIT (just-in-time compilation) to Python.

Accordingly, the Jython (translation into JVM bytecode) and IronPython (translation into .NET IL) projects were created. But, unfortunately, as you could see from the above fragment of interpreter code, the reference implementation lacks real advantages: this just an ordinary P-code interpretation not distinguished by high optimization.

A seemingly obvious solution is to disassemble PyInstaller into individual files using PyInstaller Extractor.

But I suggest to extract files from the project using a more advanced tool: pydumpck. Of course, it’s not omnipotent either and has certain shortcomings. For instance, on my system, it only runs normally on Python 3.9, but, generally speaking, the code compatibility issue (even between adjacent subversions) is common and not even the most severe problem plaguing this programming language. Now let’s get back to harsh technical details of the reference implementation.

The minimal unit of compiled Python bytecode is a .pyc file (also, there are .pyo files compiled with optimization, but they are beyond the scope of this study). Such files are generated from text script code by calling the py_compile.compile method or by calling the import directive in the course of script execution (to avoid compiling the imported module again). This is how the developers tried to compensate the absence of JIT in the reference implementation. This file contains the bytecode of the compiled module, constants, references, etc. Its format depends on the Python version; even though it’s not documented officially, you can find detailed descriptions on the Internet, for instance, on Nedbatchelder. By the way, this article provides the text of the simplest pyc disassembler written in Python:

As you can see, disassembling the bytecode of .pyc files isn’t a big deal. You can use, for example, the most widespread Python disassembler called pydasm. There is even a special plug-in Python library, dis, created exclusively for disassembling. Even though the command system is version-dependent and not documented officially, it’s still simple and publicly available. Its description is also available online.

Too bad, decompiling pyc into original Python code is problematic. Despite the large number of available decompilers (the most common are python-decompile3 and pycdc), currently, there are no absolutely correct decompilers for versions older than 3.8 in the public, not to mention obfuscation. Therefore, I must disappoint lamers novice hackers seeking a magic button: decompiled code (even version 3.9) requires significant refinement.

Let’s continue examining the Python package files. Remember the list of imported libraries displayed by the debugger and unpacked into the system’s temporary directory? This list includes modules with the pyd extension. These are native binary libraries connected to the Python interpreter. As you can see, they are classic Windows dynamic libraries in the DLL format with a single exported function. Protections integrated into such native extensions are beyond the scope of this study since they are discussed in multiple publications.

Without digging too deep into the topic, let’s examine one more key file format with the .pyz extension. This is a Python archive making it possible to combine several modules, classes, and other components of your project into a single app. A kind of ‘archive in an archive’ inside an executable PyInstaller file.

All this makes searches for a certain module by string occurrence in an unpacked PyInstaller assembly very difficult. Fortunately, this hostile engineering marvel can be easily disassembled into its components using the above-mentioned pydumpck utility and reassembled (e.g. in the case of a patch) using the built-in zipapp utility.

Now that you possess the required knowledge, let’s put it to practice to dissect the test app. First, unpack it with pydumpck (Python 3.9 must be used). This is a virtually universal tool: not only does pydumpck unpack both the executable PyInstaller exe-module and pyz Python archives contained in it, but also decompiles the unpacked pyc files into the source code.

It has two built-in decompilation plugins: the above-mentioned uncompyle6 and pycdc. By default, pycdc is used, and it generally copes with the task; with regards to the uncompyle6 plugin, I was unable to use it on version 3.9.

Now let’s use WinHex to search the resulting set of files for the text string no valid license code. Since this is the simplest case, the desired string is found both in pyc and in the py file automatically decompiled from it. Open the py file restored by the decompiler. Too bad, version 3.9 isn’t native for pycdc, and it clearly suffers from code indigestion: the code isn’t restored in full. Warnings about unknown instructions and decompilation errors can be seen everywhere, and, of course, such source code cannot be recompiled. However, the desired location where the check occurs and the string is displayed is present in the file:

Let’s try to disassemble this file using pycdasm. At first, it complains about the absence of a signature, but it’s not a big deal: you can manually add it (in this case, it’s 8 bytes: 610D0D0A0000000000000000000000000) at the beginning of the file (e.g. using WinHex).

Looking for the required location in the disassembled code:

The POP_JUMP_IF_TRUE instruction is responsible for checking the condition and making a conditional jump. Of course, it could be changed to make an unconditional jump, but, in such a case, you would have to balance the stack somehow since there is no command that simultaneously removes a value from the stack and makes a jump. In addition, there is no guarantee that the serial number isn’t checked somewhere else. It’s better to find and adjust the utils.validate_serial() method. To do this, find the utils module and decompile it:

In the bytecode form, it looks as follows:

As you can see, all you have to do is replace the command at offset 36 LOAD_CONST 2:False (64 02) with the command LOAD_CONST 3: True (64 03), and the validate_serial() method will always return True. To verify this, let’s edit the bytecode directly in the debugger.

Press the Activate button – and voila! Now the program accepts any code. Now all you have to do is edit the bytecode in the respective pyc module and neatly reassemble the executable using PyInstaller.

At first glance, it might seem that hacking such apps is a ridiculously easy job. But, as you understand, this article analyzes the simplest and most basic case without obfuscation, virtualization, cryptography, and other hassles. That’s all for now; more exotic variants will be discussed in future materials.

See you soon!