Repository navigation
USBHawk 1.0.0
USB forensics for threat hunting and incident response. Point USBHawk at a Windows triage collection (KAPE, Velociraptor, a mounted disk image or a live machine) and it tells you which USB sessions look like data theft and why, whether someone wiped the USB evidence, where else each stick has been, and how to catch it live next time.
| Command | The question it answers |
|---|---|
usbhawk sessions |
Which USB sessions look like data exfiltration, and why? |
usbhawk tamper |
Did someone wipe the USB evidence, or did Windows clean it up? |
usbhawk detections |
How do we catch it live next time? (Sigma, Elastic, Microsoft Sentinel) |
usbhawk graph |
Where else has this stick been, and who else used it? |
Downloads
| File | For |
|---|---|
usbhawk-1.0.0-windows-x64.zip |
Windows, no Python needed: unzip and run .\usbhawk.exe. Includes the docs, the demo data, collect_local.ps1 for live response and the lab Sysmon config |
usbhawk-1.0.0-py3-none-any.whl |
Python 3.11+ on Windows, Linux or macOS: pip install usbhawk-1.0.0-py3-none-any.whl |
SHA256SUMS.txt |
Check your download: Get-FileHash <file> (PowerShell) or certutil -hashfile <file> SHA256 (CMD) |
The exe is not code-signed yet, so SmartScreen may warn on first run (More info, Run anyway).
Try it in two minutes
.\usbhawk.exe detections run --events examples\detections\insider_timeline.jsonl
.\usbhawk.exe tamper --triage examples\tamper\wiped-host
.\usbhawk.exe graph --runs examples\graph\fleet device 60A44C41
Start here: the four use cases on one page · getting started · KAPE, Velociraptor and Elastic · changelog
Validated on
- The NIST CFReDS Data Leakage case (both USB sticks of the answer key found; no false tamper or detection alerts)
- A Windows 10 VM wiped with USBOblivion 1.17.0, cross-checked with Eric Zimmerman's RECmd and EvtxECmd
- EVTX-ATTACK-SAMPLES (real log clearing)
- A real Windows 11 PC, live, with and without Sysmon
- 417 automated tests; every documented command is run by the test suite
All demo data is fictional. Use USBHawk only on systems and evidence you are authorised to examine.