Skip to content

USBHawk 1.0.1

Choose a tag to compare

@aakashraman aakashraman released this 19 Nov 00:40
· 8 commits to main since this release

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.