A simple tool written in C to detect changes in USB devices, and optionally execute a command when a change is detected.
This is designed to be used in scripts or other applications, or running as a daemon with the watch
command.
You may alternatively use udev
rules to monitor USB events, but this tool is more lightweight and easier to use.
If your goal is to mitigate the risk of USB-based attacks, consider using usbguard, which allows you to define policies for USB devices.
Download the latest release from the releases page and extract the binary to a directory in your PATH.
-- OR --
git clone --depth=1 https://github.com/mathiscode/usb-see.git
cd usb-see
make && make install-user
# or
make && sudo make install-system
which usb-see # should show the path to the installed binary
To uninstall, run make uninstall-user
or sudo make uninstall-system
in the usb-see repository, or simply delete the usb-see
binary.
usb-see [OPTIONS] COMMAND
--file
or-f
- Path to the USB state file. Default: ~/.config/usb.state--exec
or-e
- Command to execute when a change is detected. Default: false- The command may contain the following placeholders:
_USB_
- The USB device line fromlsusb
_ACTION_
- The action that occurred (added
orremoved
)
- The command may contain the following placeholders:
freeze
- Freeze the current USB state to the state filescan
- Scan for any added or removed USB deviceswatch
- Watch for changes in USB devices and execute a command when a change is detected
-
Freeze the current USB state to the default state file and scan for changes
usb-see freeze usb-see scan
-
Freeze the current USB state to a custom state file
usb-see --file /tmp/usb.state freeze
-
Watch for changes in USB devices and execute a command when a change is detected
usb-see --exec 'echo "_USB_ was _ACTION_"' watch
- 0: Success; no changes detected
- 1: Device added
- 2: Device removed
- 255: An error occurred, most likely file access