ScanMacho

Collects metadata from Mach-O files.

Source code in strelka/src/python/strelka/scanners/scan_macho.py

class ScanMacho(strelka.Scanner):
    """Collects metadata from Mach-O files."""

    def scan(self, data, file, options, expire_at):
        tmp_directory = options.get("tmp_directory", "/tmp/")

        macho = MachO.parse(raw=list(data), config=MachO.ParserConfig.deep)

        self.event["total"] = {
            "binaries": macho.size,
        }

        if macho.size > 1:
            for r in range(0, macho.size):
                b = macho.at(r)
                with tempfile.NamedTemporaryFile(dir=tmp_directory) as tmp_data:
                    b.write(tmp_data.name)
                    tmp_data.flush()

                    with open(tmp_data.name, "rb") as f:
                        # Send extracted file back to Strelka
                        self.emit_file(f.read(), name=f"binary_{r}")

            return

        binary = macho.at(0)

        self.event["total"] = {
            **self.event["total"],
            "commands": binary.header.nb_cmds,
            "libraries": len(binary.libraries),
            "relocations": len(binary.relocations),
            "sections": len(binary.sections),
            "segments": len(binary.segments),
            "symbols": len(binary.symbols),
        }

        self.event["nx"] = binary.has_nx
        self.event["pie"] = binary.is_pie

        cpu_type = str(binary.header.cpu_type).split(".")[1]
        if cpu_type != "???":
            cpu_subtype = CPU_SUBTYPES[cpu_type][binary.header.cpu_subtype]
        else:
            cpu_subtype = str(binary.header.cpu_subtype)

        self.event["header"] = {
            "cpu": {
                "primary": cpu_type,
                "sub": cpu_subtype,
            },
            "file": str(binary.header.file_type).split(".")[1],
            "flags": [str(flag).split(".")[1] for flag in binary.header.flags_list],
        }

        self.event["relocations"] = []
        for relo in binary.relocations:
            row = {
                "address": relo.address,
                "size": relo.size,
            }

            if relo.has_section:
                row["section"] = relo.section.name
            if relo.has_segment:
                row["segment"] = relo.segment.name
            if relo.has_symbol:
                row["symbol"] = relo.symbol.name

            self.event["relocations"].append(row)

        self.event["sections"] = []
        for sec in binary.sections:
            self.event["sections"].append(
                {
                    "alignment": sec.alignment,
                    "entropy": sec.entropy,
                    "name": sec.name,
                    "offset": sec.offset,
                    "size": sec.size,
                    "virtual": {
                        "address": sec.virtual_address,
                    },
                }
            )

        self.event["segments"] = []
        for seg in binary.segments:
            self.event["segments"].append(
                {
                    "command": {
                        "offset": seg.command_offset,
                        "size": seg.size,
                        "type": str(seg.command).split(".")[1],
                    },
                    "file": {
                        "offset": seg.file_offset,
                        "size": seg.file_size,
                    },
                    "flags": seg.flags,
                    "protection": {
                        "init": PROTECTIONS[seg.init_protection],
                        "max": PROTECTIONS[seg.max_protection],
                    },
                    "name": seg.name,
                    "sections": [sec.name for sec in seg.sections],
                    "virtual": {
                        "address": seg.virtual_address,
                        "size": seg.virtual_size,
                    },
                }
            )

        self.event["symbols"] = {
            "exported": [sym.name for sym in binary.exported_symbols],
            "imported": [sym.name for sym in binary.imported_symbols],
            "libraries": [lib.name for lib in binary.libraries],
            "table": [],
        }

        for sym in binary.symbols:
            row = {
                "symbol": sym.name,
                "origin": str(sym.origin).rsplit(".")[1],
            }

            if sym.has_binding_info:
                binding_address = getattr(sym.binding_info, "address", None)
                binding_class = getattr(sym.binding_info, "binding_class", None)
                binding_type = getattr(sym.binding_info, "binding_type", None)
                weak_import = getattr(sym.binding_info, "weak_import", None)

                # Convert binding_class and binding_type to string and extract the last part after "."
                if binding_class and "." in str(binding_class):
                    binding_class = str(binding_class).rsplit(".", 1)[1]

                if binding_type and "." in str(binding_type):
                    binding_type = str(binding_type).rsplit(".", 1)[1]

                row["binding"] = {
                    "address": binding_address,
                    "class": binding_class,
                    "type": binding_type,
                    "weak_import": weak_import,
                }

                if sym.binding_info.has_library:
                    lib = sym.binding_info.library
                    row["binding"]["library"] = {
                        "name": lib.name,
                        "size": lib.size,
                        "timestamp": lib.timestamp,
                        "version": {
                            "compatibility": ".".join(
                                [str(ver) for ver in lib.compatibility_version]
                            ),
                            "current": ".".join(
                                [str(ver) for ver in lib.current_version]
                            ),
                        },
                    }

                if sym.binding_info.has_segment:
                    row["binding"]["segment"] = sym.binding_info.segment.name

            elif sym.has_export_info:
                row["export"] = {
                    "address": sym.export_info.address,
                    "flags": sym.export_info.flags,
                }
            self.event["symbols"]["table"].append(row)

        self.event["commands"] = {
            "commands": [str(com.command).split(".")[1] for com in binary.commands]
        }

        if binary.has_code_signature:
            self.event["commands"]["code_signature"] = {
                "command": {
                    "offset": binary.code_signature.command_offset,
                    "size": binary.code_signature.size,
                },
                "data": {
                    "offset": binary.code_signature.data_offset,
                    "size": binary.code_signature.data_size,
                },
            }

        if binary.has_data_in_code:
            self.event["commands"]["data_in_code"] = {
                "command": {
                    "offset": binary.data_in_code.command_offset,
                    "size": binary.data_in_code.size,
                },
                "data": {
                    "offset": binary.data_in_code.data_offset,
                    "size": binary.data_in_code.data_size,
                },
            }

            entries = []
            for e in binary.data_in_code.entries:
                entries.append(
                    {
                        "length": e.length,
                        "offset": e.offset,
                        "type": str(e.type).split(".")[1],
                    }
                )
            self.event["commands"]["data_in_code"]["entries"] = entries

        if binary.has_dyld_environment:
            self.event["commands"]["dyld_environment"] = {
                "command": {
                    "offset": binary.dyld_environment.command_offset,
                    "size": binary.dyld_environment.size,
                },
                "environment_variable": binary.dyld_environment.value,
            }

        if binary.has_dyld_info:
            self.event["commands"]["dyld_info"] = {
                "bind": {
                    "offset": binary.dyld_info.bind[0],
                    "size": binary.dyld_info.bind[1],
                    "lazy": {
                        "offset": binary.dyld_info.lazy_bind[0],
                        "size": binary.dyld_info.lazy_bind[1],
                    },
                    "weak": {
                        "offset": binary.dyld_info.weak_bind[0],
                        "size": binary.dyld_info.weak_bind[1],
                    },
                },
                "command": {
                    "offset": binary.dyld_info.command_offset,
                    "size": binary.dyld_info.size,
                },
                "export": {
                    "offset": binary.dyld_info.export_info[0],
                    "size": binary.dyld_info.export_info[1],
                },
                "rebase": {
                    "offset": binary.dyld_info.rebase[0],
                    "size": binary.dyld_info.rebase[1],
                },
            }

        if binary.has_dylinker:
            self.event["commands"]["load_dylinker"] = {
                "command": {
                    "offset": binary.dylinker.command_offset,
                    "size": binary.dylinker.size,
                },
                "name": binary.dylinker.name,
            }

        if binary.has_dynamic_symbol_command:
            self.event["commands"]["dynamic_symbol"] = {
                "command": {
                    "offset": binary.dynamic_symbol_command.command_offset,
                    "size": binary.dynamic_symbol_command.size,
                },
                "offset": {
                    "symbol": {
                        "external": binary.dynamic_symbol_command.external_reference_symbol_offset,
                        "indirect": binary.dynamic_symbol_command.indirect_symbol_offset,
                    },
                    "relocation": {
                        "external": binary.dynamic_symbol_command.external_relocation_offset,
                        "local": binary.dynamic_symbol_command.local_relocation_offset,
                    },
                    "table": {
                        "module": binary.dynamic_symbol_command.module_table_offset,
                    },
                    "toc": binary.dynamic_symbol_command.toc_offset,
                },
            }

        if binary.has_encryption_info:
            self.event["commands"]["encryption_info"] = {
                "command": {
                    "offset": binary.encryption_info.command_offset,
                    "size": binary.encryption_info.size,
                },
                "crypt": {
                    "id": binary.encryption_info.crypt_id,
                    "offset": binary.encryption_info.crypt_offset,
                    "size": binary.encryption_info.crypt_size,
                },
            }

        if binary.has_function_starts:
            self.event["commands"]["function_starts"] = {
                "command": {
                    "offset": binary.function_starts.command_offset,
                    "size": binary.function_starts.size,
                },
                "data": {
                    "offset": binary.function_starts.data_offset,
                    "size": binary.function_starts.data_size,
                },
            }

        if binary.has_main_command:
            self.event["commands"]["main"] = {
                "command": {
                    "offset": binary.main_command.command_offset,
                    "size": binary.main_command.size,
                },
                "entry_point": binary.main_command.entrypoint,
                "stack_size": binary.main_command.stack_size,
            }

        if binary.has_rpath:
            self.event["commands"]["rpath"] = {
                "command": {
                    "offset": binary.rpath.command_offset,
                    "size": binary.rpath.size,
                },
                "path": binary.rpath.path,
            }

        if binary.has_segment_split_info:
            self.event["commands"]["segment_split_info"] = {
                "command": {
                    "offset": binary.segment_split_info.command_offset,
                    "size": binary.segment_split_info.size,
                },
                "data": {
                    "offset": binary.segment_split_info.data_offset,
                    "size": binary.segment_split_info.data_size,
                },
            }

        if binary.has_source_version:
            self.event["commands"]["source_version"] = {
                "command": {
                    "offset": binary.source_version.command_offset,
                    "size": binary.source_version.size,
                },
                "version": ".".join([str(v) for v in binary.source_version.version]),
            }

        if binary.has_sub_framework:
            self.event["commands"]["sub_framework"] = {
                "command": {
                    "offset": binary.sub_framework.command_offset,
                    "size": binary.sub_framework.size,
                },
            }

        if binary.has_symbol_command:
            self.event["commands"]["symbol"] = {
                "command": {
                    "offset": binary.symbol_command.command_offset,
                    "size": binary.symbol_command.size,
                },
                "strings": {
                    "offset": binary.symbol_command.strings_offset,
                    "size": binary.symbol_command.strings_size,
                },
                "symbol": {
                    "offset": binary.symbol_command.symbol_offset,
                },
            }

        if binary.has_thread_command:
            self.event["commands"]["thread"] = {
                "command": {
                    "offset": binary.thread_command.command_offset,
                    "size": binary.thread_command.size,
                },
            }

        if binary.has_uuid:
            self.event["commands"]["uuid"] = {
                "command": {
                    "offset": binary.uuid.command_offset,
                    "size": binary.uuid.size,
                },
                "uuid": "".join([str(u) for u in binary.uuid.uuid]),
            }

        if binary.has_version_min:
            self.event["commands"]["version_min"] = {
                "command": {
                    "offset": binary.version_min.command_offset,
                    "size": binary.version_min.size,
                },
                "version": ".".join([str(v) for v in binary.version_min.version]),
                "sdk": ".".join([str(s) for s in binary.version_min.sdk]),
            }

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
application/x-mach-binary
macho_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
commands	dict
commands.commands	list
commands.data_in_code	dict
commands.data_in_code.command	dict
commands.data_in_code.command.offset	int
commands.data_in_code.command.size	int
commands.data_in_code.data	dict
commands.data_in_code.data.offset	int
commands.data_in_code.data.size	int
commands.data_in_code.entries	list
commands.dynamic_symbol	dict
commands.dynamic_symbol.command	dict
commands.dynamic_symbol.command.offset	int
commands.dynamic_symbol.command.size	int
commands.dynamic_symbol.offset	dict
commands.dynamic_symbol.offset.relocation	dict
commands.dynamic_symbol.offset.relocation.external	int
commands.dynamic_symbol.offset.relocation.local	int
commands.dynamic_symbol.offset.symbol	dict
commands.dynamic_symbol.offset.symbol.external	int
commands.dynamic_symbol.offset.symbol.indirect	int
commands.dynamic_symbol.offset.table	dict
commands.dynamic_symbol.offset.table.module	int
commands.dynamic_symbol.offset.toc	int
commands.function_starts	dict
commands.function_starts.command	dict
commands.function_starts.command.offset	int
commands.function_starts.command.size	int
commands.function_starts.data	dict
commands.function_starts.data.offset	int
commands.function_starts.data.size	int
commands.load_dylinker	dict
commands.load_dylinker.command	dict
commands.load_dylinker.command.offset	int
commands.load_dylinker.command.size	int
commands.load_dylinker.name	str
commands.main	dict
commands.main.command	dict
commands.main.command.offset	int
commands.main.command.size	int
commands.main.entry_point	int
commands.main.stack_size	int
commands.source_version	dict
commands.source_version.command	dict
commands.source_version.command.offset	int
commands.source_version.command.size	int
commands.source_version.version	str
commands.symbol	dict
commands.symbol.command	dict
commands.symbol.command.offset	int
commands.symbol.command.size	int
commands.symbol.strings	dict
commands.symbol.strings.offset	int
commands.symbol.strings.size	int
commands.symbol.symbol	dict
commands.symbol.symbol.offset	int
commands.uuid	dict
commands.uuid.command	dict
commands.uuid.command.offset	int
commands.uuid.command.size	int
commands.uuid.uuid	str
elapsed	str
flags	list
header	dict
header.cpu	dict
header.cpu.primary	str
header.cpu.sub	str
header.file	str
header.flags	list
nx	bool
pie	bool
relocations	list
sections	list
sections.alignment	int
sections.entropy	str
sections.name	str
sections.offset	int
sections.size	int
sections.virtual	dict
sections.virtual.address	int
segments	list
segments.command	dict
segments.command.offset	int
segments.command.size	int
segments.command.type	str
segments.file	dict
segments.file.offset	int
segments.file.size	int
segments.flags	int
segments.name	str
segments.protection	dict
segments.protection.init	str
segments.protection.max	str
segments.sections	list
segments.virtual	dict
segments.virtual.address	int
segments.virtual.size	int
symbols	dict
symbols.exported	list
symbols.imported	list
symbols.libraries	list
symbols.table	list
symbols.table.binding	dict
symbols.table.binding.address	int
symbols.table.binding.class	NoneType
symbols.table.binding.library	dict
symbols.table.binding.library.name	str
symbols.table.binding.library.size	int
symbols.table.binding.library.timestamp	int
symbols.table.binding.library.version	dict
symbols.table.binding.library.version.compatibility	str
symbols.table.binding.library.version.current	str
symbols.table.binding.segment	str
symbols.table.binding.type	NoneType
symbols.table.binding.weak_import	bool
symbols.table.export	dict
symbols.table.export.address	int
symbols.table.export.flags	int
symbols.table.origin	str
symbols.table.symbol	str
total	dict
total.binaries	int
total.commands	int
total.libraries	int
total.relocations	int
total.sections	int
total.segments	int
total.symbols	int

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": [],
        "total": {
            "binaries": 1,
            "commands": 16,
            "libraries": 1,
            "relocations": 0,
            "sections": 5,
            "segments": 4,
            "symbols": 3,
        },
        "nx": True,
        "pie": True,
        "header": {
            "cpu": {
                "primary": "x86_64",
                "sub": "x86_ALL, x86_64_ALL, I386_ALL, or 386",
            },
            "file": "EXECUTE",
            "flags": ["TWOLEVEL", "NOUNDEFS", "DYLDLINK", "PIE"],
        },
        "relocations": [],
        "sections": [
            {
                "alignment": 4,
                "entropy": 0.001,
                "name": "__text",
                "offset": 16240,
                "size": 37,
                "virtual": {"address": 4294983536},
            },
            {
                "alignment": 1,
                "entropy": 0.001,
                "name": "__stubs",
                "offset": 16278,
                "size": 6,
                "virtual": {"address": 4294983574},
            },
            {
                "alignment": 0,
                "entropy": 0.001,
                "name": "__cstring",
                "offset": 16284,
                "size": 13,
                "virtual": {"address": 4294983580},
            },
            {
                "alignment": 2,
                "entropy": 0.001,
                "name": "__unwind_info",
                "offset": 16300,
                "size": 72,
                "virtual": {"address": 4294983596},
            },
            {
                "alignment": 3,
                "entropy": 0.001,
                "name": "__got",
                "offset": 16384,
                "size": 8,
                "virtual": {"address": 4294983680},
            },
        ],
        "segments": [
            {
                "command": {"offset": 32, "size": 72, "type": "SEGMENT_64"},
                "file": {"offset": 0, "size": 0},
                "flags": 0,
                "protection": {"init": "---", "max": "---"},
                "name": "__PAGEZERO",
                "sections": [],
                "virtual": {"address": 0, "size": 4294967296},
            },
            {
                "command": {"offset": 104, "size": 392, "type": "SEGMENT_64"},
                "file": {"offset": 0, "size": 16384},
                "flags": 0,
                "protection": {"init": "r-x", "max": "r-x"},
                "name": "__TEXT",
                "sections": ["__text", "__stubs", "__cstring", "__unwind_info"],
                "virtual": {"address": 4294967296, "size": 16384},
            },
            {
                "command": {"offset": 496, "size": 152, "type": "SEGMENT_64"},
                "file": {"offset": 16384, "size": 16384},
                "flags": 16,
                "protection": {"init": "rw-", "max": "rw-"},
                "name": "__DATA_CONST",
                "sections": ["__got"],
                "virtual": {"address": 4294983680, "size": 16384},
            },
            {
                "command": {"offset": 648, "size": 72, "type": "SEGMENT_64"},
                "file": {"offset": 32768, "size": 248},
                "flags": 0,
                "protection": {"init": "r--", "max": "r--"},
                "name": "__LINKEDIT",
                "sections": [],
                "virtual": {"address": 4295000064, "size": 16384},
            },
        ],
        "symbols": {
            "exported": ["__mh_execute_header", "_main"],
            "imported": ["_printf"],
            "libraries": ["/usr/lib/libSystem.B.dylib"],
            "table": [
                {
                    "export": {"address": 0, "flags": 0},
                    "origin": "LC_SYMTAB",
                    "symbol": "__mh_execute_header",
                },
                {
                    "export": {"address": 16240, "flags": 0},
                    "origin": "LC_SYMTAB",
                    "symbol": "_main",
                },
                {
                    "binding": {
                        "address": 0,
                        "class": None,
                        "library": {
                            "name": "/usr/lib/libSystem.B.dylib",
                            "size": 56,
                            "timestamp": 2,
                            "version": {
                                "compatibility": "1.0.0",
                                "current": "1319.0.0",
                            },
                        },
                        "segment": "__DATA_CONST",
                        "type": None,
                        "weak_import": False,
                    },
                    "origin": "LC_SYMTAB",
                    "symbol": "_printf",
                },
            ],
        },
        "commands": {
            "commands": [
                "SEGMENT_64",
                "SEGMENT_64",
                "SEGMENT_64",
                "SEGMENT_64",
                "DYLD_CHAINED_FIXUPS",
                "DYLD_EXPORTS_TRIE",
                "SYMTAB",
                "DYSYMTAB",
                "LOAD_DYLINKER",
                "UUID",
                "BUILD_VERSION",
                "SOURCE_VERSION",
                "MAIN",
                "LOAD_DYLIB",
                "FUNCTION_STARTS",
                "DATA_IN_CODE",
            ],
            "data_in_code": {
                "command": {"offset": 1056, "size": 16},
                "data": {"offset": 32920, "size": 0},
                "entries": [],
            },
            "load_dylinker": {
                "command": {"offset": 856, "size": 32},
                "name": "/usr/lib/dyld",
            },
            "dynamic_symbol": {
                "command": {"offset": 776, "size": 80},
                "offset": {
                    "symbol": {"external": 0, "indirect": 32968},
                    "relocation": {"external": 0, "local": 0},
                    "table": {"module": 0},
                    "toc": 0,
                },
            },
            "function_starts": {
                "command": {"offset": 1040, "size": 16},
                "data": {"offset": 32912, "size": 8},
            },
            "main": {
                "command": {"offset": 960, "size": 24},
                "entry_point": 16240,
                "stack_size": 0,
            },
            "source_version": {
                "command": {"offset": 944, "size": 16},
                "version": "0.0.0.0.0",
            },
            "symbol": {
                "command": {"offset": 752, "size": 24},
                "strings": {"offset": 32976, "size": 40},
                "symbol": {"offset": 32920},
            },
            "uuid": {
                "command": {"offset": 888, "size": 24},
                "uuid": "3412979242375017913918719719156127234240",
            },
        },
    }