yaralyzer 1.0.11__py3-none-any.whl

yaralyzer/util/argument_parser.py

@@ -0,0 +1,297 @@
+"""Argument parsing for yaralyzer CLI tool."""
+import logging
+import re
+import sys
+from argparse import ArgumentError, ArgumentParser, Namespace
+from collections import namedtuple
+from importlib.metadata import version
+from os import getcwd, path
+from typing import Optional
+
+from rich_argparse_plus import RichHelpFormatterPlus
+
+from yaralyzer.config import YaralyzerConfig
+from yaralyzer.encoding_detection.encoding_detector import CONFIDENCE_SCORE_RANGE, EncodingDetector
+from yaralyzer.helpers.file_helper import timestamp_for_filename
+from yaralyzer.helpers.string_helper import comma_join
+from yaralyzer.output import rich_console
+from yaralyzer.yara.yara_rule_builder import YARA_REGEX_MODIFIERS
+from yaralyzer.util.logging import log, log_argparse_result, log_current_config, log_invocation
+from yaralyzer.yaralyzer import Yaralyzer
+
+
+# NamedTuple to keep our argument selection orderly
+OutputSection = namedtuple('OutputSection', ['argument', 'method'])
+
+YARA_PATTERN_LABEL_REGEX = re.compile('^\\w+$')
+YARA_RULES_ARGS = ['yara_rules_files', 'yara_rules_dirs', 'hex_patterns', 'regex_patterns']
+DESCRIPTION = "Get a good hard colorful look at all the byte sequences that make up a YARA rule match. "
+
+EPILOG = "* Values for various config options can be set permanently by a .yaralyzer file in your home directory; " + \
+         "see the documentation for details.\n" + \
+         f"* A registry of previous yaralyzer invocations will be incribed to a file if the " + \
+         f"{YaralyzerConfig.LOG_DIR_ENV_VAR} environment variable is configured."
+
+
+# Positional args, version, help, etc
+RichHelpFormatterPlus.choose_theme('prince')
+parser = ArgumentParser(formatter_class=RichHelpFormatterPlus, description=DESCRIPTION, epilog=EPILOG)
+parser.add_argument('--version', action='store_true', help='show version number and exit')
+parser.add_argument('file_to_scan_path', metavar='FILE', help='file to scan')
+
+source = parser.add_argument_group(
+    'YARA RULES',
+    "Load YARA rules from preconfigured files or use one off YARA regular expression strings")
+
+source.add_argument('--yara-file', '-Y',
+                    help='path to a YARA rules file to check against (can be supplied more than once)',
+                    action='append',
+                    metavar='FILE',
+                    dest='yara_rules_files')
+
+source.add_argument('--rule-dir', '-dir',
+                    help='directory with yara rules files (all files are used, can be supplied more than once)',
+                    action='append',
+                    metavar='DIR',
+                    dest='yara_rules_dirs')
+
+source.add_argument('--regex-pattern', '-re',
+                    help='build a YARA rule from PATTERN and run it (can be supplied more than once for boolean OR)',
+                    action='append',
+                    metavar='PATTERN',
+                    dest='regex_patterns')
+
+source.add_argument('--hex-pattern', '-hex',
+                    help='build a YARA rule from HEX_STRING and run it (can be supplied more than once for boolean OR)',
+                    action='append',
+                    metavar='HEX_STRING',
+                    dest='hex_patterns')
+
+source.add_argument('--patterns-label', '-rpl',
+                    help='supplying an optional STRING to label your YARA patterns makes it easier to scan results',
+                    metavar='STRING')
+
+source.add_argument('--regex-modifier', '-mod',
+                    help=f"optional modifier keyword for YARA regexes ({comma_join(YARA_REGEX_MODIFIERS)})",
+                    metavar='MODIFIER',
+                    choices=YARA_REGEX_MODIFIERS)
+
+# Fine tuning
+tuning = parser.add_argument_group(
+    'FINE TUNING',
+    "Tune various aspects of the analyses and visualizations to your needs. As an example setting " +
+        "a low --max-decode-length (or suppressing brute force binary decode attempts altogether) can " +
+        "dramatically improve run times and only occasionally leads to a fatal lack of insight.")
+
+tuning.add_argument('--maximize-width', action='store_true',
+                    help="maximize the display width to fill the terminal")
+
+tuning.add_argument('--surrounding-bytes',
+                    help="number of bytes to display/decode before and after YARA match start positions",
+                    default=YaralyzerConfig.DEFAULT_SURROUNDING_BYTES,
+                    metavar='N',
+                    type=int)
+
+tuning.add_argument('--suppress-decodes-table', action='store_true',
+                    help='suppress decodes table entirely (including hex/raw output)')
+
+tuning.add_argument('--suppress-decoding-attempts', action='store_true',
+                    help='suppress decode attempts for matched bytes (only hex/raw output will be shown)')
+
+tuning.add_argument('--min-decode-length',
+                    help='suppress decode attempts for quoted byte sequences shorter than N',
+                    default=YaralyzerConfig.DEFAULT_MIN_DECODE_LENGTH,
+                    metavar='N',
+                    type=int)
+
+tuning.add_argument('--max-decode-length',
+                    help='suppress decode attempts for quoted byte sequences longer than N',
+                    default=YaralyzerConfig.DEFAULT_MAX_DECODE_LENGTH,
+                    metavar='N',
+                    type=int)
+
+tuning.add_argument('--suppress-chardet', action='store_true',
+                    help="suppress the display of the full table of chardet's encoding likelihood scores")
+
+tuning.add_argument('--min-chardet-bytes',
+                    help="minimum number of bytes to run chardet.detect() and the decodings it suggests",
+                    default=YaralyzerConfig.DEFAULT_MIN_CHARDET_BYTES,
+                    metavar='N',
+                    type=int)
+
+tuning.add_argument('--min-chardet-table-confidence',
+                    help="minimum chardet confidence to display the encoding name/score in the character " +
+                         "decection scores table",
+                    default=YaralyzerConfig.DEFAULT_MIN_CHARDET_TABLE_CONFIDENCE,
+                    metavar='PCT_CONFIDENCE',
+                    type=int)
+
+tuning.add_argument('--force-display-threshold',
+                    help="encodings with chardet confidence below this number will neither be displayed nor " +
+                         "decoded in the decodings table",
+                    default=EncodingDetector.force_display_threshold,
+                    metavar='PCT_CONFIDENCE',
+                    type=int,
+                    choices=CONFIDENCE_SCORE_RANGE)
+
+tuning.add_argument('--force-decode-threshold',
+                    help="extremely high (AKA 'above this number') confidence scores from chardet.detect() " +
+                         "as to the likelihood some bytes were written with a particular encoding will cause " +
+                         "the yaralyzer to attempt decoding those bytes in that encoding even if it is not a " +
+                         "configured encoding",
+                    default=EncodingDetector.force_decode_threshold,
+                    metavar='PCT_CONFIDENCE',
+                    type=int,
+                    choices=CONFIDENCE_SCORE_RANGE)
+
+tuning.add_argument('--max-match-length',
+                    help="max bytes YARA will return for a match",
+                    default=YaralyzerConfig.DEFAULT_MAX_MATCH_LENGTH,
+                    metavar='N',
+                    type=int)
+
+tuning.add_argument('--yara-stack-size',
+                    help="YARA matching engine internal stack size",
+                    default=YaralyzerConfig.DEFAULT_YARA_STACK_SIZE,
+                    metavar='N',
+                    type=int)
+
+
+# Export options
+export = parser.add_argument_group(
+    'FILE EXPORT',
+    "Multiselect. Choosing nothing is choosing nothing. Sends what you see on the screen to various file " +
+        "formats in parallel. Writes files to the current directory if --output-dir is not provided. " +
+        "Filenames are expansions of the scanned filename though you can use --file-prefix to make your " +
+        "filenames more unique and beautiful to their beholder.")
+
+export.add_argument('-svg', '--export-svg',
+                    action='store_const',
+                    const='svg',
+                    help='export analysis to SVG images')
+
+export.add_argument('-txt', '--export-txt',
+                    action='store_const',
+                    const='txt',
+                    help='export analysis to ANSI colored text files')
+
+export.add_argument('-html', '--export-html',
+                    action='store_const',
+                    const='html',
+                    help='export analysis to styled html files')
+
+export.add_argument('-json', '--export-json',
+                    action='store_const',
+                    const='json',
+                    help='export analysis to JSON files')
+
+export.add_argument('-out', '--output-dir',
+                    metavar='OUTPUT_DIR',
+                    help='write files to OUTPUT_DIR instead of current dir, does nothing if not exporting a file')
+
+export.add_argument('-pfx', '--file-prefix',
+                    metavar='PREFIX',
+                    help='optional string to use as the prefix for exported files of any kind')
+
+export.add_argument('-sfx', '--file-suffix',
+                    metavar='SUFFIX',
+                    help='optional string to use as the suffix for exported files of any kind')
+
+
+# Debugging
+debug = parser.add_argument_group(
+    'DEBUG',
+    'Debugging/interactive options.')
+
+debug.add_argument('-I', '--interact', action='store_true',
+                    help='drop into interactive python REPL when parsing is complete')
+
+debug.add_argument('-D', '--debug', action='store_true',
+                    help='show verbose debug log output')
+
+debug.add_argument('-L', '--log-level',
+                    help='set the log level',
+                    choices=['DEBUG', 'INFO', 'WARN', 'ERROR'])
+
+YaralyzerConfig.set_argument_parser(parser)
+
+
+def parse_arguments(args: Optional[Namespace] = None):
+    """
+    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')}")
+        sys.exit()
+
+    # Hacky way to adjust arg parsing based on whether yaralyzer is used as a library vs. CLI tool
+    used_as_library = args is not None
+    args = args or parser.parse_args()
+    log_argparse_result(args, 'RAW')
+    args.standalone_mode = not used_as_library
+    args.invoked_at_str = timestamp_for_filename()
+
+    if args.debug:
+        log.setLevel(logging.DEBUG)
+
+        if args.log_level and args.log_level != 'DEBUG':
+            log.warning("Ignoring --log-level option as debug mode means log level is DEBUG")
+    elif args.log_level:
+        log.setLevel(args.log_level)
+
+    yara_rules_args = [arg for arg in YARA_RULES_ARGS if vars(args)[arg] is not None]
+
+    if used_as_library:
+        pass
+    elif len(yara_rules_args) > 1:
+        raise ArgumentError(None, "Cannot mix rules files, rules dirs, and regex patterns (for now).")
+    elif len(yara_rules_args) == 0:
+        raise ArgumentError(None, "You must provide either a YARA rules file or a regex pattern")
+    else:
+        log_invocation()
+
+    if args.maximize_width:
+        rich_console.console.width = max(rich_console.console_width_possibilities())
+
+    if args.patterns_label and not YARA_PATTERN_LABEL_REGEX.match(args.patterns_label):
+        raise ArgumentError(None, 'Pattern can only include alphanumeric chars and underscore')
+
+    # chardet.detect() action thresholds
+    if args.force_decode_threshold:
+        EncodingDetector.force_decode_threshold = args.force_decode_threshold
+
+    if args.force_display_threshold:
+        EncodingDetector.force_display_threshold = args.force_display_threshold
+
+    # File export options
+    if args.export_html or args.export_json or args.export_svg or args.export_txt:
+        args.output_dir = args.output_dir or getcwd()
+    elif args.output_dir:
+        log.warning('--output-dir provided but no export option was chosen')
+
+    YaralyzerConfig.set_args(args)
+
+    if not used_as_library:
+        log_argparse_result(args, 'parsed')
+        log_current_config()
+        log_argparse_result(YaralyzerConfig.args, 'with_env_vars')
+
+    return args
+
+
+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}"
+    args.output_basename += ('_' + args.file_suffix) if args.file_suffix else ''
+    return path.join(args.output_dir, args.output_basename + f"__at_{args.invoked_at_str}")

yaralyzer/util/logging.py

@@ -0,0 +1,135 @@
+"""
+Handle logging for `yaralyzer`.
+
+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
+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
+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.
+
+* [logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig)
+
+* [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
+from os import path
+from typing import Union
+
+from rich.logging import RichHandler
+
+from yaralyzer.config import YaralyzerConfig
+
+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.
+
+    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 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')
+        log_file_handler = logging.FileHandler(log_file_path)
+        log_file_handler.setFormatter(log_formatter)
+        logger.addHandler(log_file_handler)
+        # rich_stream_handler is for printing warnings
+        rich_stream_handler = RichHandler(rich_tracebacks=True)
+        rich_stream_handler.setLevel('WARN')
+        logger.addHandler(rich_stream_handler)
+    else:
+        logger.addHandler(RichHandler(rich_tracebacks=True))
+
+    logger.setLevel(YaralyzerConfig.LOG_LEVEL)
+    return logger
+
+
+# See comment at top. 'log' is the standard application log, 'invocation_log' is a history of yaralyzer runs
+log = configure_logger('run')
+invocation_log = configure_logger('invocation')
+
+# If we're logging to files make sure invocation_log has the right level
+if YaralyzerConfig.LOG_DIR:
+    invocation_log.setLevel('INFO')
+
+
+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."""
+    msg = f"{YaralyzerConfig.__name__} current attributes:\n"
+    config_dict = {k: v for k, v in vars(YaralyzerConfig).items() if not k.startswith('__')}
+
+    for k in sorted(config_dict.keys()):
+        msg += f"   {k: >35}  {config_dict[k]}\n"
+
+    log.info(msg)
+
+
+def log_invocation() -> None:
+    """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`."""
+    args_dict = vars(args)
+    log_msg = f'{label} argparse results:\n' + ARGPARSE_LOG_FORMAT.format('OPTION', 'TYPE', 'VALUE')
+
+    for arg_var in sorted(args_dict.keys()):
+        arg_val = args_dict[arg_var]
+        row = ARGPARSE_LOG_FORMAT.format(arg_var, type(arg_val).__name__, str(arg_val))
+        log_msg += row
+
+    log_msg += "\n"
+    invocation_log.info(log_msg)
+    log.info(log_msg)
+
+
+def set_log_level(level: Union[str, int]) -> None:
+    """Set the log level at any time."""
+    for handler in log.handlers + [log]:
+        handler.setLevel(level)
+
+
+# Suppress annoying chardet library logs
+for submodule in ['universaldetector', 'charsetprober', 'codingstatemachine']:
+    logging.getLogger(f"chardet.{submodule}").setLevel(logging.WARNING)

yaralyzer/yara/error.py

@@ -0,0 +1,90 @@
+import re
+
+import yara
+
+INTERNAL_ERROR_REGEX = re.compile(r"internal error: (\d+)$")
+YARA_ERRORS_REPO_PATH = 'master/libyara/include/yara/error.h'
+YARA_ERRORS_RAW_URL = f"https://raw.githubusercontent.com/VirusTotal/yara/refs/heads/{YARA_ERRORS_REPO_PATH}"
+YARA_ERRORS_URL = f"https://github.com/VirusTotal/yara/blob/{YARA_ERRORS_REPO_PATH}"
+
+# Extracted from YARA_ERRORS_RAW_URL
+YARA_ERROR_CODES = {
+    0: 'SUCCESS',
+    1: 'INSUFICIENT_MEMORY',
+    1: 'INSUFFICIENT_MEMORY',
+    2: 'COULD_NOT_ATTACH_TO_PROCESS',
+    3: 'COULD_NOT_OPEN_FILE',
+    4: 'COULD_NOT_MAP_FILE',
+    6: 'INVALID_FILE',
+    7: 'CORRUPT_FILE',
+    8: 'UNSUPPORTED_FILE_VERSION',
+    9: 'INVALID_REGULAR_EXPRESSION',
+    10: 'INVALID_HEX_STRING',
+    11: 'SYNTAX_ERROR',
+    12: 'LOOP_NESTING_LIMIT_EXCEEDED',
+    13: 'DUPLICATED_LOOP_IDENTIFIER',
+    14: 'DUPLICATED_IDENTIFIER',
+    15: 'DUPLICATED_TAG_IDENTIFIER',
+    16: 'DUPLICATED_META_IDENTIFIER',
+    17: 'DUPLICATED_STRING_IDENTIFIER',
+    18: 'UNREFERENCED_STRING',
+    19: 'UNDEFINED_STRING',
+    20: 'UNDEFINED_IDENTIFIER',
+    21: 'MISPLACED_ANONYMOUS_STRING',
+    22: 'INCLUDES_CIRCULAR_REFERENCE',
+    23: 'INCLUDE_DEPTH_EXCEEDED',
+    24: 'WRONG_TYPE',
+    25: 'EXEC_STACK_OVERFLOW',
+    26: 'SCAN_TIMEOUT',
+    27: 'TOO_MANY_SCAN_THREADS',
+    28: 'CALLBACK_ERROR',
+    29: 'INVALID_ARGUMENT',
+    30: 'TOO_MANY_MATCHES',
+    31: 'INTERNAL_FATAL_ERROR',
+    32: 'NESTED_FOR_OF_LOOP',
+    33: 'INVALID_FIELD_NAME',
+    34: 'UNKNOWN_MODULE',
+    35: 'NOT_A_STRUCTURE',
+    36: 'NOT_INDEXABLE',
+    37: 'NOT_A_FUNCTION',
+    38: 'INVALID_FORMAT',
+    39: 'TOO_MANY_ARGUMENTS',
+    40: 'WRONG_ARGUMENTS',
+    41: 'WRONG_RETURN_TYPE',
+    42: 'DUPLICATED_STRUCTURE_MEMBER',
+    43: 'EMPTY_STRING',
+    44: 'DIVISION_BY_ZERO',
+    45: 'REGULAR_EXPRESSION_TOO_LARGE',
+    46: 'TOO_MANY_RE_FIBERS',
+    47: 'COULD_NOT_READ_PROCESS_MEMORY',
+    48: 'INVALID_EXTERNAL_VARIABLE_TYPE',
+    49: 'REGULAR_EXPRESSION_TOO_COMPLEX',
+    50: 'INVALID_MODULE_NAME',
+    51: 'TOO_MANY_STRINGS',
+    52: 'INTEGER_OVERFLOW',
+    53: 'CALLBACK_REQUIRED',
+    54: 'INVALID_OPERAND',
+    55: 'COULD_NOT_READ_FILE',
+    56: 'DUPLICATED_EXTERNAL_VARIABLE',
+    57: 'INVALID_MODULE_DATA',
+    58: 'WRITING_FILE',
+    59: 'INVALID_MODIFIER',
+    60: 'DUPLICATED_MODIFIER',
+    61: 'BLOCK_NOT_READY',
+    62: 'INVALID_PERCENTAGE',
+    63: 'IDENTIFIER_MATCHES_WILDCARD',
+    64: 'INVALID_VALUE',
+    65: 'TOO_SLOW_SCANNING',
+    66: 'UNKNOWN_ESCAPE_SEQUENCE',
+}
+
+
+def yara_error_msg(exception: yara.Error) -> str:
+    internal_error_match = INTERNAL_ERROR_REGEX.search(str(exception))
+
+    if internal_error_match:
+        error_code = int(internal_error_match.group(1))
+        error_msg = YARA_ERROR_CODES[error_code]
+        return f"Internal YARA error! (code: {error_code}, type: {error_msg})"
+    else:
+        return f"YARA error: {exception}"

yaralyzer/yara/yara_match.py

@@ -0,0 +1,160 @@
+"""
+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
+from typing import Any, Dict
+
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.text import Text
+from yara import StringMatch
+
+from yaralyzer.helpers.bytes_helper import clean_byte_string
+from yaralyzer.helpers.rich_text_helper import CENTER
+from yaralyzer.helpers.string_helper import INDENT_SPACES
+from yaralyzer.output.rich_console import console_width, theme_colors_with_prefix
+from yaralyzer.util.logging import log
+
+MATCH_PADDING = (0, 0, 0, 1)
+
+DATE_REGEX = re.compile('\\d{4}-\\d{2}-\\d{2}')
+DIGITS_REGEX = re.compile("^\\d+$")
+HEX_REGEX = re.compile('^[0-9A-Fa-f]+$')
+MATCHER_VAR_REGEX = re.compile('\\$[a-z_]+')
+URL_REGEX = re.compile('^https?:')
+
+YARA_STRING_STYLES: Dict[re.Pattern, str] = {
+    URL_REGEX: 'yara.url',
+    DIGITS_REGEX: 'yara.number',
+    HEX_REGEX: 'yara.hex',
+    DATE_REGEX: 'yara.date',
+    MATCHER_VAR_REGEX: 'yara.match_var'
+}
+
+RAW_YARA_THEME_COLORS = [color[len('yara') + 1:] for color in theme_colors_with_prefix('yara')]
+RAW_YARA_THEME_TXT = Text('\nColor Code: ') + Text(' ').join(RAW_YARA_THEME_COLORS)
+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 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
+        yield Padding(Panel(_rich_yara_match(self.match)), MATCH_PADDING)
+
+
+def _rich_yara_match(element: Any, depth: int = 0) -> Text:
+    """
+    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)
+
+    if isinstance(element, str):
+        txt = _yara_string(element)
+    elif isinstance(element, bytes):
+        txt = Text(clean_byte_string(element), style='bytes')
+    elif isinstance(element, Number):
+        txt = Text(str(element), style='bright_cyan')
+    elif isinstance(element, bool):
+        txt = Text(str(element), style='red' if not element else 'green')
+    elif isinstance(element, (list, tuple)):
+        if len(element) == 0:
+            txt = Text('[]', style='white')
+        else:
+            if isinstance(element[0], StringMatch):
+                # In yara-python 4.3.0 the StringMatch type was introduced so we just make it look like
+                # the old list of tuples format (see: https://github.com/VirusTotal/yara-python/releases/tag/v4.3.0)
+                match_tuples = [
+                    (match.identifier, match_instance.offset, match_instance.matched_data)
+                    for match in element
+                    for match_instance in match.instances
+                ]
+
+                return _rich_yara_match(match_tuples, depth)
+
+            total_length = sum([len(str(e)) for e in element]) + ((len(element) - 1) * 2) + len(indent) + 2
+            elements_txt = [_rich_yara_match(e, depth + 1) for e in element]
+            list_txt = Text('[', style='white')
+
+            if total_length > console_width() or len(element) > 3:
+                join_txt = Text(f"\n{indent}")
+                list_txt.append(join_txt).append(Text(f",{join_txt}").join(elements_txt))
+                list_txt += Text(f'\n{end_indent}]', style='white')
+            else:
+                list_txt += Text(', ').join(elements_txt) + Text(']')
+
+            return list_txt
+    elif isinstance(element, dict):
+        element = {k: v for k, v in element.items() if k not in ['matches', 'rule']}
+
+        if len(element) == 0:
+            return Text('{}')
+
+        txt = Text('{\n', style='white')
+
+        for i, k in enumerate(element.keys()):
+            v = element[k]
+            txt += indent + Text(f"{k}: ", style='yara.key') + _rich_yara_match(v, depth + 1)
+
+            if (i + 1) < len(element.keys()):
+                txt.append(",\n")
+            else:
+                txt.append("\n")
+
+        txt += end_indent + Text('}', style='white')
+    else:
+        log.warning(f"Unknown yara return of type {type(element)}: {element}")
+        txt = indent + Text(str(element))
+
+    return txt
+
+
+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])
+
+    return Text(_string, style='yara.string')