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

model_setup/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

model_setup/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:

model_setup/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)

tests/extractors/basic.py

@@ -1,5 +1,7 @@
+"""Basic extractor."""
+
 from io import BytesIO
-from typing import List, Optional
+from typing import List
 
 from maco import extractor, model, yara
 
@@ -21,7 +23,13 @@ class Basic(extractor.Extractor):
         }
         """
 
-    def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+    def run(self, stream: BytesIO, matches: List[yara.Match]) -> model.ExtractorModel:
+        """Run the extractor.
+
+        Returns:
+            (model.ExtractorModel): Results from extractor
+
+        """
         # use a custom model that inherits from ExtractorModel
         # this model defines what can go in the 'other' dict
         tmp = model.ExtractorModel(family="basic")

tests/extractors/basic_longer.py

@@ -1,5 +1,7 @@
+"""Basic longer extractor."""
+
 from io import BytesIO
-from typing import List, Optional
+from typing import List
 
 from maco import extractor, model, yara
 
@@ -21,7 +23,12 @@ class BasicLonger(extractor.Extractor):
         }
         """
 
-    def run(self, stream: BytesIO, matches: List[yara.Match]) -> Optional[model.ExtractorModel]:
+    def run(self, stream: BytesIO, matches: List[yara.Match]) -> model.ExtractorModel:
+        """Run the extractor.
+
+        Returns:
+            (model.ExtractorModel): Results from extractor
+        """
         # use a custom model that inherits from ExtractorModel
         # this model defines what can go in the 'other' dict
         tmp = model.ExtractorModel(family="basic_longer")

tests/extractors/bob/bob.py

@@ -1,3 +1,5 @@
+"""Simple extractor for testing module and submodule with the same name."""
+
 from maco import extractor