Skip to content

ScanPyinstaller

Collects metadata and extracts pysource files from PyInstaller binaries.

This scanner parses PyInstaller binaries to collect metadata and extract embedded pysource files. It is used in forensic and malware analysis to extract and analyze structured data within PyInstaller binaries.

Scanner Type: Collection

Attributes:

Name Type Description
event dict

A dictionary to store collected metadata during the scan, structured by token types.
Detection Use Cases
  • Forensic Investigation
    • Aid in the investigation of incidents involving this specific type of Python shellcode execution by giving access to encapsulated code.
Known Limitations
  • Other Python-based Shellcode Runners
    • This scanner was made for a very specific format of Python shellcode runner script. It will not detect or extract shellcode from Python scripts which use other methods.
Source code in strelka/src/python/strelka/scanners/scan_pyinstaller.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class ScanPyinstaller(strelka.Scanner):
    """
    Collects metadata and extracts pysource files from PyInstaller binaries.

    This scanner parses PyInstaller binaries to collect metadata and extract embedded pysource files.
    It is used in forensic and malware analysis to extract and analyze structured data within PyInstaller binaries.

    Scanner Type: Collection

    Attributes:
        event (dict): A dictionary to store collected metadata during the scan, structured by token types.

    Detection Use Cases:
        - **Forensic Investigation**
            - Aid in the investigation of incidents involving this specific type of Python shellcode execution by
            giving access to encapsulated code.

    Known Limitations:
        - **Other Python-based Shellcode Runners**
            - This scanner was made for a very specific format of Python shellcode runner script. It will not detect
            or extract shellcode from Python scripts which use other methods.
    """

    def scan(self, data, file, options, expire_at):
        """
        Performs the scan operation on PyInstaller samples.

        Args:
            data (bytes): The file data as a byte string.
            file (File): The file object to be scanned.
            options (dict): Options for customizing the scan.
            expire_at (datetime): Expiration timestamp for the scan result.
        """
        # read the compiled package archive
        pkg_archive = CArchiveReader(data)
        self.event["cookie"] = pkg_archive._COOKIE
        self.event["pkg_item_binary"] = []
        self.event["pkg_item_dependency"] = []
        self.event["pkg_item_pyz"] = []
        self.event["pkg_item_zipfile"] = []
        self.event["pkg_item_pypackage"] = []
        self.event["pkg_item_pymodule"] = []
        self.event["pkg_item_pysource"] = []
        self.event["pkg_item_data"] = []
        self.event["pkg_item_runtime_option"] = []
        self.event["pkg_item_splash"] = []

        # parse each item in the package archive
        for name, toc_meta in pkg_archive.toc.items():
            (
                entry_offset,
                data_length,
                uncompressed_length,
                compression_flag,
                typecode,
            ) = toc_meta

            toc_entry = {
                "name": name,
                "entry_offset": entry_offset,
                "data_length": data_length,
                "uncompressed_length": uncompressed_length,
                "compression_flag": compression_flag,
                "typecode": typecode,
            }

            if typecode == PKG_ITEM_BINARY:
                self.event["pkg_item_binary"].append(toc_entry)
            elif typecode == PKG_ITEM_DEPENDENCY:
                self.event["pkg_item_dependency"].append(toc_entry)
            elif typecode == PKG_ITEM_PYZ:
                self.event["pkg_item_pyz"].append(toc_entry)
            elif typecode == PKG_ITEM_ZIPFILE:
                self.event["pkg_item_zipfile"].append(toc_entry)
            elif typecode == PKG_ITEM_PYPACKAGE:
                self.event["pkg_item_pypackage"].append(toc_entry)
            elif typecode == PKG_ITEM_PYMODULE:
                self.event["pkg_item_pymodule"].append(toc_entry)
            elif typecode == PKG_ITEM_PYSOURCE:
                self.event["pkg_item_pysource"].append(toc_entry)
                self.emit_file(pkg_archive.extract(name), name=name)
            elif typecode == PKG_ITEM_DATA:
                self.event["pkg_item_data"].append(toc_entry)
            elif typecode == PKG_ITEM_RUNTIME_OPTION:
                self.event["pkg_item_runtime_option"].append(toc_entry)
            elif typecode == PKG_ITEM_SPLASH:
                self.event["pkg_item_splash"].append(toc_entry)

scan(data, file, options, expire_at)

Performs the scan operation on PyInstaller samples.

Parameters:

Name Type Description Default
data bytes

The file data as a byte string.

 required
file File

The file object to be scanned.

 required
options dict

Options for customizing the scan.

 required
expire_at datetime

Expiration timestamp for the scan result.

 required
Source code in strelka/src/python/strelka/scanners/scan_pyinstaller.py 
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def scan(self, data, file, options, expire_at):
    """
    Performs the scan operation on PyInstaller samples.

    Args:
        data (bytes): The file data as a byte string.
        file (File): The file object to be scanned.
        options (dict): Options for customizing the scan.
        expire_at (datetime): Expiration timestamp for the scan result.
    """
    # read the compiled package archive
    pkg_archive = CArchiveReader(data)
    self.event["cookie"] = pkg_archive._COOKIE
    self.event["pkg_item_binary"] = []
    self.event["pkg_item_dependency"] = []
    self.event["pkg_item_pyz"] = []
    self.event["pkg_item_zipfile"] = []
    self.event["pkg_item_pypackage"] = []
    self.event["pkg_item_pymodule"] = []
    self.event["pkg_item_pysource"] = []
    self.event["pkg_item_data"] = []
    self.event["pkg_item_runtime_option"] = []
    self.event["pkg_item_splash"] = []

    # parse each item in the package archive
    for name, toc_meta in pkg_archive.toc.items():
        (
            entry_offset,
            data_length,
            uncompressed_length,
            compression_flag,
            typecode,
        ) = toc_meta

        toc_entry = {
            "name": name,
            "entry_offset": entry_offset,
            "data_length": data_length,
            "uncompressed_length": uncompressed_length,
            "compression_flag": compression_flag,
            "typecode": typecode,
        }

        if typecode == PKG_ITEM_BINARY:
            self.event["pkg_item_binary"].append(toc_entry)
        elif typecode == PKG_ITEM_DEPENDENCY:
            self.event["pkg_item_dependency"].append(toc_entry)
        elif typecode == PKG_ITEM_PYZ:
            self.event["pkg_item_pyz"].append(toc_entry)
        elif typecode == PKG_ITEM_ZIPFILE:
            self.event["pkg_item_zipfile"].append(toc_entry)
        elif typecode == PKG_ITEM_PYPACKAGE:
            self.event["pkg_item_pypackage"].append(toc_entry)
        elif typecode == PKG_ITEM_PYMODULE:
            self.event["pkg_item_pymodule"].append(toc_entry)
        elif typecode == PKG_ITEM_PYSOURCE:
            self.event["pkg_item_pysource"].append(toc_entry)
            self.emit_file(pkg_archive.extract(name), name=name)
        elif typecode == PKG_ITEM_DATA:
            self.event["pkg_item_data"].append(toc_entry)
        elif typecode == PKG_ITEM_RUNTIME_OPTION:
            self.event["pkg_item_runtime_option"].append(toc_entry)
        elif typecode == PKG_ITEM_SPLASH:
            self.event["pkg_item_splash"].append(toc_entry)

Features

The features of this scanner are detailed below. These features represent the capabilities and the type of analysis the scanner can perform. This may include support for Indicators of Compromise (IOC), the ability to emit files for further analysis, and the presence of extended documentation for complex analysis techniques.

Feature
Support
IOC Support
Emit Files
Extended Docs
Malware Scanner
Image Thumbnails

Tastes

Strelka's file distribution system assigns scanners to files based on 'flavors' and 'tastes'. Flavors describe the type of file, typically determined by MIME types from libmagic, matches from YARA rules, or characteristics of parent files. Tastes are the criteria used within Strelka to determine which scanners are applied to which files, with positive and negative tastes defining files to be included or excluded respectively.

Source Filetype
Include / Exclude
pyinstaller_file

Scanner Fields

This section provides a list of fields that are extracted from the files processed by this scanner. These fields include the data elements that the scanner extracts from each file, representing the analytical results produced by the scanner. If the test file is missing or cannot be parsed, this section will not contain any data.

Field Name
Field Type
cookie
dict
cookie.archive_length
int
cookie.magic
str
cookie.pylib_name
str
cookie.pyvers
int
cookie.toc_length
int
cookie.toc_offset
int
elapsed
str
flags
list
pkg_item_binary
list
pkg_item_data
list
pkg_item_dependency
list
pkg_item_pymodule
list
pkg_item_pymodule.compression_flag
int
pkg_item_pymodule.data_length
int
pkg_item_pymodule.entry_offset
int
pkg_item_pymodule.name
str
pkg_item_pymodule.typecode
str
pkg_item_pymodule.uncompressed_length
int
pkg_item_pypackage
list
pkg_item_pysource
list
pkg_item_pysource.compression_flag
int
pkg_item_pysource.data_length
int
pkg_item_pysource.entry_offset
int
pkg_item_pysource.name
str
pkg_item_pysource.typecode
str
pkg_item_pysource.uncompressed_length
int
pkg_item_pyz
list
pkg_item_pyz.compression_flag
int
pkg_item_pyz.data_length
int
pkg_item_pyz.entry_offset
int
pkg_item_pyz.name
str
pkg_item_pyz.typecode
str
pkg_item_pyz.uncompressed_length
int
pkg_item_runtime_option
list
pkg_item_splash
list
pkg_item_zipfile
list

Sample Event

Below is a sample event generated by this scanner, demonstrating the kind of output that can be expected when it processes a file. This sample is derived from a mock scan event configured in the scanner's test file. If no test file is available, this section will not display a sample event.

    test_scan_event = {
        "elapsed": 0.001,
        "flags": [],
        "cookie": {
            "archive_length": 1381481,
            "magic": "MEI\f\u000b\n\u000b\u000e",
            "pylib_name": "Python",
            "pyvers": 313,
            "toc_length": 400,
            "toc_offset": 1380993,
        },
        "pkg_item_binary": [],
        "pkg_item_data": [],
        "pkg_item_dependency": [],
        "pkg_item_pymodule": [
            {
                "compression_flag": 1,
                "data_length": 235,
                "entry_offset": 0,
                "name": "struct",
                "typecode": "m",
                "uncompressed_length": 289,
            },
            {
                "compression_flag": 1,
                "data_length": 2754,
                "entry_offset": 235,
                "name": "pyimod01_archive",
                "typecode": "m",
                "uncompressed_length": 4797,
            },
            {
                "compression_flag": 1,
                "data_length": 13646,
                "entry_offset": 2989,
                "name": "pyimod02_importers",
                "typecode": "m",
                "uncompressed_length": 31830,
            },
            {
                "compression_flag": 1,
                "data_length": 2820,
                "entry_offset": 16635,
                "name": "pyimod03_ctypes",
                "typecode": "m",
                "uncompressed_length": 6453,
            },
        ],
        "pkg_item_pypackage": [],
        "pkg_item_pysource": [
            {
                "compression_flag": 1,
                "data_length": 1040,
                "entry_offset": 19455,
                "name": "pyiboot01_bootstrap",
                "typecode": "s",
                "uncompressed_length": 1900,
            },
            {
                "compression_flag": 1,
                "data_length": 1532,
                "entry_offset": 20495,
                "name": "pyi_rth_inspect",
                "typecode": "s",
                "uncompressed_length": 2831,
            },
            {
                "compression_flag": 1,
                "data_length": 112,
                "entry_offset": 22027,
                "name": "hello_world",
                "typecode": "s",
                "uncompressed_length": 137,
            },
        ],
        "pkg_item_pyz": [
            {
                "compression_flag": 0,
                "data_length": 1358854,
                "entry_offset": 22139,
                "name": "PYZ-00.pyz",
                "typecode": "z",
                "uncompressed_length": 1358854,
            }