yaralyzer 1.0.11__py3-none-any.whl

yaralyzer/__init__.py

@@ -0,0 +1,76 @@
+import code
+import yara as python_yara
+from os import environ, getcwd, path
+
+from dotenv import load_dotenv
+from rich.text import Text
+
+# load_dotenv() should be called as soon as possible (before parsing local classes) but not for pytest
+if not environ.get('INVOKED_BY_PYTEST', False):
+    for dotenv_file in [path.join(dir, '.yaralyzer') for dir in [getcwd(), path.expanduser('~')]]:
+        if path.exists(dotenv_file):
+            load_dotenv(dotenv_path=dotenv_file)
+            break
+
+from yaralyzer.helpers.rich_text_helper import print_fatal_error_and_exit
+from yaralyzer.output.file_export import export_json, invoke_rich_export
+from yaralyzer.output.rich_console import console
+from yaralyzer.util.argument_parser import get_export_basepath, parse_arguments
+from yaralyzer.yara.error import yara_error_msg
+from yaralyzer.yara.yara_rule_builder import HEX, REGEX
+from yaralyzer.yaralyzer import Yaralyzer
+
+PDFALYZER_MSG = "\nIf you are analyzing a PDF you may be interested in The Pdfalyzer, birthplace of The Yaralyzer:"
+PDFALYZER_MSG_TXT = Text(PDFALYZER_MSG, style='bright_white bold')
+PDFALYZER_MSG_TXT.append('\n -> ', style='bright_white')
+PDFALYZER_MSG_TXT.append('https://github.com/michelcrypt4d4mus/pdfalyzer\n', style='bright_cyan underline')
+
+
+def yaralyze():
+    """
+    Entry point for yaralyzer when invoked as a script.
+
+    Args are parsed from the command line and environment variables. See `yaralyze --help` for details.
+    """
+    args = parse_arguments()
+    output_basepath = None
+
+    if args.yara_rules_files:
+        yaralyzer = Yaralyzer.for_rules_files(args.yara_rules_files, args.file_to_scan_path)
+    elif args.yara_rules_dirs:
+        yaralyzer = Yaralyzer.for_rules_dirs(args.yara_rules_dirs, args.file_to_scan_path)
+    elif args.regex_patterns or args.hex_patterns:
+        yaralyzer = Yaralyzer.for_patterns(
+            args.regex_patterns or args.hex_patterns,
+            HEX if args.hex_patterns else REGEX,
+            args.file_to_scan_path,
+            pattern_label=args.patterns_label,
+            regex_modifier=args.regex_modifier)
+    else:
+        raise RuntimeError("No pattern or YARA file to scan against.")
+
+    if args.output_dir:
+        output_basepath = get_export_basepath(args, yaralyzer)
+        console.print(f"Will render yaralyzer data to '{output_basepath}'...", style='yellow')
+        console.record = True
+
+    try:
+        yaralyzer.yaralyze()
+    except python_yara.Error as e:
+        print_fatal_error_and_exit(yara_error_msg(e))
+
+    if args.export_txt:
+        invoke_rich_export(console.save_text, output_basepath)
+    if args.export_html:
+        invoke_rich_export(console.save_html, output_basepath)
+    if args.export_svg:
+        invoke_rich_export(console.save_svg, output_basepath)
+    if args.export_json:
+        export_json(yaralyzer, output_basepath)
+
+    if args.file_to_scan_path.endswith('.pdf'):
+        console.print(PDFALYZER_MSG_TXT)
+
+    # Drop into interactive shell if requested
+    if args.interact:
+        code.interact(local=locals())

yaralyzer/bytes_match.py

@@ -0,0 +1,276 @@
+"""
+`BytesMatch` class for tracking regex and YARA matches against binary data.
+"""
+import re
+from dataclasses import dataclass, field
+from typing import Iterator, Optional
+
+from rich.table import Table
+from rich.text import Text
+from yara import StringMatch, StringMatchInstance
+
+from yaralyzer.config import YaralyzerConfig
+from yaralyzer.helpers.rich_text_helper import prefix_with_style
+from yaralyzer.output.file_hashes_table import bytes_hashes_table
+from yaralyzer.output.rich_console import ALERT_STYLE, GREY_ADDRESS
+
+
+@dataclass
+class BytesMatch:
+    """
+    Simple class to keep track of regex matches against binary data.
+
+    Basically a Regex `re.match` object with some (not many) extra bells and whistles, most notably
+    the `surrounding_bytes` property.
+
+    Args:
+        matched_against (bytes): The full byte sequence that was searched.
+        start_idx (int): Start index of the match in the byte sequence.
+        match_length (int): Length of the match in bytes.
+        label (str): Label for the match (e.g., regex or YARA rule name).
+        ordinal (int): This was the Nth match for this pattern (used for labeling only).
+        match (Optional[re.Match]): Regex `match` object, if available.
+        highlight_style (str): Style to use for highlighting the match.
+
+    Attributes:
+        end_idx (int): End index of the match in the byte sequence.
+        bytes: (bytes): The bytes that matched the regex.
+    """
+    matched_against: bytes
+    start_idx: int
+    match_length: int
+    label: str
+    ordinal: int
+    match: re.Match | None = None   # It's rough to get the regex from yara :(
+    highlight_style: str = YaralyzerConfig.HIGHLIGHT_STYLE
+    end_idx: int = field(init=False)
+    match_grooups: tuple = field(init=False)
+    highlight_start_idx: int = field(init=False)
+    highlight_end_idx: int = field(init=False)
+    surrounding_start_idx: int = field(init=False)
+    surrounding_end_idx: int = field(init=False)
+    surrounding_bytes: bytes = field(init=False)
+
+    def __post_init__(self):
+        self.end_idx: int = self.start_idx + self.match_length
+        self.bytes = self.matched_against[self.start_idx:self.end_idx]  # TODO: Maybe should be called "matched_bytes"
+        self.match_groups: Optional[tuple] = self.match.groups() if self.match else None
+        num_after = YaralyzerConfig.args.surrounding_bytes
+        num_before = YaralyzerConfig.args.surrounding_bytes
+        # Adjust the highlighting start point in case this match is very early or late in the stream
+        self.surrounding_start_idx: int = max(self.start_idx - num_before, 0)
+        self.surrounding_end_idx: int = min(self.end_idx + num_after, len(self.matched_against))
+        self.surrounding_bytes: bytes = self.matched_against[self.surrounding_start_idx:self.surrounding_end_idx]
+        self.highlight_start_idx = self.start_idx - self.surrounding_start_idx
+        self.highlight_end_idx = self.highlight_start_idx + self.match_length
+
+    @classmethod
+    def from_regex_match(
+        cls,
+        matched_against: bytes,
+        match: re.Match,
+        ordinal: int,
+        highlight_style: str = YaralyzerConfig.HIGHLIGHT_STYLE
+    ) -> 'BytesMatch':
+        """
+        Alternate constructor to build a `BytesMatch` from a regex match object.
+
+        Args:
+            matched_against (bytes): The bytes searched.
+            match (re.Match): The regex `match` object.
+            ordinal (int): This was the Nth match for this pattern (used for labeling only).
+            highlight_style (str): Style for highlighting.
+
+        Returns:
+            BytesMatch: The constructed `BytesMatch` instance.
+        """
+        return cls(matched_against, match.start(), len(match[0]), match.re.pattern, ordinal, match, highlight_style)
+
+    @classmethod
+    def from_yara_str(
+        cls,
+        matched_against: bytes,
+        rule_name: str,
+        yara_str_match: StringMatch,
+        yara_str_match_instance: StringMatchInstance,
+        ordinal: int,
+        highlight_style: str = YaralyzerConfig.HIGHLIGHT_STYLE
+    ) -> 'BytesMatch':
+        """
+        Alternate constructor to build a `BytesMatch` from a YARA string match instance.
+
+        Args:
+            matched_against (bytes): The bytes searched.
+            rule_name (str): Name of the YARA rule.
+            yara_str_match (StringMatch): YARA string match object.
+            yara_str_match_instance (StringMatchInstance): Instance of the string match.
+            ordinal (int): The Nth match for this pattern.
+            highlight_style (str): Style for highlighting.
+
+        Returns:
+            BytesMatch: The constructed BytesMatch instance.
+        """
+        pattern_label = yara_str_match.identifier
+
+        # Don't duplicate the labeling if rule_name and yara_str are the same
+        if pattern_label == '$' + rule_name:
+            label = pattern_label
+        else:
+            label = rule_name + ': ' + pattern_label
+
+        return cls(
+            matched_against=matched_against,
+            start_idx=yara_str_match_instance.offset,
+            match_length=yara_str_match_instance.matched_length,
+            label=label,
+            ordinal=ordinal,
+            highlight_style=highlight_style
+        )
+
+    @classmethod
+    def from_yara_match(
+        cls,
+        matched_against: bytes,
+        yara_match: dict,
+        highlight_style: str = YaralyzerConfig.HIGHLIGHT_STYLE
+    ) -> Iterator['BytesMatch']:
+        """
+        Yield a `BytesMatch` for each string returned as part of a YARA match result dict.
+
+        Args:
+            matched_against (bytes): The bytes searched.
+            yara_match (dict): YARA match result dictionary.
+            highlight_style (str): Style for highlighting.
+
+        Yields:
+            BytesMatch: For each string match in the YARA result.
+        """
+        i = 0  # For numbered labeling
+
+        # yara-python's internals changed with 4.3.0: https://github.com/VirusTotal/yara-python/releases/tag/v4.3.0
+        for yara_str_match in yara_match['strings']:
+            for yara_str_match_instance in yara_str_match.instances:
+                i += 1
+
+                yield cls.from_yara_str(
+                    matched_against,
+                    yara_match['rule'],
+                    yara_str_match,
+                    yara_str_match_instance,
+                    i,
+                    highlight_style
+                )
+
+    def style_at_position(self, idx) -> str:
+        """
+        Get the style for the byte at position `idx` within the matched bytes.
+
+        Args:
+            idx (int): Index within the surrounding bytes.
+
+        Returns:
+            str: The style to use for this byte (highlight or greyed out).
+        """
+        if idx < self.highlight_start_idx or idx >= self.highlight_end_idx:
+            return GREY_ADDRESS
+        else:
+            return self.highlight_style
+
+    def location(self) -> Text:
+        """
+        Get a styled `Text` object describing the start and end index of the match.
+
+        Returns:
+            Text: Rich Text object like '(start idx: 348190, end idx: 348228)'.
+        """
+        location_txt = prefix_with_style(
+            f"(start idx: ",
+            style='off_white',
+            root_style='decode.subheading'
+        )
+
+        location_txt.append(str(self.start_idx), style='number')
+        location_txt.append(', end idx: ', style='off_white')
+        location_txt.append(str(self.end_idx), style='number')
+        location_txt.append(')', style='off_white')
+        return location_txt
+
+    def is_decodable(self) -> bool:
+        """
+        Determine if the matched bytes should be decoded.
+
+        Whether the bytes are decodable depends on whether `SUPPRESS_DECODES_TABLE` is set
+        and whether the match length is between `MIN`/`MAX_DECODE_LENGTH`.
+
+        Returns:
+            bool: `True` if decodable, `False` otherwise.
+        """
+        return self.match_length >= YaralyzerConfig.args.min_decode_length \
+           and self.match_length <= YaralyzerConfig.args.max_decode_length \
+           and not YaralyzerConfig.args.suppress_decodes_table
+
+    def bytes_hashes_table(self) -> Table:
+        """
+        Build a table of MD5/SHA hashes for the matched bytes.
+
+        Returns:
+            Table: Rich `Table` object with hashes.
+        """
+        return bytes_hashes_table(
+            self.bytes,
+            self.location().plain,
+            'center'
+        )
+
+    def suppression_notice(self) -> Text:
+        """
+        Generate a message for when the match is too short or too long to decode.
+
+        Returns:
+            Text: Rich `Text` object with the suppression notice.
+        """
+        txt = self.__rich__()
+
+        if self.match_length < YaralyzerConfig.args.min_decode_length:
+            txt = Text('Too little to actually attempt decode at ', style='grey') + txt
+        else:
+            txt.append(" too long to decode ")
+            txt.append(f"(--max-decode-length is {YaralyzerConfig.args.max_decode_length} bytes)", style='grey')
+
+        return txt
+
+    def to_json(self) -> dict:
+        """
+        Convert this `BytesMatch` to a JSON-serializable dictionary.
+
+        Returns:
+            dict: Dictionary representation of the match, suitable for JSON serialization.
+        """
+        json_dict = {
+            'label': self.label,
+            'match_length': self.match_length,
+            'matched_bytes': self.bytes.hex(),
+            'ordinal': self.ordinal,
+            'start_idx': self.start_idx,
+            'end_idx': self.end_idx,
+            'surrounding_bytes': self.surrounding_bytes.hex(),
+            'surrounding_start_idx': self.surrounding_start_idx,
+            'surrounding_end_idx': self.surrounding_end_idx,
+        }
+
+        if self.match:
+            json_dict['pattern'] = self.match.re.pattern
+
+        return json_dict
+
+    def __rich__(self) -> Text:
+        """Get a rich `Text` representation of the match for display."""
+        headline = prefix_with_style(str(self.match_length), style='number', root_style='decode.subheading')
+        headline.append(f" bytes matching ")
+        headline.append(f"{self.label} ", style=ALERT_STYLE if self.highlight_style == ALERT_STYLE else 'regex')
+        headline.append('at ')
+        return headline + self.location()
+
+    def __str__(self):
+        """Plain text (no rich colors) representation of the match for display."""
+        return self.__rich__().plain

yaralyzer/config.py

@@ -0,0 +1,126 @@
+"""
+Configuration management for Yaralyzer.
+"""
+import logging
+from argparse import ArgumentParser, Namespace
+from os import environ
+from typing import Any, List
+
+from rich.console import Console
+
+YARALYZE = 'yaralyze'
+YARALYZER = f"{YARALYZE}r".upper()
+PYTEST_FLAG = 'INVOKED_BY_PYTEST'
+
+KILOBYTE = 1024
+MEGABYTE = 1024 * KILOBYTE
+
+
+def config_var_name(env_var: str) -> str:
+    """
+    Get the name of `env_var` and strip off `YARALYZER_` prefix.
+
+    Example:
+        ```
+        SURROUNDING_BYTES_ENV_VAR = 'YARALYZER_SURROUNDING_BYTES'
+        config_var_name(SURROUNDING_BYTES_ENV_VAR) => 'SURROUNDING_BYTES'
+        ```
+    """
+    env_var = env_var.removeprefix("YARALYZER_")
+    return f'{env_var=}'.partition('=')[0]
+
+
+def is_env_var_set_and_not_false(var_name: str) -> bool:
+    """Return `True` if `var_name` is not empty and set to anything other than "false" (capitalization agnostic)."""
+    if var_name in environ:
+        var_value = environ[var_name]
+        return var_value is not None and len(var_value) > 0 and var_value.lower() != 'false'
+    else:
+        return False
+
+
+def is_invoked_by_pytest() -> bool:
+    """Return `True` if invoked in a `pytest` context."""
+    return is_env_var_set_and_not_false(PYTEST_FLAG)
+
+
+class YaralyzerConfig:
+    """Handles parsing of command line args and environment variables for Yaralyzer."""
+
+    # Passed through to yara.set_config()
+    DEFAULT_MAX_MATCH_LENGTH = 100 * KILOBYTE
+    DEFAULT_YARA_STACK_SIZE = 2 * 65536
+
+    # Skip decoding binary matches under/over these lengths
+    DEFAULT_MIN_DECODE_LENGTH = 1
+    DEFAULT_MAX_DECODE_LENGTH = 256
+
+    # chardet.detect() related
+    DEFAULT_MIN_CHARDET_TABLE_CONFIDENCE = 2
+    DEFAULT_MIN_CHARDET_BYTES = 9
+
+    # Number of bytes to show before/after byte previews and decodes. Configured by command line or env var
+    DEFAULT_SURROUNDING_BYTES = 64
+
+    LOG_DIR_ENV_VAR = 'YARALYZER_LOG_DIR'
+    LOG_DIR = environ.get(LOG_DIR_ENV_VAR)
+    LOG_LEVEL_ENV_VAR = f"{YARALYZER}_LOG_LEVEL"
+    LOG_LEVEL = logging.getLevelName(environ.get(LOG_LEVEL_ENV_VAR, 'WARN'))
+
+    if LOG_DIR and not is_invoked_by_pytest():
+        Console(color_system='256').print(f"Writing logs to '{LOG_DIR}' instead of stderr/stdout...", style='dim')
+
+    HIGHLIGHT_STYLE = 'orange1'
+
+    ONLY_CLI_ARGS = [
+        'debug',
+        'help',
+        'hex_patterns',
+        'interact',
+        'patterns_label',
+        'regex_patterns',
+        'regex_modifier',
+        'version'
+    ]
+
+    @classmethod
+    def set_argument_parser(cls, parser: ArgumentParser) -> None:
+        """Sets the `_argument_parser` instance variable that will be used to parse command line args."""
+        cls._argument_parser: ArgumentParser = parser
+        cls._argparse_keys: List[str] = sorted([action.dest for action in parser._actions])
+
+    @classmethod
+    def set_args(cls, args: Namespace) -> None:
+        """Set the `args` class instance variable and update args with any environment variable overrides."""
+        cls.args = args
+
+        for option in cls._argparse_keys:
+            if option.startswith('export') or option in cls.ONLY_CLI_ARGS:
+                continue
+
+            arg_value = vars(args)[option]
+            env_var = f"{YARALYZER}_{option.upper()}"
+            env_value = environ.get(env_var)
+            default_value = cls.get_default_arg(option)
+            # print(f"option: {option}, arg_value: {arg_value}, env_var: {env_var}, env_value: {env_value}, default: {default_value}")  # noqa: E501
+
+            # TODO: as is you can't override env vars with CLI args
+            if isinstance(arg_value, bool):
+                setattr(args, option, arg_value or is_env_var_set_and_not_false(env_var))
+            elif isinstance(arg_value, (int, float)):
+                # Check against defaults to avoid overriding env var configured options
+                if arg_value == default_value and env_value is not None:
+                    setattr(args, option, int(env_value) or arg_value)  # TODO: float args not handled
+            else:
+                setattr(args, option, arg_value or env_value)
+
+    @classmethod
+    def set_default_args(cls):
+        """Set `self.args` to their defaults as if parsed from the command line."""
+        cls.set_args(cls._argument_parser.parse_args(['dummy']))
+
+    @classmethod
+    def get_default_arg(cls, arg: str) -> Any:
+        """Return the default value for `arg` as defined by a `DEFAULT_` style class variable."""
+        default_var = f"DEFAULT_{arg.upper()}"
+        return vars(cls).get(default_var)

yaralyzer/decoding/bytes_decoder.py

@@ -0,0 +1,207 @@
+"""
+`BytesDecoder` class for attempting to decode bytes with various encodings.
+"""
+from collections import defaultdict
+from copy import deepcopy
+from operator import attrgetter
+from typing import List, Optional
+
+from rich.align import Align
+from rich.console import Console, ConsoleOptions, NewLine, RenderResult
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from yaralyzer.bytes_match import BytesMatch  # Used to cause circular import issues
+from yaralyzer.config import YaralyzerConfig
+from yaralyzer.decoding.decoding_attempt import DecodingAttempt
+from yaralyzer.encoding_detection.character_encodings import ENCODING, ENCODINGS_TO_ATTEMPT
+from yaralyzer.encoding_detection.encoding_assessment import EncodingAssessment
+from yaralyzer.encoding_detection.encoding_detector import EncodingDetector
+from yaralyzer.helpers.dict_helper import get_dict_key_by_value
+from yaralyzer.helpers.rich_text_helper import CENTER, DECODING_ERRORS_MSG, NO_DECODING_ERRORS_MSG
+from yaralyzer.output.decoding_attempts_table import new_decoding_attempts_table
+from yaralyzer.output.decoding_table_row import DecodingTableRow
+from yaralyzer.util.logging import log
+
+# A 2-tuple that can be indexed by booleans of messages used in the table to show true vs. false
+WAS_DECODABLE_YES_NO = [NO_DECODING_ERRORS_MSG, DECODING_ERRORS_MSG]
+
+# Multiply chardet scores by 100 (again) to make sorting the table easy
+SCORE_SCALER = 100.0
+
+
+class BytesDecoder:
+    """
+    Handles decoding a chunk of bytes into strings using various possible encodings, ranking and displaying results.
+
+    This class leverages the `chardet` library and custom logic to try multiple encodings, track decoding outcomes,
+    and present the results in a rich, user-friendly format. It is used to analyze and display the possible
+    interpretations of a byte sequence, especially in the context of YARA matches or binary analysis.
+
+    Attributes:
+        bytes_match (BytesMatch): The `BytesMatch` instance being decoded.
+        bytes (bytes): The bytes (including surrounding context) to decode.
+        label (str): Label for this decoding attempt.
+        was_match_decodable (dict): Tracks successful decodes per encoding.
+        was_match_force_decoded (dict): Tracks forced decodes per encoding.
+        was_match_undecodable (dict): Tracks failed decodes per encoding.
+        decoded_strings (dict): Maps encoding to decoded string.
+        undecoded_rows (list): Stores undecoded table rows.
+        decodings (list): List of DecodingAttempt objects for each encoding tried.
+        encoding_detector (EncodingDetector): Used to detect and assess possible encodings.
+    """
+
+    def __init__(self, bytes_match: 'BytesMatch', label: Optional[str] = None) -> None:
+        """
+        Initialize a `BytesDecoder` for attempting to decode a chunk of bytes using various encodings.
+
+        Args:
+            bytes_match (BytesMatch): The `BytesMatch` object containing the bytes to decode and match metadata.
+            label (Optional[str], optional): Optional label for this decoding attempt. Defaults to the match label.
+        """
+        self.bytes_match = bytes_match
+        self.bytes = bytes_match.surrounding_bytes
+        self.label = label or bytes_match.label
+
+        # Empty table/metrics/etc
+        self.was_match_decodable = _build_encodings_metric_dict()
+        self.was_match_force_decoded = _build_encodings_metric_dict()
+        self.was_match_undecodable = _build_encodings_metric_dict()
+        self.decoded_strings = {}  # dict[encoding: decoded string]
+        self.undecoded_rows = []
+        self.decodings = []
+
+        # Note we send both the match and surrounding bytes used when detecting the encoding
+        self.encoding_detector = EncodingDetector(self.bytes)
+
+    def __rich_console__(self, _console: Console, options: ConsoleOptions) -> RenderResult:
+        """Rich object generator (see Rich console docs)."""
+        yield NewLine(2)
+        yield Align(self._decode_attempt_subheading(), CENTER)
+
+        if not YaralyzerConfig.args.suppress_chardet:
+            yield NewLine()
+            yield Align(self.encoding_detector, CENTER)
+            yield NewLine()
+
+        # In standalone mode we always print the hex/raw bytes
+        if self.bytes_match.is_decodable():
+            yield self._build_decodings_table()
+        elif YaralyzerConfig.args.standalone_mode:
+            yield self._build_decodings_table(True)
+
+        yield NewLine()
+        yield Align(self.bytes_match.bytes_hashes_table(), CENTER, style='dim')
+
+    def _build_decodings_table(self, suppress_decodes: bool = False) -> Table:
+        """
+        First rows are the raw / hex views of the bytes, next rows are the attempted decodings.
+
+        Args:
+            suppress_decodes (bool, optional): If `True` don't add decoding attempts to the table. Defaults to `False`.
+        """
+        self.table = new_decoding_attempts_table(self.bytes_match)
+
+        # Add the encoding rows to the table if not suppressed
+        if not (YaralyzerConfig.args.suppress_decoding_attempts or suppress_decodes):
+            self.decodings = [DecodingAttempt(self.bytes_match, encoding) for encoding in ENCODINGS_TO_ATTEMPT]
+            # Attempt decodings we don't usually attempt if chardet is insistent enough
+            forced_decodes = self._undecoded_assessments(self.encoding_detector.force_decode_assessments)
+            self.decodings += [DecodingAttempt(self.bytes_match, a.encoding) for a in forced_decodes]
+
+            # If we still haven't decoded chardet's top choice, decode it
+            if len(self._forced_displays()) > 0 and not self._was_decoded(self._forced_displays()[0].encoding):
+                chardet_top_encoding = self._forced_displays()[0].encoding
+                log.info(f"Decoding {chardet_top_encoding} because it's chardet top choice...")
+                self.decodings.append(DecodingAttempt(self.bytes_match, chardet_top_encoding))
+
+            # Build the table rows from the decoding attempts
+            rows = [self._row_from_decoding_attempt(decoding) for decoding in self.decodings]
+
+            # Add assessments with no decode attempt
+            rows += [
+                DecodingTableRow.from_undecoded_assessment(a, a.confidence * SCORE_SCALER)
+                for a in self._forced_displays()
+            ]
+
+            self._track_decode_stats()
+
+            for row in sorted(rows, key=attrgetter('sort_score', 'encoding_label_plain'), reverse=True):
+                self.table.add_row(*row.to_row_list())
+
+        return self.table
+
+    # TODO: rename this to something that makes more sense, maybe assessments_over_display_threshold()?
+    def _forced_displays(self) -> List[EncodingAssessment]:
+        """Returns assessments over the display threshold that are not yet decoded."""
+        return self._undecoded_assessments(self.encoding_detector.force_display_assessments)
+
+    def _undecoded_assessments(self, assessments: List[EncodingAssessment]) -> List[EncodingAssessment]:
+        """Filter out the already decoded assessments from a set of assessments."""
+        return [a for a in assessments if not self._was_decoded(a.encoding)]
+
+    def _was_decoded(self, encoding: str) -> bool:
+        """Check whether a given encoding is in the table already."""
+        return any(row.encoding == encoding for row in self.decodings)
+
+    def _decode_attempt_subheading(self) -> Panel:
+        """Generate a rich.Panel for displaying decode attempts."""
+        headline = Text(f"Found ", style='decode.subheading') + self.bytes_match.__rich__()
+        return Panel(headline, style='decode.subheading', expand=False)
+
+    def _track_decode_stats(self) -> None:
+        """Track stats about successful vs. forced vs. failed decode attempts."""
+        for decoding in self.decodings:
+            if decoding.failed_to_decode:
+                self.was_match_undecodable[decoding.encoding] += 1
+                continue
+
+            self.was_match_decodable[decoding.encoding] += 1
+
+            if decoding.was_force_decoded:
+                self.was_match_force_decoded[decoding.encoding] += 1
+
+    def _row_from_decoding_attempt(self, decoding: DecodingAttempt) -> DecodingTableRow:
+        """Create a `DecodingAttemptTable` row from a `DecodingAttempt`."""
+        assessment = self.encoding_detector.get_encoding_assessment(decoding.encoding)
+
+        # If the decoding can have a start offset add an appropriate extension to the encoding label
+        if decoding.start_offset_label:
+            if assessment.language:
+                log.warning(f"{decoding.encoding} offset {decoding.start_offset} AND language '{assessment.language}'")
+            else:
+                assessment = deepcopy(assessment)
+                assessment.set_encoding_label(decoding.start_offset_label)
+
+        plain_decoded_string = decoding.decoded_string.plain
+        sort_score = assessment.confidence * SCORE_SCALER
+
+        # If the decoding result is a duplicate of a previous decoding, replace the decoded text
+        # with "same output as X" where X is the previous encoding that gave the same result.
+        if plain_decoded_string in self.decoded_strings.values():
+            encoding_with_same_output = get_dict_key_by_value(self.decoded_strings, plain_decoded_string)
+            display_text = Text('same output as ', style='color(66) dim italic')
+            display_text.append(encoding_with_same_output, style=ENCODING).append('...', style='white')
+        else:
+            self.decoded_strings[decoding.encoding_label] = plain_decoded_string
+            display_text = decoding.decoded_string
+
+        # Set failures negative, shave off a little for forced decodes
+        if decoding.failed_to_decode:
+            sort_score = (sort_score * -1) - 100
+        elif decoding.was_force_decoded:
+            sort_score -= 10
+
+        was_forced = WAS_DECODABLE_YES_NO[int(decoding.was_force_decoded)]
+        return DecodingTableRow.from_decoded_assessment(assessment, was_forced, display_text, sort_score)
+
+
+def _build_encodings_metric_dict():
+    """One key for each key in `ENCODINGS_TO_ATTEMPT`, values are all 0."""
+    metrics_dict = defaultdict(lambda: 0)
+
+    for encoding in ENCODINGS_TO_ATTEMPT.keys():
+        metrics_dict[encoding] = 0
+
+    return metrics_dict