maco 1.2.14__py3-none-any.whl → 1.2.16__py3-none-any.whl

maco/utils.py

@@ -1,7 +1,6 @@
-# Common utilities shared between the MACO collector and configextractor-py
+"""Common utilities shared between the MACO collector and configextractor-py."""
+
 import importlib
-import importlib.machinery
-import importlib.util
 import inspect
 import json
 import logging
@@ -12,8 +11,9 @@ import shutil
 import subprocess
 import sys
 import tempfile
+from importlib.machinery import SourceFileLoader
 
-from multiprocess import Queue
+from multiprocess import Process, Queue
 
 from maco import yara
 
@@ -26,15 +26,14 @@ from base64 import b64decode
 from copy import deepcopy
 from glob import glob
 from logging import Logger
-from pkgutil import walk_packages
 from types import ModuleType
-from typing import Callable, Dict, List, Set, Tuple, Union
+from typing import Callable, Dict, List, Tuple, Union
 
 from uv import find_uv_bin
 
 from maco import model
-from maco.extractor import Extractor
 from maco.exceptions import AnalysisAbortedException
+from maco.extractor import Extractor
 
 logger = logging.getLogger("maco.lib.utils")
 
@@ -50,10 +49,14 @@ VENV_CREATE_CMD = f"{UV_BIN} venv"
 
 
 class Base64Decoder(json.JSONDecoder):
+    """JSON decoder that also base64 encodes binary data."""
+
     def __init__(self, *args, **kwargs):
+        """Initialize the decoder."""
         json.JSONDecoder.__init__(self, object_hook=self.object_hook, *args, **kwargs)
 
     def object_hook(self, obj):
+        """Hook to decode base64 encoded binary data."""  # noqa: DOC201
         if "__class__" not in obj:
             return obj
         type = obj["__class__"]
@@ -131,17 +134,38 @@ rule MACO {
 
 
 def maco_extractor_validation(module: ModuleType) -> bool:
+    """Validation function for extractors.
+
+    Returns:
+        (bool): True if extractor belongs to MACO, False otherwise.
+    """
     if inspect.isclass(module):
         # 'author' has to be implemented otherwise will raise an exception according to MACO
         return hasattr(module, "author") and module.author
     return False
 
 
-def maco_extract_rules(module: Extractor) -> bool:
+def maco_extract_rules(module: Extractor) -> str:
+    """Extracts YARA rules from extractor.
+
+    Returns:
+     (str): YARA rules
+    """
     return module.yara_rule
 
 
 def scan_for_extractors(root_directory: str, scanner: yara.Rules, logger: Logger) -> Tuple[List[str], List[str]]:
+    """Looks for extractors using YARA rules.
+
+    Args:
+        root_directory (str): Root directory containing extractors
+        scanner (yara.Rules): Scanner to look for extractors using YARA rules
+        logger (Logger): Logger to use
+
+    Returns:
+        Tuple[List[str], List[str]]: Returns a list of extractor directories and extractor files
+
+    """
     extractor_dirs = set([root_directory])
     extractor_files = []
 
@@ -177,17 +201,22 @@ def scan_for_extractors(root_directory: str, scanner: yara.Rules, logger: Logger
                     with open(path, "rb") as f:
                         data = f.read()
 
-                    with open(path, "wb") as f:
-                        # Replace any relative importing with absolute
-                        curr_dir = os.path.dirname(path)
-                        split = curr_dir.split("/")[::-1]
-                        for pattern in [RELATIVE_FROM_IMPORT_RE, RELATIVE_FROM_RE]:
-                            for match in pattern.findall(data):
-                                depth = match.count(b".")
-                                abspath = ".".join(split[depth - 1 : split.index(package) + 1][::-1])
-                                abspath += "." if pattern == RELATIVE_FROM_RE else ""
-                                data = data.replace(f"from {match.decode()}".encode(), f"from {abspath}".encode(), 1)
-                        f.write(data)
+                    # Replace any relative importing with absolute
+                    changed_imports = False
+                    curr_dir = os.path.dirname(path)
+                    split = curr_dir.split("/")[::-1]
+                    for pattern in [RELATIVE_FROM_IMPORT_RE, RELATIVE_FROM_RE]:
+                        for match in pattern.findall(data):
+                            depth = match.count(b".")
+                            abspath = ".".join(split[depth - 1 : split.index(package) + 1][::-1])
+                            abspath += "." if pattern == RELATIVE_FROM_RE else ""
+                            data = data.replace(f"from {match.decode()}".encode(), f"from {abspath}".encode(), 1)
+                            changed_imports = True
+
+                    # only write extractor files if imports were changed
+                    if changed_imports:
+                        with open(path, "wb") as f:
+                            f.write(data)
 
                 if scanner.match(path):
                     # Add directory to list of hits for venv creation
@@ -282,7 +311,16 @@ def _install_required_packages(create_venv: bool, directories: List[str], python
     return venvs
 
 
-def find_and_insert_venv(path: str, venvs: List[str]):
+def find_and_insert_venv(path: str, venvs: List[str]) -> Tuple[str, str]:
+    """Finds the closest virtual environment to the extractor and inserts it into the PATH.
+
+    Args:
+        path (str): Path of extractor
+        venvs (List[str]): List of virtual environments
+
+    Returns:
+        (Tuple[str, str]): Virtual environment and site-packages path that's closest to the extractor
+    """
     venv = None
     for venv in sorted(venvs, reverse=True):
         venv_parent = os.path.dirname(venv)
@@ -303,14 +341,53 @@ def find_and_insert_venv(path: str, venvs: List[str]):
     return venv, site_package
 
 
+def register_extractor_module(
+    extractor_source_file: str,
+    module_name: str,
+    venvs: List[str],
+    extractor_module_callback: Callable[[ModuleType, str], None],
+    logger: Logger,
+):
+    """Register the extractor module in isolation.
+
+    Args:
+        extractor_source_file (str): Path to source file of extractor
+        module_name (str): The name of the module relative to the package directory
+        venvs (List[str]): List of virtual environments
+        extractor_module_callback (Callable[[ModuleType, str], None]): Callback used to register extractors
+        logger (Logger): Logger to use
+
+    """
+    try:
+        logger.info(f"Inspecting '{extractor_source_file}' for extractors..")
+        venv, site_packages = find_and_insert_venv(extractor_source_file, venvs)
+        loader = SourceFileLoader(
+            module_name,
+            extractor_source_file,
+        )
+        extractor_module_callback(loader.load_module(), venv)
+    finally:
+        # Cleanup virtual environment that was loaded into PATH
+        if venv and site_packages in sys.path:
+            sys.path.remove(site_packages)
+
+
 def register_extractors(
     current_directory: str,
     venvs: List[str],
     extractor_files: List[str],
     extractor_module_callback: Callable[[ModuleType, str], None],
     logger: Logger,
-    default_loaded_modules: Set[str] = set(sys.modules.keys()),
 ):
+    """Register extractors with in the current directory.
+
+    Args:
+        current_directory (str): Current directory to register extractors found
+        venvs (List[str]): List of virtual environments
+        extractor_files (List[str]): List of extractor files found
+        extractor_module_callback (Callable[[ModuleType, str], None]): Callback used to register extractors
+        logger (Logger): Logger to use
+    """
     package_name = os.path.basename(current_directory)
     parent_directory = os.path.dirname(current_directory)
     if venvs and package_name in sys.modules:
@@ -325,74 +402,25 @@ def register_extractors(
         sys.path.insert(1, current_directory)
         sys.path.insert(1, parent_directory)
 
-        # Insert any virtual environment necessary to load directory as package
-        package_venv, package_site_packages = find_and_insert_venv(current_directory, venvs)
-        package = importlib.import_module(package_name)
+        # Load the potential extractors directly from the source file
+        registration_processes = []
+        for extractor_source_file in extractor_files:
+            module_name = extractor_source_file.replace(f"{parent_directory}/", "").replace("/", ".")[:-3]
+            p = Process(
+                target=register_extractor_module,
+                args=(extractor_source_file, module_name, venvs, extractor_module_callback, logger),
+            )
+            p.start()
+            registration_processes.append(p)
 
-        # Walk through our new package and find the extractors that YARA identified
-        for module_path, module_name, ispkg in walk_packages(package.__path__, package.__name__ + "."):
-            if ispkg:
-                # Skip packages
-                continue
+        for p in registration_processes:
+            p.join()
 
-            module_path = os.path.realpath(os.path.join(module_path.path, module_name.rsplit(".", 1)[1]) + ".py")
-            if module_path in extractor_files:
-                # Cross this extractor off the list of extractors to find
-                logger.debug(f"Inspecting '{module_name}' for extractors..")
-                extractor_files.remove(module_path)
-                try:
-                    # This is an extractor we've been looking for, load the module and invoke callback
-                    venv, site_packages = find_and_insert_venv(module_path, venvs)
-                    module = importlib.import_module(module_name)
-                    module.__file__ = os.path.realpath(module.__file__)
-
-                    # Patch the original directory information into the module
-                    original_package_name = os.path.basename(current_directory)
-                    module.__name__ = module.__name__.replace(package_name, original_package_name)
-                    module.__package__ = module.__package__.replace(package_name, original_package_name)
-                    extractor_module_callback(module, venv)
-                finally:
-                    # Cleanup virtual environment that was loaded into PATH
-                    if venv and site_packages in sys.path:
-                        sys.path.remove(site_packages)
-
-            if not extractor_files:
-                return
     finally:
         # Cleanup changes made to PATH
         sys.path.remove(parent_directory)
         sys.path.remove(current_directory)
 
-        if package_venv and package_site_packages in sys.path:
-            sys.path.remove(package_site_packages)
-
-        # Remove any modules that were loaded to deconflict with later modules loads
-        [sys.modules.pop(k) for k in set(sys.modules.keys()) - default_loaded_modules]
-
-    # If there still exists extractor files we haven't found yet, try searching in the available subdirectories
-    if extractor_files:
-        for dir in os.listdir(current_directory):
-            path = os.path.join(current_directory, dir)
-            if dir == "__pycache__":
-                # Ignore the cache created
-                continue
-            elif dir.endswith(".egg-info"):
-                # Ignore these directories
-                continue
-            elif dir.startswith("."):
-                # Ignore hidden directories
-                continue
-
-            if os.path.isdir(path):
-                # Check subdirectory to find the rest of the detected extractors
-                register_extractors(
-                    path, venvs, extractor_files, extractor_module_callback, logger, default_loaded_modules
-                )
-
-            if not extractor_files:
-                # We were able to find all the extractor files
-                break
-
 
 def proxy_logging(queue: Queue, callback: Callable[[ModuleType, str], None], *args, **kwargs):
     """Ensures logging is set up correctly for a child process and then executes the callback."""
@@ -413,6 +441,17 @@ def import_extractors(
     python_version: str = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
     skip_install: bool = False,
 ):
+    """Import extractors in a given directory.
+
+    Args:
+        extractor_module_callback (Callable[[ModuleType, str], bool]): Callback used to register extractors
+        root_directory (str): Root directory to look for extractors
+        scanner (yara.Rules): Scanner to look for extractors that match YARA rule
+        create_venv (bool): Create/Use virtual environments
+        logger (Logger): Logger to use
+        python_version (str): Version of python to use when creating virtual environments
+        skip_install (bool): Skip installation of Python dependencies for extractors
+    """
     extractor_dirs, extractor_files = scan_for_extractors(root_directory, scanner, logger)
 
     logger.info(f"Extractor files found based on scanner ({len(extractor_files)}).")
@@ -448,7 +487,24 @@ def run_extractor(
     venv_script=VENV_SCRIPT,
     json_decoder=Base64Decoder,
 ) -> Union[Dict[str, dict], model.ExtractorModel]:
-    """Runs the maco extractor against sample either in current process or child process."""
+    """Runs the maco extractor against sample either in current process or child process.
+
+    Args:
+        sample_path (str): Path to sample
+        module_name (str): Name of extractor module
+        extractor_class (str): Name of extractor class in module
+        module_path (str): Path to Python module containing extractor
+        venv (str): Path to virtual environment associated to extractor
+        venv_script (str): Script to run extractor in a virtual environment
+        json_decoder (Base64Decoder): Decoder used for JSON
+
+    Raises:
+        AnalysisAbortedException: Raised when extractor voluntarily terminates execution
+        Exception: Raised when extractor raises an exception
+
+    Returns:
+        Union[Dict[str, dict], model.ExtractorModel]: Results from extractor
+    """
     if not venv:
         key = f"{module_name}_{extractor_class}"
         if key not in _loaded_extractors:

maco/yara.py

@@ -1,25 +1,34 @@
+"""yara-python facade that uses yara-x."""
+
 import re
 from collections import namedtuple
 from itertools import cycle
-from typing import Dict
+from typing import Dict, List
 
 import yara_x
 
-RULE_ID_RE = re.compile("(\w+)? ?rule (\w+)")
-
+from maco.exceptions import SyntaxError
 
-class SyntaxError(Exception): ...
+RULE_ID_RE = re.compile("(\w+)? ?rule (\w+)")
 
 
 # Create interfaces that resembles yara-python (but is running yara-x under the hood)
 class StringMatchInstance:
+    """Instance of a string match."""
+
     def __init__(self, match: yara_x.Match, file_content: bytes):
+        """Initializes StringMatchInstance."""
         self.matched_data = file_content[match.offset : match.offset + match.length]
         self.matched_length = match.length
         self.offset = match.offset
         self.xor_key = match.xor_key
 
     def plaintext(self) -> bytes:
+        """Plaintext of the matched data.
+
+        Returns:
+            (bytes): Plaintext of the matched cipher text
+        """
         if not self.xor_key:
             # No need to XOR the matched data
             return self.matched_data
@@ -28,17 +37,28 @@ class StringMatchInstance:
 
 
 class StringMatch:
+    """String match."""
+
     def __init__(self, pattern: yara_x.Pattern, file_content: bytes):
+        """Initializes StringMatch."""
         self.identifier = pattern.identifier
         self.instances = [StringMatchInstance(match, file_content) for match in pattern.matches]
         self._is_xor = any([match.xor_key for match in pattern.matches])
 
     def is_xor(self):
+        """Checks if string match is xor'd.
+
+        Returns:
+            (bool): True if match is xor'd
+        """
         return self._is_xor
 
 
 class Match:
+    """Match."""
+
     def __init__(self, rule: yara_x.Rule, file_content: bytes):
+        """Initializes Match."""
         self.rule = rule.identifier
         self.namespace = rule.namespace
         self.tags = list(rule.tags) or []
@@ -50,7 +70,14 @@ class Match:
 
 
 class Rules:
+    """Rules."""
+
     def __init__(self, source: str = None, sources: Dict[str, str] = None):
+        """Initializes Rules.
+
+        Raises:
+            SyntaxError: Raised when there's a syntax error in the YARA rule.
+        """
         Rule = namedtuple("Rule", "identifier namespace is_global")
         if source:
             sources = {"default": source}
@@ -69,10 +96,20 @@ class Rules:
             raise SyntaxError(e)
 
     def __iter__(self):
+        """Iterate over rules.
+
+        Yields:
+            YARA rules
+        """
         for rule in self._rules:
             yield rule
 
-    def match(self, filepath: str = None, data: bytes = None):
+    def match(self, filepath: str = None, data: bytes = None) -> List[Match]:
+        """Performs a scan to check for YARA rules matches based on the file, either given by path or buffer.
+
+        Returns:
+            (List[Match]): A list of YARA matches.
+        """
         if filepath:
             with open(filepath, "rb") as fp:
                 data = fp.read()
@@ -81,4 +118,9 @@ class Rules:
 
 
 def compile(source: str = None, sources: Dict[str, str] = None) -> Rules:
+    """Compiles YARA rules from source or from sources.
+
+    Returns:
+        (Rules): a Rules object
+    """
     return Rules(source, sources)

{maco-1.2.14.dist-info → maco-1.2.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: maco
-Version: 1.2.14
+Version: 1.2.16
 Author: sl-govau
 Maintainer: cccs-rs
 License: MIT License
@@ -35,6 +35,7 @@ Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Requires-Dist: uv
 Requires-Dist: yara-x==0.11.0
 Requires-Dist: multiprocess>=0.70.17
+Dynamic: license-file
 
 # Maco - Malware config extractor framework
 
@@ -69,7 +70,6 @@ This framework is actively being used by:
 |        <a href="https://cybercentrecanada.github.io/assemblyline4_docs/"><img src="https://images.weserv.nl/?url=cybercentrecanada.github.io/assemblyline4_docs/images/crane.png?v=4&h=100&w=100&fit=cover&maxage=7d"></a>         | A malware analysis platform that uses the MACO model to export malware configuration extractions into a parseable, machine-friendly format                                                                                                                    |       [![License](https://img.shields.io/github/license/CybercentreCanada/assemblyline)](https://github.com/CybercentreCanada/assemblyline/blob/main/LICENSE.md)       |
 |                                                                           [configextractor-py](https://github.com/CybercentreCanada/configextractor-py)                                                                            | A tool designed to run extractors from multiple frameworks and uses the MACO model for output harmonization                                                                                                                                                   | [![License](https://img.shields.io/github/license/CybercentreCanada/configextractor-py)](https://github.com/CybercentreCanada/configextractor-py/blob/main/LICENSE.md) |
 | <a href="https://github.com/jeFF0Falltrades/rat_king_parser"><img src="https://images.weserv.nl/?url=raw.githubusercontent.com/jeFF0Falltrades/rat_king_parser/master/.github/logo.png?v=4&h=100&w=100&fit=cover&maxage=7d"/> </a> | A robust, multiprocessing-capable, multi-family RAT config parser/extractor that is compatible with MACO                                                                                                                                                      |      [![License](https://img.shields.io/github/license/jeFF0Falltrades/rat_king_parser)](https://github.com/jeFF0Falltrades/rat_king_parser/blob/master/LICENSE)       |
-|                              <a href="https://github.com/apophis133/apophis-YARA-Rules"><img src="https://images.weserv.nl/?url=github.com/apophis133.png?v=4&h=100&w=100&fit=cover&maxage=7d"/> </a>                              | A parser/extractor repository that supports MACO for performing malware configuration extraction with YARA rule detection                                                                                                                                     |                                                                                                                                                                        |
 |                           <a href="https://github.com/CAPESandbox/community"><img src="https://images.weserv.nl/?url=github.com/CAPESandbox.png?v=4&h=100&w=100&fit=cover&maxage=7d0&mask=circle"/> </a>                           | A parser/extractor repository containing MACO extractors that's authored by the CAPE community but is integrated in [CAPE](https://github.com/kevoreilly/CAPEv2) deployments.<br>**Note: These MACO extractors wrap and parse the original CAPE extractors.** |                  [![License](https://img.shields.io/badge/license-GPL--3.0-informational)](https://github.com/kevoreilly/CAPEv2/blob/master/LICENSE)                   |
 
 ## Model Example

maco-1.2.16.dist-info/RECORD

@@ -0,0 +1,49 @@
+demo_extractors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+demo_extractors/elfy.py,sha256=PQpX956WaKmGzxF0pvpXECbwSPF_j3-_SElvboYPlF8,1083
+demo_extractors/limit_other.py,sha256=lR0-7KPPDyl2UK917ev7ALhqvnPcFGsUObq7b-dESBE,1718
+demo_extractors/nothing.py,sha256=0pLL9vZESWSdNOmtzTv33Ird0QaQUmXmeW_rwu6MExU,784
+demo_extractors/requirements.txt,sha256=nD7BPNv7YEPUr9MDcaKYNs2UfHtxvN8FOKKesgC_L5g,50
+demo_extractors/shared.py,sha256=GxdUKic4N1Bu2dODo-zjvm8JMLxFIXGkgoz4PUBo-Xw,432
+demo_extractors/terminator.py,sha256=nxoZYRteYDQS7wp-aAsCaxCSJ9FSE54jPrW3fJpRVho,925
+demo_extractors/complex/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+demo_extractors/complex/complex.py,sha256=GYKmPOD8-fyVHxwjZb-3t1IghKVMuLtdUvCs5C5yPe0,2625
+demo_extractors/complex/complex_utils.py,sha256=5kdMl-niSH9d-d3ChuItpmlPT4U-S9g-iyBZlR4tfmQ,296
+maco/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+maco/base_test.py,sha256=DrVE7vOazeLQpOQeIDwBYK1WtlmdJrRe50JOqP5t4Y0,3198
+maco/cli.py,sha256=nrSukAJAthbstZT3-lQNPz4zOOMcBhvfYQqLh_B5Jdk,9457
+maco/collector.py,sha256=R3zw-fUJBlwmcSqvkQ-PnoJdHfRm2V0JAOl7N8MTAbY,8240
+maco/exceptions.py,sha256=XBHUrs1kr1ZayPI9B_W-WejKgVmC8sWL_o4RL0b4DQE,745
+maco/extractor.py,sha256=s36aGcsXSc-9iCik6iihVt5G1a1DZUA7TquvWYQNwdE,2912
+maco/utils.py,sha256=wzecqu1W_BbhDHSs07sweOKNeFrmC4CDYmAN_qyYJS4,23362
+maco/yara.py,sha256=gkHHxwZNxzZV7nHZM3HNUmhHXB7VW82voCHK5mHpt2Q,3970
+maco/model/__init__.py,sha256=ULdyHx8R5D2ICHZo3VoCk1YTlewTok36TYIpwx__pNY,45
+maco/model/model.py,sha256=DBHTmZXMzjpVq0s2mzZv3VCzPhwPnv7sH6u_QZCTcA4,24484
+maco-1.2.16.dist-info/licenses/LICENSE.md,sha256=gMSjshPhXvV_F1qxmeNkKdBqGWkd__fEJf4glS504bM,1478
+model_setup/maco/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+model_setup/maco/base_test.py,sha256=DrVE7vOazeLQpOQeIDwBYK1WtlmdJrRe50JOqP5t4Y0,3198
+model_setup/maco/cli.py,sha256=nrSukAJAthbstZT3-lQNPz4zOOMcBhvfYQqLh_B5Jdk,9457
+model_setup/maco/collector.py,sha256=R3zw-fUJBlwmcSqvkQ-PnoJdHfRm2V0JAOl7N8MTAbY,8240
+model_setup/maco/exceptions.py,sha256=XBHUrs1kr1ZayPI9B_W-WejKgVmC8sWL_o4RL0b4DQE,745
+model_setup/maco/extractor.py,sha256=s36aGcsXSc-9iCik6iihVt5G1a1DZUA7TquvWYQNwdE,2912
+model_setup/maco/utils.py,sha256=wzecqu1W_BbhDHSs07sweOKNeFrmC4CDYmAN_qyYJS4,23362
+model_setup/maco/yara.py,sha256=gkHHxwZNxzZV7nHZM3HNUmhHXB7VW82voCHK5mHpt2Q,3970
+model_setup/maco/model/__init__.py,sha256=ULdyHx8R5D2ICHZo3VoCk1YTlewTok36TYIpwx__pNY,45
+model_setup/maco/model/model.py,sha256=DBHTmZXMzjpVq0s2mzZv3VCzPhwPnv7sH6u_QZCTcA4,24484
+pipelines/publish.yaml,sha256=xt3WNU-5kIICJgKIiiE94M3dWjS3uEiun-n4OmIssK8,1471
+pipelines/test.yaml,sha256=btJVI-R39UBeYosGu7TOpU6V9ogFW3FT3ROtWygQGQ0,1472
+tests/data/example.txt.cart,sha256=j4ZdDnFNVq7lb-Qi4pY4evOXKQPKG-GSg-n-uEqPhV0,289
+tests/data/trigger_complex.txt,sha256=uqnLSrnyDGCmXwuPmZ2s8vdhH0hJs8DxvyaW_tuYY24,64
+tests/data/trigger_complex.txt.cart,sha256=Z7qF1Zi640O45Znkl9ooP2RhSLAEqY0NRf51d-q7utU,345
+tests/extractors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/extractors/basic.py,sha256=BpOgVoeeAYoRF4PYDP4llS0GrvlqcEKw1588RsnSHFc,952
+tests/extractors/basic_longer.py,sha256=2I7wWJugOB9tHtgdIvG9crbV9pEuDsuvr9OR-aHRRbs,990
+tests/extractors/test_basic.py,sha256=RZPKBP6we2DlY2qpbxYjvf8u-TPcD96ofphLQ117WPk,775
+tests/extractors/bob/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/extractors/bob/bob.py,sha256=4fpqy_O6NDinJImghyW5OwYgnaB05aY4kgoIS_C3c_U,253
+tests/extractors/import_rewriting/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/extractors/import_rewriting/importer.py,sha256=wqF1AG2zXXuj9EMt9qlDorab-UD0GYuFggtrCuz4sf0,289735
+maco-1.2.16.dist-info/METADATA,sha256=v5ZV9RoifsSn6im1tO0wpUJeKPGW3Wf-_C_BjF7qNmM,15232
+maco-1.2.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maco-1.2.16.dist-info/entry_points.txt,sha256=TpcwG1gedIg8Y7a9ZOv8aQpuwEUftCefDrAjzeP-o6U,39
+maco-1.2.16.dist-info/top_level.txt,sha256=iMRwuzmrHA3zSwiSeMIl6FWhzRpn_st-I4fAv-kw5_o,49
+maco-1.2.16.dist-info/RECORD,,

{maco-1.2.14.dist-info → maco-1.2.16.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

model_setup/maco/base_test.py

@@ -1,7 +1,6 @@
 """Foundation for unit testing an extractor.
 
 Example:
-
 from maco import base_test
 class TestExample(base_test.BaseTest):
     name = "Example"
@@ -20,13 +19,12 @@ import unittest
 import cart
 
 from maco import collector
-
-
-class NoHitException(Exception):
-    pass
+from maco.exceptions import NoHitException
 
 
 class BaseTest(unittest.TestCase):
+    """Base test class."""
+
     name: str = None  # name of the extractor
     # folder and/or file where extractor is.
     # I recommend something like os.path.join(__file__, "../../extractors")
@@ -36,6 +34,11 @@ class BaseTest(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls) -> None:
+        """Initialization of class.
+
+        Raises:
+            Exception: when name or path is not set.
+        """
         if not cls.name or not cls.path:
             raise Exception("name and path must be set")
         cls.c = collector.Collector(cls.path, include=[cls.name], create_venv=cls.create_venv)
@@ -47,7 +50,11 @@ class BaseTest(unittest.TestCase):
         self.assertEqual(len(self.c.extractors), 1)
 
     def extract(self, stream):
-        """Return results for running extractor over stream, including yara check."""
+        """Return results for running extractor over stream, including yara check.
+
+        Raises:
+            NoHitException: when yara rule doesn't hit.
+        """
         runs = self.c.match(stream)
         if not runs:
             raise NoHitException("no yara rule hit")
@@ -65,7 +72,17 @@ class BaseTest(unittest.TestCase):
 
     @classmethod
     def load_cart(cls, filepath: str) -> io.BytesIO:
-        """Load and unneuter a test file (likely malware) into memory for processing."""
+        """Load and unneuter a test file (likely malware) into memory for processing.
+
+        Args:
+            filepath (str): Path to carted sample
+
+        Returns:
+            (io.BytesIO): Buffered stream containing the un-carted sample
+
+        Raises:
+            FileNotFoundError: if the path to the sample doesn't exist
+        """
         # it is nice if we can load files relative to whatever is implementing base_test
         dirpath = os.path.split(cls._get_location())[0]
         # either filepath is absolute, or should be loaded relative to child of base_test

model_setup/maco/cli.py

@@ -3,19 +3,18 @@
 import argparse
 import base64
 import binascii
-import cart
 import hashlib
 import io
 import json
 import logging
 import os
 import sys
-
 from importlib.metadata import version
 from typing import BinaryIO, List, Tuple
 
-from maco import collector
+import cart
 
+from maco import collector
 
 logger = logging.getLogger("maco.lib.cli")
 
@@ -29,7 +28,20 @@ def process_file(
     force: bool,
     include_base64: bool,
 ):
-    """Process a filestream with the extractors and rules."""
+    """Process a filestream with the extractors and rules.
+
+    Args:
+        collected (collector.Collector): a Collector instance
+        path_file (str): path to sample to be analyzed
+        stream (BinaryIO): binary stream to be analyzed
+        pretty (bool): Pretty print the JSON output
+        force (bool): Run all extractors regardless of YARA rule match
+        include_base64 (bool): include base64'd data in output
+
+    Returns:
+        (dict): The output from the extractors analyzing the sample
+
+    """
     unneutered = io.BytesIO()
     try:
         cart.unpack_stream(stream, unneutered)
@@ -98,7 +110,8 @@ def process_filesystem(
 ) -> Tuple[int, int, int]:
     """Process filesystem with extractors and print results of extraction.
 
-    Returns total number of analysed files, yara hits and successful maco extractions.
+    Returns:
+        (Tuple[int, int, int]): Total number of analysed files, yara hits and successful maco extractions.
     """
     if force:
         logger.warning("force execute will cause errors if an extractor requires a yara rule hit during execution")
@@ -163,6 +176,7 @@ def process_filesystem(
 
 
 def main():
+    """Main block for CLI."""
     parser = argparse.ArgumentParser(description="Run extractors over samples.")
     parser.add_argument("extractors", type=str, help="path to extractors")
     parser.add_argument("samples", type=str, help="path to samples")