YARA Match Report Generator

Build a utility that scans files with YARA rules and generates detailed match reports. The tool should process scan results and extract comprehensive information about pattern matches.

Capabilities

Scan and Process Match Results

Execute YARA scans and extract match information from results.

• Scanning data with compiled rules returns match objects containing rule names and namespaces. @test
• Each match object provides access to tags and metadata defined in the matched rule. @test

Extract String Match Details

Process string pattern matches within matched rules.

• Match objects expose a list of matched strings with their identifiers. @test
• Each matched string provides instances showing where the pattern occurred. @test

Analyze Match Instance Data

Extract detailed information from individual match instances.

• Match instances provide the byte offset where the pattern was found. @test
• Match instances expose the actual matched data for inspection. @test
• Match instances provide the length of the matched data. @test

Generate Match Report

Format match information into a structured report.

• Given match results, generate a report listing all matched rules with their metadata. @test
• For each matched rule, include details of all matched strings with their identifiers. @test
• For each matched string, include instance details with offsets and matched data. @test

Implementation

@generates

API

def scan_and_report(rules, data):
    """
    Scan data with YARA rules and generate a detailed match report.

    Parameters:
    - rules: Compiled YARA Rules object
    - data: Bytes or string data to scan

    Returns:
    A dictionary containing:
    {
        "total_matches": int,  # Number of rules that matched
        "matches": [
            {
                "rule": str,      # Rule name
                "namespace": str, # Rule namespace
                "tags": [str],    # Rule tags
                "meta": dict,     # Rule metadata
                "strings": [
                    {
                        "identifier": str,  # String identifier (e.g., "$a")
                        "instances": [
                            {
                                "offset": int,        # Byte offset in data
                                "matched_data": bytes, # Actual matched bytes
                                "length": int         # Length of match
                            }
                        ]
                    }
                ]
            }
        ]
    }
    """
    pass

def format_report(report_data):
    """
    Format a match report into human-readable text.

    Parameters:
    - report_data: Dictionary returned from scan_and_report()

    Returns:
    A formatted string report showing:
    - Total number of matches
    - Each matched rule with its metadata
    - String matches with identifiers
    - Instance details with offsets and data
    """
    pass

Dependencies { .dependencies }

yara-python { .dependency }

Provides YARA pattern matching and result processing capabilities.

@satisfied-by