maco 1.2.13__py3-none-any.whl → 1.2.15__py3-none-any.whl

maco/utils.py

@@ -1,4 +1,5 @@
-# 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
@@ -33,8 +34,8 @@ from typing import Callable, Dict, List, Set, 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 +51,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 +136,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 +203,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 +313,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)
@@ -311,6 +351,16 @@ def register_extractors(
     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
+        default_loaded_modules (Set[str]): Set of default loaded modules
+    """
     package_name = os.path.basename(current_directory)
     parent_directory = os.path.dirname(current_directory)
     if venvs and package_name in sys.modules:
@@ -413,6 +463,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 +509,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.13.dist-info → maco-1.2.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: maco
-Version: 1.2.13
+Version: 1.2.15
 Author: sl-govau
 Maintainer: cccs-rs
 License: MIT License
@@ -33,9 +33,9 @@ Requires-Dist: cart
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Requires-Dist: uv
-Requires-Dist: yara-python
 Requires-Dist: yara-x==0.11.0
 Requires-Dist: multiprocess>=0.70.17
+Dynamic: license-file
 
 # Maco - Malware config extractor framework
 
@@ -70,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.15.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=rXKrrKTNi7DEC5SZUnUQcxnRRmJXRp0y4DuVaDkBYvY,24977
+maco/yara.py,sha256=gkHHxwZNxzZV7nHZM3HNUmhHXB7VW82voCHK5mHpt2Q,3970
+maco/model/__init__.py,sha256=ULdyHx8R5D2ICHZo3VoCk1YTlewTok36TYIpwx__pNY,45
+maco/model/model.py,sha256=whdeqwphReHpgQ5f6kODB7pQI3UEylTTiVqNq_FHNBg,24156
+maco-1.2.15.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=rXKrrKTNi7DEC5SZUnUQcxnRRmJXRp0y4DuVaDkBYvY,24977
+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=whdeqwphReHpgQ5f6kODB7pQI3UEylTTiVqNq_FHNBg,24156
+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.15.dist-info/METADATA,sha256=BBjPNqDyPQPPwFHL0G0LqOrM2zYURFENydH2K63J6aU,15232
+maco-1.2.15.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maco-1.2.15.dist-info/entry_points.txt,sha256=TpcwG1gedIg8Y7a9ZOv8aQpuwEUftCefDrAjzeP-o6U,39
+maco-1.2.15.dist-info/top_level.txt,sha256=iMRwuzmrHA3zSwiSeMIl6FWhzRpn_st-I4fAv-kw5_o,49
+maco-1.2.15.dist-info/RECORD,,

{maco-1.2.13.dist-info → maco-1.2.15.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")

model_setup/maco/collector.py

@@ -13,18 +13,20 @@ from multiprocess import Manager, Process, Queue
 from pydantic import BaseModel
 
 from maco import extractor, model, utils, yara
-from maco.exceptions import AnalysisAbortedException
-
-
-class ExtractorLoadError(Exception):
-    pass
-
+from maco.exceptions import AnalysisAbortedException, ExtractorLoadError
 
 logger = logging.getLogger("maco.lib.helpers")
 
 
 def _verify_response(resp: Union[BaseModel, dict]) -> Dict:
-    """Enforce types and verify properties, and remove defaults."""
+    """Enforce types and verify properties, and remove defaults.
+
+    Args:
+        resp (Union[BaseModel, dict])): results from extractor
+
+    Returns:
+        (Dict): results from extractor after verification
+    """
     if not resp:
         return None
     # check the response is valid for its own model
@@ -62,6 +64,8 @@ class ExtractorRegistration(TypedDict):
 
 
 class Collector:
+    """Discover and load extractors from file system."""
+
     def __init__(
         self,
         path_extractors: str,
@@ -70,7 +74,11 @@ class Collector:
         create_venv: bool = False,
         skip_install: bool = False,
     ):
-        """Discover and load extractors from file system."""
+        """Discover and load extractors from file system.
+
+        Raises:
+            ExtractorLoadError: when no extractors are found
+        """
         # maco requires the extractor to be imported directly, so ensure they are available on the path
         full_path_extractors = os.path.abspath(path_extractors)
         full_path_above_extractors = os.path.dirname(full_path_extractors)
@@ -175,7 +183,15 @@ class Collector:
         stream: BinaryIO,
         extractor_name: str,
     ) -> Dict[str, Any]:
-        """Run extractor with stream and verify output matches the model."""
+        """Run extractor with stream and verify output matches the model.
+
+        Args:
+            stream (BinaryIO): Binary stream to analyze
+            extractor_name (str): Name of extractor to analyze stream
+
+        Returns:
+            (Dict[str, Any]): Results from extractor
+        """
         extractor = self.extractors[extractor_name]
         try:
             # Run extractor on a copy of the sample

model_setup/maco/exceptions.py

@@ -1,3 +1,33 @@
+"""Exception classes for extractors."""
+
+
 # Can be raised by extractors to abort analysis of a sample
 # ie. Can abort if preliminary checks at start of run indicate the file shouldn't be analyzed by extractor
-class AnalysisAbortedException(Exception): ...
+class AnalysisAbortedException(Exception):
+    """Raised when extractors voluntarily abort analysis of a sample."""
+
+    pass
+
+
+class ExtractorLoadError(Exception):
+    """Raised when extractors cannot be loaded."""
+
+    pass
+
+
+class InvalidExtractor(ValueError):
+    """Raised when an extractor is invalid."""
+
+    pass
+
+
+class NoHitException(Exception):
+    """Raised when the YARA rule of an extractor doesn't hit."""
+
+    pass
+
+
+class SyntaxError(Exception):
+    """Raised when there's a syntax error in the YARA rule."""
+
+    pass

model_setup/maco/extractor.py

@@ -4,14 +4,8 @@ import logging
 import textwrap
 from typing import BinaryIO, List, Optional, Union
 
-from maco import yara
-
-from . import model
-
-
-class InvalidExtractor(ValueError):
-    pass
-
+from maco import model, yara
+from maco.exceptions import InvalidExtractor
 
 DEFAULT_YARA_RULE = """
 rule {name}
@@ -37,6 +31,11 @@ class Extractor:
     logger: logging.Logger = None  # logger for use when debugging
 
     def __init__(self) -> None:
+        """Initialise the extractor.
+
+        Raises:
+            InvalidExtractor: When the extractor is invalid.
+        """
         self.name = name = type(self).__name__
         self.logger = logging.getLogger(f"maco.extractor.{name}")
         self.logger.debug(f"initialise '{name}'")