hfiref0x-DefenderRulesPlus/README.md

DefenderRulesPlus

Tool designed to parse and analyze Microsoft Defender AV signature definition files.

This tool may generate per-threat .bin files derived from Microsoft Defender definition data.
These files are intended for local research only and must not be published or redistributed (e.g. in issues, gists, or repositories).
Do not attach .vdm, .extracted, or .bin artifacts to public resources.

Description

DefenderRulesPlus parses Microsoft Defender signature definition files extracted from .vdm containers with WDExtract.

The tool is focused on local analysis and reporting. It can:

• parse threat entries directly from extracted Defender signature data
• resolve threat names from embedded file metadata
• optionally enrich threat names from a user-supplied catalog CSV
• export per-threat binary chunks
• generate CSV statistics
• optionally generate HTML charts
• filter output to a specific threat name substring

Unlike the original implementation, the parser no longer depends on auto-generating defender.csv through PowerShell in order to function correctly. Embedded threat metadata in the parsed file is used as the primary source of truth, while an external catalog is optional enrichment only.

Features

• File-driven parsing of extracted Defender signature data
• Optional threat catalog enrichment via --catalog <CatalogCsv>
• Optional export filtering with --threat <substring>
• Quieter execution with --quiet
• Optional export suppression with --no-export
• Statistics-only mode with --stats-only
• Optional HTML chart generation with --html
• Faster parsing through byte-array processing and static signature lookup
• CSV and HTML reporting for signature type distribution

Requirements

• .NET 10 SDK/runtime
• Extracted Defender definition file produced from .vdm
• No PowerShell or Windows Defender catalog export is required for normal operation

Preparing input data

Use WDExtract to unpack or decrypt the original Defender container before running DefenderRulesPlus.

Typical workflow:

wdextract mpasbase.vdm
DefenderRulesPlus mpasbase.extracted ./output

You can also merge base and delta definition files with WDExtract first, then analyze the merged result:

wdextract mpasbase.extracted mpasdlta.extracted -m -mc
DefenderRulesPlus mpasbase.extracted.merged ./output

Usage

DefenderRulesPlus <FilePath> <OutputDirectory> [--catalog <CatalogCsv>] [--threat <substring>] [--quiet] [--no-export] [--stats-only] [--html]

Command line options

Option	Description
--catalog <CatalogCsv>	Optional CSV file used to enrich threat names.
--threat <substring>	Only include threats whose resolved name contains the specified substring, case-insensitive.
--quiet	Reduce console output.
--no-export	Do not write per-threat .bin files.
--stats-only	Write reports/statistics only. Implies --no-export.
--html	Generate HTML chart reports.

Examples

DefenderRulesPlus mpasbase.extracted ./output
DefenderRulesPlus mpasbase.extracted ./output --catalog defender.csv
DefenderRulesPlus mpasbase.extracted ./output --threat Wacatac
DefenderRulesPlus mpasbase.extracted ./output --quiet --stats-only
DefenderRulesPlus mpasbase.extracted ./output --html

Behavior

This tool:

• parses threat data from the extracted Defender binary
• uses embedded threat names found in the file
• optionally enriches threat names from a supplied CSV catalog
• exports matching threat chunks as .bin files unless export is disabled
• writes logs and CSV statistics
• optionally writes two HTML dashboards

Output

File Name	Description
output.txt	List of identified threat entries
missing.txt	Threats present in the optional catalog but not found in the parsed file
ThreatsStats.csv	Threat-by-threat signature type counts
ThreatsGlobalStats.csv	Total signature type usage across filtered threats
Top30GlobalStatsChart.html	Optional bar chart of the most common signature types
ThreatGroupStatsCharts.html	Optional grouped charts by threat category
<ThreatName>.bin	Binary data for each exported threat rule

Notes

• The parser operates on extracted Defender signature data, not directly on compressed .vdm containers.
• Threat names embedded in the parsed file are preferred over external catalog data.
• Catalog CSV input is optional and is used only for name enrichment and missing-entry reporting.
• Filtering with --threat affects exports and generated reports.
• Use WDExtract-generated .extracted or merged output as the preferred input format.

Related references and tools

• Original DefenderRules project
• WDExtract
• PowerShell unpack script for packed VDM containers
• Windows Defender Emulator Tools
• Porting Windows Dynamic Link Libraries to Linux
• MpEnum
• libmpclient
• Windows Defender's VDM Format

Disclaimer

This tool is intended for educational and security analysis purposes only.
Improper use may violate Microsoft's license agreements. Use responsibly and only on systems you own or are authorized to analyze.

Author

Project based on the original DefenderRules by Andrea Cristaldi, with additional fixes, refactoring and feature extensions.

License

This project is licensed under the MIT License.