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

demo_extractors/complex/complex.py

@@ -1,3 +1,5 @@
+"""Demo complex extractor."""
+
 from io import BytesIO
 from typing import List, Optional
 
@@ -39,6 +41,16 @@ class Complex(extractor.Extractor):
         """
 
     def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+        """Run the analysis process.
+
+        Args:
+            stream (BytesIO): file object from disk/network/memory.
+            matches (List[yara.Match]): yara rule matches
+
+        Returns:
+            (Optional[model.ExtractorModel]): model of results
+
+        """
         self.logger.info("starting run")
         self.logger.debug(f"{[x.rule for x in matches]=}")
         data = stream.read()

demo_extractors/complex/complex_utils.py

@@ -1,3 +1,12 @@
-def getdata():
-    """This could be some complex and long function to support the main script."""
+"""Example of a complex function invoked by the extractor."""
+
+from typing import Dict
+
+
+def getdata() -> Dict[str, int]:
+    """This could be some complex and long function to support the main script.
+
+    Returns:
+        (Dict[str, int]): returns mock results
+    """
     return {"result": 5}

demo_extractors/elfy.py

@@ -1,3 +1,5 @@
+"""Demo extractor that targets ELF files."""
+
 from io import BytesIO
 from typing import List, Optional
 
@@ -21,6 +23,16 @@ class Elfy(extractor.Extractor):
         """
 
     def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+        """Run the analysis process.
+
+        Args:
+            stream (BytesIO): file object from disk/network/memory.
+            matches (List[yara.Match]): yara rule matches
+
+        Returns:
+            (Optional[model.ExtractorModel]): model of results
+
+        """
         # return config model formatted results
         ret = model.ExtractorModel(family=self.family)
         # the list for campaign_id already exists and is empty, so we just add an item

demo_extractors/limit_other.py

@@ -1,3 +1,5 @@
+"""Demo extractor to show the usage of the other field in the model."""
+
 from io import BytesIO
 from typing import List, Optional
 
@@ -23,6 +25,19 @@ class LimitOther(extractor.Extractor):
         """
 
     def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+        """Run the analysis process.
+
+        Args:
+            stream (BytesIO): file object from disk/network/memory.
+            matches (List[yara.Match]): yara rule matches
+
+        Returns:
+            (Optional[model.ExtractorModel]): model of results
+
+        Raises:
+            Exception: if the httpx library is not installed
+
+        """
         # import httpx at runtime so we can test that requirements.txt is installed dynamically without breaking
         # the tests that do direct importing
         import httpx

demo_extractors/nothing.py

@@ -1,7 +1,9 @@
+"""Demo extractor that returns nothing."""
+
 from io import BytesIO
-from typing import List, Optional
+from typing import List
 
-from maco import extractor, model, yara
+from maco import extractor, yara
 
 
 class Nothing(extractor.Extractor):
@@ -21,6 +23,12 @@ class Nothing(extractor.Extractor):
         }
         """
 
-    def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+    def run(self, stream: BytesIO, matches: List[yara.Match]):
+        """Run the analysis process.
+
+        Args:
+            stream (BytesIO): file object from disk/network/memory.
+            matches (List[yara.Match]): yara rule matches
+        """
         # return config model formatted results
         return

demo_extractors/shared.py

@@ -1,3 +1,5 @@
+"""Custom model based on Maco's model."""
+
 from typing import Optional
 
 import pydantic
@@ -6,7 +8,11 @@ from maco import model
 
 
 class MyCustomModel(model.ExtractorModel):
+    """Custom model based on Maco's model."""
+
     class Other(pydantic.BaseModel):
+        """Custom 'other' class."""
+
         key1: str
         key2: bool
         key3: int

demo_extractors/terminator.py

@@ -1,3 +1,5 @@
+"""Example extractor that terminates early during extraction."""
+
 from io import BytesIO
 from typing import List, Optional
 
@@ -6,12 +8,21 @@ from maco.exceptions import AnalysisAbortedException
 
 
 class Terminator(extractor.Extractor):
-    """Terminates early during extraction"""
+    """Terminates early during extraction."""
 
     family = "terminator"
     author = "skynet"
     last_modified = "1997-08-29"
 
     def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+        """Run the analysis process but terminate early.
+
+        Args:
+            stream (BytesIO): file object from disk/network/memory.
+            matches (List[yara.Match]): yara rule matches
+
+        Raises:
+            AnalysisAbortedException: Extractor has decided to terminate early
+        """
         # Terminate early and indicate I can't run on this sample
         raise AnalysisAbortedException("I can't run on this sample")

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

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")

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

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

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}'")

maco/model/model.py

@@ -29,6 +29,8 @@ class Encryption(ForbidModel):
     """Encryption usage."""
 
     class UsageEnum(str, Enum):
+        """Purpose of the encryption."""
+
         config = "config"
         communication = "communication"
         binary = "binary"
@@ -52,6 +54,8 @@ class Encryption(ForbidModel):
 
 
 class CategoryEnum(str, Enum):
+    """Category of the malware."""
+
     # Software that shows you extra promotions that you cannot control as you use your PC.
     # You wouldn't see the extra ads if you didn't have adware installed.
     adware = "adware"
@@ -274,6 +278,8 @@ class ExtractorModel(ForbidModel):
         """Binary data extracted by decoder."""
 
         class TypeEnum(str, Enum):
+            """Type of binary data."""
+
             payload = "payload"  # contained within the original file
             config = "config"  # sometimes malware uses json/formatted text for config
             other = "other"
@@ -289,6 +295,8 @@ class ExtractorModel(ForbidModel):
         # convenience for ret.encryption.append(ret.Encryption(*properties))
         # Define as class as only way to allow for this to be accessed and not have pydantic try to parse it.
         class Encryption(Encryption):
+            """Encryption usage."""
+
             pass
 
         encryption: Union[List[Encryption], Encryption, None] = None  # encryption information for the binary
@@ -436,6 +444,8 @@ class ExtractorModel(ForbidModel):
         """Direct usage of DNS."""
 
         class RecordTypeEnum(str, Enum):
+            """DNS record types."""
+
             A = "A"
             AAAA = "AAAA"
             AFSDB = "AFSDB"
@@ -512,6 +522,8 @@ class ExtractorModel(ForbidModel):
     # convenience for ret.encryption.append(ret.Encryption(*properties))
     # Define as class as only way to allow for this to be accessed and not have pydantic try to parse it.
     class Encryption(Encryption):
+        """Encryption usage."""
+
         pass
 
     encryption: List[Encryption] = []
@@ -530,6 +542,8 @@ class ExtractorModel(ForbidModel):
         """Cryptocoin usage (ransomware/miner)."""
 
         class UsageEnum(str, Enum):
+            """Cryptocoin usage."""
+
             ransomware = "ransomware"  # request money to unlock
             miner = "miner"  # use gpu/cpu to mint coins
             other = "other"
@@ -543,7 +557,11 @@ class ExtractorModel(ForbidModel):
     cryptocurrency: List[Cryptocurrency] = []
 
     class Path(ForbidModel):
+        """Path used by malware."""
+
         class UsageEnum(str, Enum):
+            """Purpose of the path."""
+
             c2 = "c2"  # file/folder issues commands to malware
             config = "config"  # config is loaded from this path
             install = "install"  # install directory/filename for malware
@@ -559,7 +577,11 @@ class ExtractorModel(ForbidModel):
     paths: List[Path] = []  # files/directories used by malware
 
     class Registry(ForbidModel):
+        """Registry usage by malware."""
+
         class UsageEnum(str, Enum):
+            """Registry usage."""
+
             persistence = "persistence"  # stay alive
             store_data = "store_data"  # generated encryption keys or config
             store_payload = "store_payload"  # malware hidden in registry key