Skip to content

Releases

USBHawk 1.0.2

Choose a tag to compare

@aakashraman aakashraman released this 19 Nov 03:26

Fixes from a second pass over a real KAPE collection (a VHDX of a running Windows 10 PC). Checked on that collection with the 1.0.2-rc1 test build before release.

What changed

Before 1.0.2
setupapi.dev.log (local time) was converted with the offset in force at collection, so installs from the other side of a daylight-saving change were an hour off, and could show as a ghost "no removal" session one hour after the real one Converted with the host's time zone and its DST rules; the offset at collection is only a fallback (details.tz_used). On the real collection, setupapi now agrees to the second with Partition/Diagnostic 1006 and System 20003
An external hard disk whose USB node and disk events (Security 6416) came a few seconds apart showed as two rows in the replay table, with two first-seen alerts Paired within 30 s; a row never holds two disks or two USB nodes, so a quick re-plug stays two rows
Orphaned MountPoints2 volume GUIDs gave no time of their own The tamper finding decodes the time inside the GUID ("first mounted here at or shortly after", since the stamp can run a few minutes early) and counts other orphans stamped in the same second, which one stick's plug-in cannot explain
"Look at first" under the replay table showed times without dates Full dates, first to last
A wrong --system / --software / --ntuser path only warned, and the run went on without that hive (as "unknown-host", with every orphan check skipped) Stops before loading anything and suggests the file in that folder, for example the name rla.exe gave the replayed hive (F_C_Windows_System32_config_SYSTEM)
The dirty-hive warning for a user hive said --system / --software Names the flag that takes that hive (--ntuser <clean file>=<user> for a user hive)

Release files updated on 2026-11-19 with the last two rows, found by replaying the real collection's dirty hives with rla.exe. With the clean hives, the orphan raised for the drive connected just before collection disappeared, as its dirty-hive caution had said it might. If you downloaded 1.0.2 earlier, re-download; the hashes below are the current ones.

Details: CHANGELOG

Downloads

File For
usbhawk-1.0.2-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.2-py3-none-any.whl Python 3.11+ on Windows, Linux or macOS: pip install usbhawk-1.0.2-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).

449 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.

USBHawk 1.0.1

Choose a tag to compare

@aakashraman aakashraman released this 19 Nov 00:40

Fixes from the first run on a real KAPE collection (a VHDX of a running Windows 10 PC). Evidence copied from a running machine is imperfect; 1.0.1 makes USBHawk read what it can, say what it could not, and not mistake collection artefacts for tampering.

What changed

Before 1.0.1
One damaged chunk in a log copied while open ("Invalid EVTX chunk header magic") dropped the whole file Read around the damage, with a warning naming the file and the records skipped and read. A record-ID jump in a damaged Partition/Diagnostic log is low ("may be damage rather than deletion"), not medium
A malformed record ("System": null) stopped the file Skipped
detections run judged off hours (H2) in UTC Uses the host's clock: --tz (new on run), else the time zone in the SYSTEM hive found next to the logs, else UTC with a warning. The first output line names the zone
A dirty hive (newest changes still in .LOG1/.LOG2) went unnoticed, so a stick connected just before collection could look wiped Flagged with rla.exe advice; every orphaned_device_reference on a dirty SYSTEM hive carries a caution
Each USB plug-in appeared twice in the replay table (6416 for the USB device and for its disk) One row per plug-in, marked as such; alerts.jsonl keeps both, as a live rule would
WIN-... computer names from Windows.old logs were unexplained Windows.old logs are labelled as the previous installation; evidence_host_mismatch explains setup-time names
--triage case.vhdx said "folder not found" A disk image (.vhdx, .vhd, .E01, .dd, .raw, .vmdk) prints the read-only mount steps
Square brackets in evidence text (device names, labels) could vanish from the tables Shown literally

KAPE VHDX in four commands

Mount-DiskImage -ImagePath D:\kape\HOST.vhdx -Access ReadOnly
usbhawk tamper   --triage F:\ --out runs\HOST
usbhawk sessions --triage F:\ --out runs\HOST
usbhawk detections run --evtx F:\ --out runs\HOST\detections

Details: INTEGRATIONS.md · changelog

Downloads

File For
usbhawk-1.0.1-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.1-py3-none-any.whl Python 3.11+ on Windows, Linux or macOS: pip install usbhawk-1.0.1-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).

438 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.

USBHawk 1.0.0

Choose a tag to compare

@aakashraman aakashraman released this 18 Nov 16:20

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.