yaralyzer 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

yaralyzer/output/file_hashes_table.py

@@ -1,5 +1,5 @@
 """
-Methods for building Rich layout elements for display of results.
+Methods for computing and displaying various file hashes.
 """
 import hashlib
 from collections import namedtuple
@@ -18,7 +18,18 @@ def bytes_hashes_table(
     title: Optional[str] = None,
     title_justify: str = LEFT
 ) -> Table:
-    """Build a table to show the MD5, SHA1, SHA256, etc."""
+    """
+    Build a Rich `Table` displaying the size, MD5, SHA1, and SHA256 hashes of a byte sequence.
+
+    Args:
+        bytes_or_bytes_info (Union[bytes, BytesInfo]): The `bytes` to hash, or a `BytesInfo`
+            namedtuple with precomputed values.
+        title (Optional[str], optional): Optional title for the table. Defaults to `None`.
+        title_justify (str, optional): Justification for the table title. Defaults to `"LEFT"`.
+
+    Returns:
+        Table: A Rich `Table` object with the size and hash values.
+    """
     if isinstance(bytes_or_bytes_info, bytes):
         bytes_info = compute_file_hashes(bytes_or_bytes_info)
     else:
@@ -40,6 +51,15 @@ def bytes_hashes_table(
 
 
 def compute_file_hashes(_bytes: bytes) -> BytesInfo:
+    """
+    Compute the size, MD5, SHA1, and SHA256 hashes for a given byte sequence.
+
+    Args:
+        _bytes (bytes): The `bytes` to hash.
+
+    Returns:
+        BytesInfo: `BytesInfo` namedtuple containing size, md5, sha1, and sha256 values.
+    """
     return BytesInfo(
         size=len(_bytes),
         md5=hashlib.md5(_bytes).hexdigest().upper(),
@@ -49,5 +69,14 @@ def compute_file_hashes(_bytes: bytes) -> BytesInfo:
 
 
 def compute_file_hashes_for_file(file_path) -> BytesInfo:
+    """
+    Compute the size, MD5, SHA1, and SHA256 hashes for the contents of a file.
+
+    Args:
+        file_path (str): Path to the file to hash.
+
+    Returns:
+        BytesInfo: `BytesInfo` namedtuple containing size, md5, sha1, and sha256 values for the file contents.
+    """
     with open(file_path, 'rb') as file:
         return compute_file_hashes(file.read())

yaralyzer/output/regex_match_metrics.py

@@ -1,12 +1,5 @@
 """
-Class to  measure what we enounter as we iterate over every single match of a relatively simple byte level regex
-(e.g. "bytes between quotes") against a relatively large pool of close to random encrypted binary data
-
-Things like how much many of our matched bytes were we able to decode easily vs. by force vs. not at all,
-were some encodings have a higher pct of success than others (indicating part of our mystery data might be encoded
-that way?
-
-TODO: use @dataclass decorator https://realpython.com/python-data-classes/
+`RegexMatchMetrics` class.
 """
 from collections import defaultdict
 
@@ -15,6 +8,30 @@ from yaralyzer.util.logging import log
 
 
 class RegexMatchMetrics:
+    """
+    Class to measure what we enounter as we iterate over all matches of a relatively simple byte level regex.
+
+    Things like how much many of our matched bytes were we able to decode easily vs. by force vs. not at all,
+    were some encodings have a higher pct of success than others (indicating part of our mystery data might be
+    encoded that way?
+
+    Example:
+        "Find bytes between quotes" against a relatively large pool of close to random encrypted binary data.
+
+    Attributes:
+        match_count (int): Total number of matches found.
+        bytes_matched (int): Total number of bytes matched across all matches.
+        matches_decoded (int): Number of matches where we were able to decode at least some of the matched bytes.
+        easy_decode_count (int): Number of matches where we were able to decode the matched bytes without forcing.
+        forced_decode_count (int): Number of matches where we were only able to decode the matched bytes by forcing.
+        undecodable_count (int): Number of matches where we were unable to decode any of the matched bytes.
+        skipped_matches_lengths (defaultdict): Dictionary mapping lengths of skipped matches to their counts.
+        bytes_match_objs (list): List of `BytesMatch` objects for all matches encountered.
+        per_encoding_stats (defaultdict): Dictionary mapping encoding names to their respective `RegexMatchMetrics`.
+
+    TODO: use @dataclass decorator https://realpython.com/python-data-classes/
+    """
+
     def __init__(self) -> None:
         self.match_count = 0
         self.bytes_matched = 0
@@ -27,12 +44,20 @@ class RegexMatchMetrics:
         self.per_encoding_stats = defaultdict(lambda: RegexMatchMetrics())
 
     def num_matches_skipped_for_being_empty(self) -> int:
+        """Number of matches skipped for being empty (0 length)."""
         return self.skipped_matches_lengths[0]
 
     def num_matches_skipped_for_being_too_big(self) -> int:
+        """Number of matches skipped for being too big to decode."""
         return sum({k: v for k, v in self.skipped_matches_lengths.items() if k > 0}.values())
 
     def tally_match(self, decoder: BytesDecoder) -> None:
+        """
+        Tally statistics from a `BytesDecoder` after it has processed a match.
+
+        Args:
+            decoder (BytesDecoder): The `BytesDecoder` that processed a match.
+        """
         log.debug(f"Tallying {decoder.bytes_match} ({len(decoder.decodings)} decodings)")
         self.match_count += 1
         self.bytes_matched += decoder.bytes_match.match_length

yaralyzer/output/rich_console.py

@@ -81,15 +81,11 @@ YARALYZER_THEME = Theme(YARALYZER_THEME_DICT)
 
 
 def console_width_possibilities():
+    """Returns a list of possible console widths, the first being the current terminal width."""
     # Subtract 2 from terminal cols just as a precaution in case things get weird
     return [get_terminal_size().columns - 2, DEFAULT_CONSOLE_WIDTH]
 
 
-def console_width() -> int:
-    """Current width set in console obj"""
-    return console._width or 40
-
-
 # Maximize output width if YARALYZER_MAXIMIZE_WIDTH is set (also can changed with --maximize-width option)
 if is_invoked_by_pytest():
     CONSOLE_WIDTH = DEFAULT_CONSOLE_WIDTH
@@ -103,8 +99,8 @@ CONSOLE_PRINT_BYTE_WIDTH = int(CONSOLE_WIDTH / 4.0)
 console = Console(theme=YARALYZER_THEME, color_system='256', highlight=False, width=CONSOLE_WIDTH)
 
 
-def console_print_with_fallback(_string, style=None) -> None:
-    """Fallback to regular print() if there's a Markup issue"""
+def console_print_with_fallback(_string: Text | str, style=None) -> None:
+    """`rich.console.print()` with fallback to regular `print()` if there's a Rich Markup issue."""
     try:
         console.print(_string, style=style)
     except MarkupError:
@@ -112,11 +108,18 @@ def console_print_with_fallback(_string, style=None) -> None:
         print(_string.plain if isinstance(_string, Text) else _string)
 
 
-def theme_colors_with_prefix(prefix: str) -> List[Text]:
-    return [Text(k, v) for k, v in YARALYZER_THEME.styles.items() if k.startswith(prefix)]
+def console_width() -> int:
+    """Current width set in `console` object."""
+    return console._width or 40
 
 
 def print_fatal_error_and_exit(error_message: str) -> None:
+    """
+    Print a fatal error message in a `Panel` and exit.
+
+    Args:
+        error_message (str): The error message to display.
+    """
     console.line(1)
     print_header_panel(error_message, style='bold red reverse')
     console.line(1)
@@ -124,4 +127,18 @@ def print_fatal_error_and_exit(error_message: str) -> None:
 
 
 def print_header_panel(headline: str, style: str, expand: bool = True, padding: tuple = (0, 2)) -> None:
+    """
+    Print a headline inside a styled Rich `Panel` to the console.
+
+    Args:
+        headline (str): The text to display as the panel's headline.
+        style (str): The style to apply to the panel (e.g., color, bold, reverse).
+        expand (bool, optional): Whether the panel should expand to the full console width. Defaults to `True`.
+        padding (tuple, optional): Padding around the panel content (top/bottom, left/right). Defaults to `(0, 2)`.
+    """
     console.print(Panel(headline, box=box.DOUBLE_EDGE, style=style, expand=expand, padding=padding))
+
+
+def theme_colors_with_prefix(prefix: str) -> List[Text]:
+    """Return a list of (name, style) `Text` objects for all styles in the theme that start with `prefix`."""
+    return [Text(k, v) for k, v in YARALYZER_THEME.styles.items() if k.startswith(prefix)]

yaralyzer/util/argument_parser.py

@@ -1,3 +1,4 @@
+"""Argument parsing for yaralyzer CLI tool."""
 import logging
 import re
 import sys
@@ -217,9 +218,16 @@ YaralyzerConfig.set_argument_parser(parser)
 
 def parse_arguments(args: Optional[Namespace] = None):
     """
-    Parse command line args. Most settings can be communicated to the app by setting env vars.
-    If args are passed neither rules nor a regex need be provided as it is assumed
-    the constructor will instantiate a Yaralyzer object directly.
+    Parse command line args. Most arguments can also be communicated to the app by setting env vars.
+    If `args` are passed neither rules nor a regex need be provided as it is assumed
+    the constructor will instantiate a `Yaralyzer` object directly.
+
+    Args:
+        args (Optional[Namespace], optional): If provided, use these args instead of parsing from command line.
+            Defaults to `None`.
+
+    Raises:
+        ArgumentError: If args are invalid.
     """
     if '--version' in sys.argv:
         print(f"yaralyzer {version('yaralyzer')}")
@@ -281,6 +289,7 @@ def parse_arguments(args: Optional[Namespace] = None):
 
 
 def get_export_basepath(args: Namespace, yaralyzer: Yaralyzer):
+    """Get the basepath (directory + filename without extension) for exported files."""
     file_prefix = (args.file_prefix + '_') if args.file_prefix else ''
     args.output_basename  = f"{file_prefix}{yaralyzer._filename_string()}"  # noqa: E221
     args.output_basename += f"__maxdecode{YaralyzerConfig.args.max_decode_length}"

yaralyzer/util/logging.py

@@ -1,28 +1,34 @@
 """
-There's two possible log sinks other than STDOUT:
+Handle logging for `yaralyzer`.
 
-  1. 'log' - the application log (standard log, what goes to STDOUT with -D option)
+There's two possible log sinks other than `STDOUT`:
+
+  1. 'log' - the application log (standard log, what goes to `STDOUT` with `-D` option)
   2. 'invocation_log' - tracks the exact command yaralyzer was invoked with, similar to a history file
 
-The regular log file at APPLICATION_LOG_PATH is where the quite verbose application logs
+The regular log file at `APPLICATION_LOG_PATH` is where the quite verbose application logs
 will be written if things ever need to get that formal. For now those logs are only accessible
-on STDOUT with the -D flag but the infrastructure for persistent logging exists if someone
+on `STDOUT` with the `-D` flag but the infrastructure for persistent logging exists if someone
 needs/wants that sort of thing.
 
-Logs are not normally ephemeral/not written  to files but can be configured to do so by setting
-the YARALYZER_LOG_DIR env var. See .yaralyzer.example for documentation about the side effects of setting
-YARALYZER_LOG_DIR to a value.
+Logs are not normally ephemeral/not written to files but can be configured to do so by setting
+the `YARALYZER_LOG_DIR` env var. See `.yaralyzer.example` for documentation about the side effects
+of setting `YARALYZER_LOG_DIR` to a value.
+
+* [logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig)
 
-https://docs.python.org/3/library/logging.html#logging.basicConfig
-https://realpython.com/python-logging/
+* [realpython.com/python-logging/](https://realpython.com/python-logging/)
 
 Python log levels for reference:
+
+```
     CRITICAL 50
     ERROR 40
     WARNING 30
     INFO 20
     DEBUG 10
     NOTSET 0
+```
 """
 import logging
 import sys
@@ -37,13 +43,22 @@ ARGPARSE_LOG_FORMAT = '{0: >30}    {1: <17} {2: <}\n'
 
 
 def configure_logger(log_label: str) -> logging.Logger:
-    """Set up a file or stream logger depending on the configuration"""
+    """
+    Set up a file or stream `logger` depending on the configuration.
+
+    Args:
+        log_label (str): The label for the `logger`, e.g. "run" or "invocation".
+            Actual name will be `"yaralyzer.{log_label}"`.
+
+    Returns:
+        logging.Logger: The configured `logger`.
+    """
     log_name = f"yaralyzer.{log_label}"
     logger = logging.getLogger(log_name)
 
     if YaralyzerConfig.LOG_DIR:
         if not path.isdir(YaralyzerConfig.LOG_DIR) or not path.isabs(YaralyzerConfig.LOG_DIR):
-            raise RuntimeError(f"Log dir '{YaralyzerConfig.LOG_DIR}' doesn't exist or is not absolute")
+            raise FileNotFoundError(f"Log dir '{YaralyzerConfig.LOG_DIR}' doesn't exist or is not absolute")
 
         log_file_path = path.join(YaralyzerConfig.LOG_DIR, f"{log_name}.log")
         log_formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
@@ -70,14 +85,14 @@ if YaralyzerConfig.LOG_DIR:
     invocation_log.setLevel('INFO')
 
 
-def log_and_print(msg: str, log_level='INFO'):
-    """Both print and log (at INFO level) a string"""
+def log_and_print(msg: str, log_level: str = 'INFO'):
+    """Both print (to console) and log (to file) a string."""
     log.log(logging.getLevelName(log_level), msg)
     print(msg)
 
 
 def log_current_config():
-    """Write current state of YaralyzerConfig object to the logs"""
+    """Write current state of `YaralyzerConfig` object to the logs."""
     msg = f"{YaralyzerConfig.__name__} current attributes:\n"
     config_dict = {k: v for k, v in vars(YaralyzerConfig).items() if not k.startswith('__')}
 
@@ -88,14 +103,14 @@ def log_current_config():
 
 
 def log_invocation() -> None:
-    """Log the command used to launch the yaralyzer to the invocation log"""
+    """Log the command used to launch the `yaralyzer` to the invocation log."""
     msg = f"THE INVOCATION: '{' '.join(sys.argv)}'"
     log.info(msg)
     invocation_log.info(msg)
 
 
 def log_argparse_result(args, label: str):
-    """Logs the result of argparse"""
+    """Logs the result of `argparse`."""
     args_dict = vars(args)
     log_msg = f'{label} argparse results:\n' + ARGPARSE_LOG_FORMAT.format('OPTION', 'TYPE', 'VALUE')
 

yaralyzer/yara/yara_match.py

@@ -1,17 +1,22 @@
 """
-Rich text decorator for YARA match dicts, which look like this:
-
-{
-    'tags': ['foo', 'bar'],
-    'matches': True,
-    'namespace': 'default',
-    'rule': 'my_rule',
-    'meta': {},
-    'strings': [
-        StringMatch1,
-        StringMatch2
-    ]
-}
+Rich text decorator for YARA match dicts.
+
+A YARA match is returned as a `dict` with this structure:
+
+Example:
+    ```
+    {
+        'tags': ['foo', 'bar'],
+        'matches': True,
+        'namespace': 'default',
+        'rule': 'my_rule',
+        'meta': {},
+        'strings': [
+            StringMatch1,
+            StringMatch2
+        ]
+    }
+    ```
 """
 import re
 from numbers import Number
@@ -30,11 +35,12 @@ from yaralyzer.output.rich_console import console_width, theme_colors_with_prefi
 from yaralyzer.util.logging import log
 
 MATCH_PADDING = (0, 0, 0, 1)
-URL_REGEX = re.compile('^https?:')
+
+DATE_REGEX = re.compile('\\d{4}-\\d{2}-\\d{2}')
 DIGITS_REGEX = re.compile("^\\d+$")
 HEX_REGEX = re.compile('^[0-9A-Fa-f]+$')
-DATE_REGEX = re.compile('\\d{4}-\\d{2}-\\d{2}')
 MATCHER_VAR_REGEX = re.compile('\\$[a-z_]+')
+URL_REGEX = re.compile('^https?:')
 
 YARA_STRING_STYLES: Dict[re.Pattern, str] = {
     URL_REGEX: 'yara.url',
@@ -50,14 +56,21 @@ RAW_YARA_THEME_TXT.justify = CENTER
 
 
 class YaraMatch:
+    """Rich text decorator for YARA match dicts."""
+
     def __init__(self, match: dict, matched_against_bytes_label: Text) -> None:
+        """
+        Args:
+            match (dict): The YARA match dict.
+            matched_against_bytes_label (Text): Label indicating what bytes were matched against.
+        """
         self.match = match
         self.rule_name = match['rule']
         self.label = matched_against_bytes_label.copy().append(f" matched rule: '", style='matched_rule')
         self.label.append(self.rule_name, style='on bright_red bold').append("'!", style='siren')
 
     def __rich_console__(self, _console: Console, options: ConsoleOptions) -> RenderResult:
-        """Renders a panel showing the color highlighted raw YARA match info."""
+        """Renders a rich `Panel` showing the color highlighted raw YARA match info."""
         yield Text("\n")
         yield Padding(Panel(self.label, expand=False, style=f"on color(251) reverse"), MATCH_PADDING)
         yield RAW_YARA_THEME_TXT
@@ -65,7 +78,16 @@ class YaraMatch:
 
 
 def _rich_yara_match(element: Any, depth: int = 0) -> Text:
-    """Painful/hacky way of recursively coloring a yara result hash."""
+    """
+    Painful/hacky way of recursively coloring a YARA match dict.
+
+    Args:
+        element (Any): The element to render (can be `dict`, `list`, `str`, `bytes`, `int`, `bool`).
+        depth (int): Current recursion depth (used for indentation).
+
+    Returns:
+        Text: The rich `Text` representation of the element.
+    """
     indent = Text((depth + 1) * INDENT_SPACES)
     end_indent = Text(depth * INDENT_SPACES)
 
@@ -130,6 +152,7 @@ def _rich_yara_match(element: Any, depth: int = 0) -> Text:
 
 
 def _yara_string(_string: str) -> Text:
+    """Apply special styles to certain types of yara strings (e.g. URLs, numbers, hex, dates, matcher vars)."""
     for regex in YARA_STRING_STYLES.keys():
         if regex.match(_string):
             return Text(_string, YARA_STRING_STYLES[regex])

yaralyzer/yara/yara_rule_builder.py

@@ -1,6 +1,9 @@
 """
-Builds bare bones YARA rules to match strings and regex patterns. Example rule string:
+Builds bare bones YARA rules to match strings and regex patterns.
 
+Example rule string:
+
+```
 rule Just_A_Piano_Man {
     meta:
         author           = "Tim"
@@ -9,19 +12,23 @@ rule Just_A_Piano_Man {
     condition:
         $hilton_producer
 }
+```
 """
 import re
-from typing import Optional
+from typing import Literal, Optional
 
 import yara
 
 from yaralyzer.config import YARALYZE
 from yaralyzer.util.logging import log
 
+PatternType = Literal['hex', 'regex']
+YaraModifierType = Literal['ascii', 'fullword', 'nocase', 'wide']
+
 HEX = 'hex'
+PATTERN = 'pattern'
 REGEX = 'regex'
 RULE = 'rule'
-PATTERN = 'pattern'
 UNDERSCORE = '_'
 YARA_REGEX_MODIFIERS = ['nocase', 'ascii', 'wide', 'fullword']
 
@@ -60,12 +67,25 @@ rule {rule_name} {{
 
 def yara_rule_string(
     pattern: str,
-    pattern_type: str = REGEX,
+    pattern_type: PatternType = REGEX,
     rule_name: str = YARALYZE,
     pattern_label: Optional[str] = PATTERN,
-    modifier: Optional[str] = None
+    modifier: Optional[YaraModifierType] = None
 ) -> str:
-    """Build a YARA rule string for a given pattern"""
+    """
+    Build a YARA rule string for a given `pattern`.
+
+    Args:
+        pattern (str): The string or regex pattern to match.
+        pattern_type (str): Either `"regex"` or `"hex"`. Default is `"regex"`.
+        rule_name (str): The name of the YARA rule. Default is `"YARALYZE"`.
+        pattern_label (Optional[str]): The label for the pattern in the YARA rule. Default is `"pattern"`.
+        modifier (Optional[str]): Optional regex modifier (e.g. 'nocase', 'ascii', 'wide', 'fullword').
+            Only valid if `pattern_type` is `"regex"`.
+
+    Returns:
+        str: The constructed YARA rule as a string.
+    """
     if not (modifier is None or modifier in YARA_REGEX_MODIFIERS):
         raise TypeError(f"Modifier '{modifier}' is not one of {YARA_REGEX_MODIFIERS}")
 
@@ -73,6 +93,8 @@ def yara_rule_string(
         pattern = f"/{pattern}/"
     elif pattern_type == HEX:
         pattern = f"{{{pattern}}}"
+    else:
+        raise ValueError(f"pattern_type must be either '{REGEX}' or '{HEX}'")
 
     if modifier:
         pattern += f" {modifier}"
@@ -81,7 +103,8 @@ def yara_rule_string(
         rule_name=rule_name,
         pattern_label=pattern_label,
         pattern=pattern,
-        modifier='' if modifier is None else f" {modifier}")
+        modifier='' if modifier is None else f" {modifier}"
+    )
 
     log.debug(f"Built YARA rule: \n{rule}")
     return rule
@@ -89,18 +112,39 @@ def yara_rule_string(
 
 def build_yara_rule(
     pattern: str,
-    pattern_type: str = REGEX,
+    pattern_type: PatternType = REGEX,
     rule_name: str = YARALYZE,
     pattern_label: Optional[str] = PATTERN,
-    modifier: Optional[str] = None
+    modifier: Optional[YaraModifierType] = None
 ) -> yara.Rule:
-    """Build a compiled YARA rule"""
+    """
+    Build a compiled `yara.Rule` object.
+
+    Args:
+        pattern (str): The string or regex pattern to match.
+        pattern_type (str): Either `"regex"` or `"hex"`. Default is `"regex"`.
+        rule_name (str): The name of the YARA rule. Default is `"YARALYZE"`.
+        pattern_label (Optional[str]): The label for the pattern in the YARA rule. Default is `"pattern"`.
+        modifier (Optional[str]): Optional regex modifier (e.g. 'nocase', 'ascii', 'wide', 'fullword').
+            Only valid if `pattern_type` is `"regex"`.
+
+    Returns:
+        yara.Rule: Compiled YARA rule object.
+    """
     rule_string = yara_rule_string(pattern, pattern_type, rule_name, pattern_label, modifier)
     return yara.compile(source=rule_string)
 
 
 def safe_label(_label: str) -> str:
-    """YARA rule and pattern names can only contain alphanumeric chars"""
+    """
+    YARA rule and pattern names can only contain alphanumeric chars.
+
+    Args:
+        _label (str): The label to sanitize.
+
+    Returns:
+        str: A sanitized label safe for use in YARA rules.
+    """
     label = _label
 
     for char, replacement in SAFE_LABEL_REPLACEMENTS.items():