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](https://github.com/hfiref0x/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](https://github.com/hfiref0x/WDExtract) to unpack or decrypt the original Defender container before running DefenderRulesPlus.

Typical workflow:

```text
wdextract mpasbase.vdm
DefenderRulesPlus mpasbase.extracted ./output
```

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

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

## Usage
```text
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
```text
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](https://github.com/andreacristaldi/DefenderRules)
- [WDExtract](https://github.com/hfiref0x/WDExtract)
- [PowerShell unpack script for packed VDM containers](https://gist.github.com/mattifestation/3af5a472e11b7e135273e71cb5fed866)
- [Windows Defender Emulator Tools](https://github.com/0xAlexei/WindowsDefenderTools)
- [Porting Windows Dynamic Link Libraries to Linux](https://github.com/taviso/loadlibrary)
- [MpEnum](https://github.com/hfiref0x/MpEnum)
- [libmpclient](https://github.com/UldisRinkevichs/libmpclient)
- [Windows Defender's VDM Format](https://github.com/commial/experiments/tree/master/windows-defender/VDM)

## 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](https://github.com/andreacristaldi/DefenderRules) by Andrea Cristaldi, with additional fixes, refactoring and feature extensions.

## License
This project is licensed under the MIT License.