Metadata-Version: 2.4
Name: wddh
Version: 1.0.1
Summary: Parser for Windows Defender Detection history
License: Apache-2.0
License-File: LICENSE
Author: Billaud William
Author-email: william.billaud@orange.com
Requires-Python: <4.0,>=3.10
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Project-URL: Changelog, https://github.com/cert-orangecyberdefense/wddh-parser/blob/master/CHANGELOG.md
Project-URL: Homepage, https://github.com/cert-orangecyberdefense/wddh-parser
Project-URL: Issues, https://github.com/cert-orangecyberdefense/wddh-parser/issues
Project-URL: Repository, https://github.com/cert-orangecyberdefense/wddh-parser.git
Description-Content-Type: text/markdown

# Description

Parser for Windows Defender Detection history files.

DetectionHistory files are located  `C:\ProgramData\Microsoft\Windows Defender\Scans\History\Service\DetectionHistory\` folder.
They are generated by Windows defender and content can be query on a live system using WMI : `Get-WmiObject -Namespace "root\Microsoft\Windows\Defender" -Class MSFT_MpThreatDetection`

This artifact is probably not the first one to look in an incident response/analysis, but can contain some valuable information not always logged by Microsoft defenders, such as binary hash.

This tools allows to dump information present in these files in json format. It can also be used as a library.
Further information regarding format is located in the file [doc.md](./doc.md).

## Installation

```commandline
pip install wddh
```

```commandline
# Local install
git clone https://github.com/cert-orangecyberdefense/wddh-parser.git
cd wddh 
pip install .
# or using uv
uv run wddh
```

Pre compiled binaries are also available in the release section https://github.com/cert-orangecyberdefense/wddh-parser/releases

## Usage

```
usage: wddh [-h] [-i INFILE] [-D DIRECTORY] [-s] [-o [OUTFILE]] [-d] [-v] [-V]

Parser for Windows Defender Detection history (files located under \ProgramData\Microsoft\Windows Defender\Scans\History\Service\DetectionHistory\)

options:
  -h, --help            show this help message and exit
  -i INFILE, --in INFILE
                        Input file
  -D DIRECTORY, --directory DIRECTORY
                        Input directory
  -s, --short           Only return a subset of information
  -o [OUTFILE], --out [OUTFILE]
  -d, --debug           Logs in debug mode (DEBUG)
  -v, --verbose         Logs in verbose mode (INFO)
  -V, --version         show program's version number and exit
```

### Parse a single file

```
❯ wddh -s -i samples/original/94BBE9CF-CDEB-4885-9178-CC93FB10822D   | jq '.'
{
  "threat_id": 2147686744,
  "threat_name": "HackTool:Win32/Mimikatz",
  "threat_status": "Quarantined",
  "domain_user": "DESKTOP-O8964S4\\RaptorSniper",
  "domain_user_group": "NT AUTHORITY\\SYSTEM",
  "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
  "initial_detection_time": "2025-01-28T16:44:51.243160+00:00",
  "remediation": "2025-01-28T16:45:06.220888+00:00",
  "ressources": [
    "file C:\\Users\\RaptorSniper\\Downloads\\a.zip"
  ],
  "misc": {
    "ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5",
    "ThreatTrackingSigSeq": 24633990908277,
    "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073",
    "ThreatTrackingStartTime": 133825562912428260,
    "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz",
    "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b",
    "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac",
    "ThreatTrackingSize": 1206166,
    "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db",
    "ThreatTrackingScanFlags": 17,
    "ThreatTrackingIsEsuSig": false,
    "ThreatTrackingThreatId": 2147686744,
    "ThreatTrackingScanSource": 3,
    "ThreatTrackingScanType": 0
  }
}
```

### Parse a single file (dump all datas)

```
❯ wddh -i samples/original/94BBE9CF-CDEB-4885-9178-CC93FB10822D  | jq '.'
{
  "header": {
    "threat_id": 2147686744,
    "detection_id": "94bbe9cf-cdeb-4885-9178-cc93fb10822d",
    "magic_version": "Magic.Version:1.2",
    "threat_name": "HackTool:Win32/Mimikatz"
  },
  "flag_section": {
    "flag_1": 0,
    "flag_2": 4,
    "flag_3": 34,
    "flag_4": 87,
    "flag_5": 4,
    "threat_status_id": "ThreatStatusID.Quarantined",
    "flag_list_len": 3,
    "flag_list": [
      2,
      3,
      6
    ],
    "alert_detail_count": 1
  },
  "alert_details": [
    {
      "magic_version": "Magic.Version:1.2",
      "ressource_type": "file",
      "ressource_location": "C:\\Users\\RaptorSniper\\Downloads\\a.zip",
      "flag_1": 268435457,
      "blob_len": 1289,
      "blob": {
        "ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5",
        "ThreatTrackingSigSeq": 24633990908277,
        "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073",
        "ThreatTrackingStartTime": 133825562912428260,
        "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz",
        "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b",
        "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac",
        "ThreatTrackingSize": 1206166,
        "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db",
        "ThreatTrackingScanFlags": 17,
        "ThreatTrackingIsEsuSig": false,
        "ThreatTrackingThreatId": 2147686744,
        "ThreatTrackingScanSource": 3,
        "ThreatTrackingScanType": 0
      }
    }
  ],
  "metadata": {
    "last_threat_status_change": "2025-01-28T16:45:06.220888+00:00",
    "threat_status_error_code": 0,
    "flag_1": 0,
    "unknown_uid": "80031958-0000-0000-862b-597c89800a50",
    "current_threat_execution_id": 1
  },
  "optional": null,
  "metadata_2": {
    "flag_1": 2,
    "domain_user": "DESKTOP-O8964S4\\RaptorSniper",
    "flag_2": 3,
    "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
    "flag_3": 3,
    "flag_4": 1,
    "flag_5": 0,
    "initial_detection_time": "2025-01-28T16:44:51.243160+00:00",
    "flag_6": 0,
    "remediation": "2025-01-28T16:45:06.220888+00:00",
    "flag_7": 0,
    "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>",
    "flag_8": 0,
    "domain_user_group": "NT AUTHORITY\\SYSTEM",
    "flag_9": 0,
    "count_following_information_section": 0
  },
  "alert_details_2": [],
  "footer": {
    "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>",
    "flag_1": 0,
    "flag_2": 0,
    "flag_3": 0,
    "flag_4": 1
  }
}
```


### Parse a directory recursively

```
wddh -D samples
[21ms]__init__:74 | WARNING - Do not find expected type at offset 0x4. Expected : TLVTypeEnum.UINT64, Found : TLVTypeEnum.MISSING
[21ms]main:129 | WARNING - Fail to parse samples/search_threat_id/note.md : unpack requires a buffer of 8 bytes
[21ms]__init__:74 | WARNING - Do not find expected type at offset 0x4. Expected : TLVTypeEnum.UINT64, Found : TLVTypeEnum.MISSING
[21ms]main:129 | WARNING - Fail to parse samples/action_id/note.md : unpack requires a buffer of 8 bytes
[21ms]__init__:74 | WARNING - Do not find expected type at offset 0x4. Expected : TLVTypeEnum.UINT64, Found : TLVTypeEnum.MISSING
[21ms]main:129 | WARNING - Fail to parse samples/ts_modified/note.md : unpack requires a buffer of 8 bytes
{"header": {"threat_id": 2147686744, "detection_id": "94bbe9cf-cdeb-4885-9178-cc93fb10822d", "magic_version": "Magic.Version:1.2", "threat_name": "HackTool:Win32/Mimikatz"}, "flag_section": {"flag_1": 0, "flag_2": 4, "flag_3": 34, "flag_4": 87, "flag_5": 4, "threat_status_id": "ThreatStatusID.Quarantined", "flag_list_len": 3, "flag_list": [2, 3, 6], "alert_detail_count": 1}, "alert_details": [{"magic_version": "Magic.Version:1.2", "ressource_type": "file", "ressource_location": "C:\\Users\\RaptorSniper\\Downloads\\a.zip", "flag_1": 268435457, "blob_len": 1289, "blob": {"ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5", "ThreatTrackingSigSeq": 24633990908277, "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073", "ThreatTrackingStartTime": 133825562912428256, "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz", "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b", "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac", "ThreatTrackingSize": 1206166, "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db", "ThreatTrackingScanFlags": 17, "ThreatTrackingIsEsuSig": false, "ThreatTrackingThreatId": 2147686744, "ThreatTrackingScanSource": 3, "ThreatTrackingScanType": 0}}], "metadata": {"last_threat_status_change": "2025-01-28T16:45:06.220888+00:00", "threat_status_error_code": 0, "flag_1": 0, "unknown_uid": "80031958-0000-0000-862b-597c89800a50", "current_threat_execution_id": 1}, "optional": null, "metadata_2": {"flag_1": 2, "domain_user": "DESKTOP-O8964S4\\RaptorSniper", "flag_2": 3, "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "flag_3": 3, "flag_4": 1, "flag_5": 0, "initial_detection_time": "2025-01-28T16:44:51.243160+00:00", "flag_6": 0, "remediation": "2025-01-28T16:45:06.220888+00:00", "flag_7": 0, "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_8": 0, "domain_user_group": "NT AUTHORITY\\SYSTEM", "flag_9": 0, "count_following_information_section": 0}, "alert_details_2": [], "footer": {"unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_1": 0, "flag_2": 0, "flag_3": 0, "flag_4": 1}}
{"header": {"threat_id": 2147686744, "detection_id": "94bbe9cf-cdeb-4885-9178-cc93fb10822d", "magic_version": "Magic.Version:1.2", "threat_name": "HackTool:Win32/Mimikatz"}, "flag_section": {"flag_1": 0, "flag_2": 4, "flag_3": 34, "flag_4": 87, "flag_5": 16, "threat_status_id": "ThreatStatusID.MISSING", "flag_list_len": 3, "flag_list": [2, 3, 6], "alert_detail_count": 1}, "alert_details": [{"magic_version": "Magic.Version:1.2", "ressource_type": "file", "ressource_location": "C:\\Users\\RaptorSniper\\Downloads\\a.zip", "flag_1": 268435457, "blob_len": 1289, "blob": {"ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5", "ThreatTrackingSigSeq": 24633990908277, "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073", "ThreatTrackingStartTime": 133825562912428256, "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz", "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b", "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac", "ThreatTrackingSize": 1206166, "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db", "ThreatTrackingScanFlags": 17, "ThreatTrackingIsEsuSig": false, "ThreatTrackingThreatId": 2147686744, "ThreatTrackingScanSource": 3, "ThreatTrackingScanType": 0}}], "metadata": {"last_threat_status_change": "2025-01-28T16:45:06.220888+00:00", "threat_status_error_code": 0, "flag_1": 0, "unknown_uid": "80031958-0000-0000-862b-597c89800a50", "current_threat_execution_id": 1}, "optional": null, "metadata_2": {"flag_1": 2, "domain_user": "DESKTOP-O8964S4\\RaptorSniper", "flag_2": 3, "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "flag_3": 3, "flag_4": 1, "flag_5": 0, "initial_detection_time": "2025-01-28T16:44:51.243160+00:00", "flag_6": 0, "remediation": "2025-01-28T16:45:06.220888+00:00", "flag_7": 0, "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_8": 0, "domain_user_group": "NT AUTHORITY\\SYSTEM", "flag_9": 0, "count_following_information_section": 0}, "alert_details_2": [], "footer": {"unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_1": 0, "flag_2": 0, "flag_3": 0, "flag_4": 1}}
{"header": {"threat_id": 2147686744, "detection_id": "94bbe9cf-cdeb-4885-9178-cc93fb10822d", "magic_version": "Magic.Version:1.2", "threat_name": "HackTool:Win32/Mimikatz"}, "flag_section": {"flag_1": 0, "flag_2": 4, "flag_3": 34, "flag_4": 87, "flag_5": 4, "threat_status_id": "ThreatStatusID.Quarantined", "flag_list_len": 3, "flag_list": [2, 3, 6], "alert_detail_count": 1}, "alert_details": [{"magic_version": "Magic.Version:1.2", "ressource_type": "file", "ressource_location": "C:\\Users\\RaptorSniper\\Downloads\\a.zip", "flag_1": 268435457, "blob_len": 1289, "blob": {"ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5", "ThreatTrackingSigSeq": 24633990908277, "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073", "ThreatTrackingStartTime": 133825562912428256, "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz", "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b", "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac", "ThreatTrackingSize": 1206166, "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db", "ThreatTrackingScanFlags": 17, "ThreatTrackingIsEsuSig": false, "ThreatTrackingThreatId": 2147686744, "ThreatTrackingScanSource": 3, "ThreatTrackingScanType": 0}}], "metadata": {"last_threat_status_change": "2025-01-28T16:45:06.220888+00:00", "threat_status_error_code": 7, "flag_1": 0, "unknown_uid": "80031958-0000-0000-862b-597c89800a50", "current_threat_execution_id": 5}, "optional": null, "metadata_2": {"flag_1": 3, "domain_user": "DESKTOP-O8964S4\\RaptorSniper", "flag_2": 3, "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "flag_3": 3, "flag_4": 1, "flag_5": 0, "initial_detection_time": "2025-01-28T16:44:51.243160+00:00", "flag_6": 0, "remediation": "2025-01-28T16:45:06.220888+00:00", "flag_7": 0, "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_8": 0, "domain_user_group": "NT AUTHORITY\\SYSTEM", "flag_9": 0, "count_following_information_section": 0}, "alert_details_2": [], "footer": {"unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_1": 0, "flag_2": 0, "flag_3": 0, "flag_4": 1}}
{"header": {"threat_id": 2147686744, "detection_id": "94bbe9cf-cdeb-4885-9178-cc93fb10822d", "magic_version": "Magic.Version:1.2", "threat_name": "HackTool:Win32/Mimikatz"}, "flag_section": {"flag_1": 0, "flag_2": 4, "flag_3": 34, "flag_4": 87, "flag_5": 4, "threat_status_id": "ThreatStatusID.Quarantined", "flag_list_len": 3, "flag_list": [2, 3, 6], "alert_detail_count": 1}, "alert_details": [{"magic_version": "Magic.Version:1.2", "ressource_type": "file", "ressource_location": "C:\\Users\\RaptorSniper\\Downloads\\a.zip", "flag_1": 268435457, "blob_len": 1289, "blob": {"ThreatTrackingSha256": "7accd179e8a6b2fc907e7e8d087c52a7f48084852724b03d25bebcada1acbca5", "ThreatTrackingSigSeq": 24633990908277, "ThreatTrackingId": "DC97D2FF-71EA-44A3-BED5-851EC71A1073", "ThreatTrackingStartTime": 133825562912428256, "ThreatTrackingThreatName": "HackTool:Win32/Mimikatz", "ThreatTrackingSha1": "4112ef95386ea4d1131be7c600d49a310e9d8f5b", "ThreatTrackingSigSha": "690c01740c8b5e15fb8f56402cdd51d18e31faac", "ThreatTrackingSize": 1206166, "ThreatTrackingMD5": "d2d3e1f8023b12fb89e400c7e8ecd7db", "ThreatTrackingScanFlags": 17, "ThreatTrackingIsEsuSig": false, "ThreatTrackingThreatId": 2147686744, "ThreatTrackingScanSource": 3, "ThreatTrackingScanType": 0}}], "metadata": {"last_threat_status_change": "2025-01-28T16:45:06.220888+00:00", "threat_status_error_code": 0, "flag_1": 0, "unknown_uid": "80031958-0000-0000-862b-597c89800a50", "current_threat_execution_id": 1}, "optional": null, "metadata_2": {"flag_1": 2, "domain_user": "DESKTOP-O8964S4\\RaptorSniper", "flag_2": 3, "process_name": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "flag_3": 3, "flag_4": 1, "flag_5": 0, "initial_detection_time": "2025-01-28T16:44:51.243160+00:00", "flag_6": 0, "remediation": "2025-01-28T16:52:16.241905+00:00", "flag_7": 0, "unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_8": 0, "domain_user_group": "NT AUTHORITY\\SYSTEM", "flag_9": 0, "count_following_information_section": 0}, "alert_details_2": [], "footer": {"unknown_1": "<L:4|T:0|V:b'\\x00\\x00\\x00\\x00'>", "flag_1": 0, "flag_2": 0, "flag_3": 0, "flag_4": 1}}
```

### As a library

```
from wddh.wddh_clean import WDDHClean
with open("./samples/original/94BBE9CF-CDEB-4885-9178-CC93FB10822D","rb") as f:
    wddh = WDDHClean(f)
print(wddh.header.detection_id)
```

## License

See [license](./LICENSE).
Some sample used in tests data are from the [AndrewRathbun/DFIRArtifactMuseum](https://github.com/AndrewRathbun/DFIRArtifactMuseum/). See associated [license](./tests/data/DFIRArtifactMuseum/).

## References

The following projects contain information related to this artifact :

* <https://github.com/log2timeline/plaso/blob/main/plaso/parsers/windefender_history.py>
* <https://github.com/libyal/dtformats/blob/main/documentation/Windows%20Defender%20scan%20DetectionHistory%20file%20format.asciidoc>
* <https://github.com/jklepsercyber/defender-detectionhistory-parser>
* <https://www.orangecyberdefense.com/global/blog/cybersecurity/digging-into-windows-defender-detection-history-wddh>

