4 releases (2 breaking)

0.3.0 Jun 24, 2024
0.2.1 May 31, 2024
0.2.0 May 23, 2024
0.1.0 May 16, 2024

#525 in Hardware support

MIT license

46KB
1K SLoC

hid-recorder

HID Recorder is a utility to record HID data from a /dev/hidraw device and print both the HID Report Descriptor and the HID Reports in a human and machine-readable format. This output can be used for analysis and/or replaying devices and their events.

This is a Rust reimplementation of hid-recorder from hid-tools

Installation

The easiest is to install with cargo:

$ cargo install hid-recorder
$ hid-recorder

This installs in $CARGO_HOME (usually $HOME/.cargo) and is sufficient for use-cases where you only neeed to analyze the HID Report Descriptor (not events from the device)

For use-cases where you need to record events (HID Reports) hid-recorder needs read access to the respective /dev/hidraw device. Typically this means you need to run as root. The easiest way is to run through pkexec which will ask for your user's password:

$ pkexec hid-recorder

Alternatively you can install hid-recorder so you can access it via sudo:

Sudo-compatible Installation

Install as user in $CARGO_HOME

This is the default cargo installation but requires that you add the path manually when running hid-recorder:

$ cargo install hid-recorder
$ sudo $HOME/.cargo/bin/hid-recorder

Install as root in /usr/local

Install hid-recorder in /usr/local/ which is typically part of the default $PATH.

$ sudo CARGO_INSTALL_ROOT=/usr/local cargo install hid-recorder
$ sudo hid-recorder

Allow access to the device to non-root users

This is the least safe option as once read access is granted, any process can read events from the device. If the device is a keyboard this allows for key loggers to read all events.

$ cargo install hid-recorder
$ sudo chmod o+r /dev/hidraw0
$ hid-recorder

It is recommended to remove these permissions once the recording is complete:

$ sudo chmod o-r /dev/hidraw0

Recording a device

The typical use is a request for "attach a hid recording" in an issue. To do this, run hid-recorder with no arguments and pick the device in question, e.g.

$ sudo hid-recorder
# Available devices:
# /dev/hidraw0:     Microsoft Microsoft® 2.4GHz Transceiver v9.0
# /dev/hidraw1:     Microsoft Microsoft® 2.4GHz Transceiver v9.0
# /dev/hidraw2:     Microsoft Microsoft® 2.4GHz Transceiver v9.0
# /dev/hidraw3:     Logitech USB Receiver
# /dev/hidraw4:     HUION Huion Tablet_H641P
# /dev/hidraw5:     HUION Huion Tablet_H641P
# /dev/hidraw6:     HUION Huion Tablet_H641P
# /dev/hidraw7:     Yubico YubiKey OTP+FIDO+CCID
# /dev/hidraw8:     Logitech ERGO K860
# /dev/hidraw9:     Yubico YubiKey OTP+FIDO+CCID
# Select the device event number [0-9]:

Alternatively provide the /dev/hidraw path directly:

$ sudo hid-recorder /dev/hidraw0

Use the --help option to see more options.

Dependencies

~5–12MB
~145K SLoC