This guide explains what is Usbrip program, how to track the details of connected or disconnected USB devices and also how to show USB devices event history using Usbrip tool in Linux.
Table of Contents
Introduction
Nowadays, USB devices are prevalent. You should be using lots of devices with a USB connector such as flash drive, external drive, mouse, keyboard, printer, mobile phone charger all day, everyday. Like every other events, the history of USB connections are also tracked by the Linux OS. Whenever you connect or disconnect an USB device, the USB devices event history is tracked and stored in one or more of the following files in your Linux system:
- /var/log/dmesg
- /var/log/daemon.log
- /var/log/kern.log
- /var/log/syslog
- /var/log/messages
You could manually go through these files to know your USB connections history or use a tool that helps to easily organize the USB artifacts in a neat tabular-column format. One such tool to track the USB event history is Usbrip.
About Usbrip
Usbrip is a command line forensics tool to track the history of all USB device connections in Linux. It analyzes your system's log data using journelctl
command or from log files such as /var/log/syslog
and /var/log/messages
and displays the collected USB event history in standard output or a file.
The usbrip program tracks the USB device artifacts and lists them under the following columns:
- Connected (date & time)
- Host
- VID (vendor ID)
- PID (product ID)
- Product
- Manufacturer
- Serial Number
- Port
- Disconnected" (date & time)
Usbrip is free and open source tool written in Python 3. For those wondering, the name Usbrip is derived from the two words - USB and Ripper. It is not USB R.I.P.
Usbrip features
Usbrip has a few interesting features. I'd like to mention the following three notable features.
1. Find unauthorized USB access
This is the main purpose of the Usbrip tool. Using usbrip tool, we can prove that a USB device was connected to a specific Linux system, by a specific user, within a specific time interval. In general, we can use Usbrip in any cases in which USB devices are involved.
As stated already, you can export all USB connection details in a JSON
file. Why do we dump the details in a JSON file? Because, we can easily search for any "violation events". For instance, we could create a file, say auth.json
, and store the list of authorized or trusted USB devices in that file.
The auth.json
file can be used to investigate which USB devices were connected and whether they are the authorized devices or not. This way it is possible to find out if some user has copied something from your system without your permission.
Please note that if you install usbrip using the installer script, the auth.json
file will be automatically created in the location /var/opt/usbrip/trusted/
at the time of installation. You can also create your own at any location of your choice.
2. Find USB device details
If you want to know specification details of an USB device, you can easily get them by using its VID or PID. Usbbrip will fetch the details of vendors, devices and interfaces from the usb.ids
database maintained at http://www.linux-usb.org/.
3. Backup USB events
If you've manually installed Usbrip with -s
(--storages
) option, you can automatically backup USB events with crontab scheduler.
Now let us see how to install and use Usbrip in Linux to collect USB connection events.
Install Usbrip in Linux
Since Usbrip is written in Python, we can install it using Pip package manager.
$ pip install usbrip
If you installed usbrip with pip, some features will be unavailable. To get all features, you should manually install usbrip using its installer script called install.sh
.
First, make sure you've installed necessary prerequisites:
- python3-venv
- p7zip
On Debian, Ubuntu and its derivatives, you can install them as shown below:
$ sudo apt install python3-venv p7zip-full
Git clone usbrip repository:
$ git clone https://github.com/snovvcrash/usbrip.git usbrip
The above command will clone the contents of usbrip repository and store them in a directory named "usbrip" in your current directory.
Cd into the usbrip directory:
$ cd usbrip
Make the installer script as executable:
$ chmod +x ./installers/install.sh
And finally install it using command:
$ sudo -H ./installers/install.sh -s
Here, we used -s
flag to enable storage module. This will not only install the usbrip program, but also create the list of trusted USB devices, history and violations storages. Take a note of your secret password. You may need it later.
Once the installation is completed, you can remove the cloned directory:
$ cd
$ rm -r usbrip/
Show USB devices event history using Usbrip in Linux
Before starting to use it, let us get to know the list of general options and available flags.
1. Getting help
To view the help section of Usbrip program, simply run:
$ usbrip --help
Sample output:
usage: usbrip [-h] {banner,events,storage,ids} ... positional arguments: {banner,events,storage,ids} banner show tool banner events work with USB events storage work with USB event storage ids work with USB IDs optional arguments: -h, --help show this help message and exit
As you can see, there are four main commands, namely banner
, events
, storage
, and ids
.
To view the list of sub-commands for a specific main command, run:
$ usbrip <command> --help
Example:
$ usbrip events --help
To list all switches related to a specific sub-command, for example events
, run:
$ usbrip events genauth --help
2. View USB device connection history
To show the history of USB device connections, run:
$ usbrip events history
You will be prompted whether you want to display USB event history in standard output or in a JSON file. If you want to display the output, simply press ENTER (which is the default) or type number 2 to save it in a JSON file.
I go with the default output, hence I get this long output:
_ {{4}} {v2.2.2-1} _ _ ___| |_ ___[e]___ | | |_ -| . | _[n] . | |___|___|___|_| [5] _| x[1]_| https://github.com/snovvcrash/usbrip [*] Started at 2021-03-27 14:28:31 [14:28:31] [INFO] Trying to run journalctl... [14:29:10] [INFO] Successfully runned journalctl [14:29:11] [INFO] Reading journalctl output 100%|█████████████████████████████| 912197/912197 [00:04<00:00, 188838.07line/s] [?] How would you like your event history list to be generated? 1. Terminal stdout 2. JSON-file [>] Please enter the number of your choice (default 1): 1 [14:29:48] [INFO] Preparing collected events [14:29:48] [WARNING] Terminal window is too small to display table properly [14:29:48] [WARNING] Representation: list USB-History-Events −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Connected: 2020-12-26 21:24:23 Host: ostechnix VID: 0cf3 PID: 3002 Product: ∅ Manufacturer: ∅ Serial Number: ∅ Bus-Port: 1-1.4 Disconnected: 2020-12-26 21:24:24 . . . −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Connected: 2021-03-27 11:52:19 Host: ostechnix VID: 046d PID: c52b Product: USB Receiver Manufacturer: Logitech Serial Number: ∅ Bus-Port: 1-1.2 Disconnected: ∅ −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− [*] Shut down at 2021-03-27 14:29:48 [*] Time taken: 0:01:17.624936
By default, Usbrip will display the result in tabular column format. Since my Terminal window is too small to display table properly, the output is displayed in list format. If you want to insist Usbrip to display the result in tabular column format anyway, add -t
flag:
$ usbrip events history -t
You can customize the output as per your liking. In the following example, I used -q/--quiet
flag to suppress the banner and other user information, -l/--list
to display output in list format and -n/--number
to display specific number of outputs.
$ usbrip events history -ql -n 2
The above command will only show the latest 2 USB history events without the banner, info message and user interaction prompt.
Sample output:
100%|█████████████████████████████| 912890/912890 [00:05<00:00, 159754.38line/s] USB-History-Events −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Connected: 2021-03-27 10:16:08 Host: ostechnix VID: 0cf3 PID: 3005 Product: ∅ Manufacturer: ∅ Serial Number: ∅ Bus-Port: 1-1.4 Disconnected: ∅ −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− Connected: 2021-03-27 11:52:19 Host: ostechnix VID: 046d PID: c52b Product: USB Receiver Manufacturer: Logitech Serial Number: ∅ Bus-Port: 1-1.2 Disconnected: ∅ −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
3. Save USB event history in a file
Instead of displaying the event history in standard output, we can save it in a file with JSON format.
To do so, run the command to show USB event history:
$ usbrip events history
Type 2 when you are prompted to choose how would you like to save the output. You will be again asked to enter the location of output file name. Simply enter a location of your choice or press ENTER to save it to default file called history.json
in the $HOME
directory.
_ {{4}} {v2.2.2-1}
_ _ ___| |_ ___[3]___
| | |_ -| . | _[N] . |
|___|___|___|_| [5] _|
x[1]_| https://github.com/snovvcrash/usbrip
[*] Started at 2021-03-29 11:49:40
[11:49:40] [INFO] Trying to run journalctl...
[11:49:41] [INFO] Successfully ran journalctl
[11:49:41] [INFO] Reading journalctl output
100%|███████████████████████████████| 15910/15910 [00:00<00:00, 235574.33line/s]
[?] How would you like your event history list to be generated?
1. Terminal stdout
2. JSON-file
[>] Please enter the number of your choice (default 1): 2
[>] Please enter the output file name (default is "history.json")
:
[11:49:46] [INFO] Generating event history list (JSON)
[11:49:46] [INFO] New event history list: "/home/ostechnix/history.json"
[*] Shut down at 2021-03-29 11:49:46
[*] Time taken: 0:00:05.852216
You can view this file at any time using command:
$ usbrip events open history.json
4. Show external USB devices event history
To show the connection history of external devices use -e
, --external
flag:
$ usbrip events history -q -e
5. Show USB event history between a specific timeframe
We can use -d
, --date
flag to view the USB devices event history between certain period of time. For example, this command displays the event history that has been taken place between January 2021 to March 2021:
$ usbrip events history -q -d '2021-01-01' '2021-03-29'
6. Show certain information only
You might be interested in to view the specific events of USB connections. For instance, the following command will get you the details of columns namely Connected, Disconnected, Serial and Product name only:
$ usbrip events history -q -c conn disconn serial prod -n 20
Here, -n 20
option is used to display the recent 20 records.
7. Search details of specific USB devices
You might be interested to view the event history of a specific device. If so, you can use the --manufact
flag to view such details:
In the following example, I have displayed the 15 recent events of my Logitech wireless receiver. I also listed the details of only 4 columns namely Connected, Disconnected, Serial and Product.
$ usbrip events history -q -c conn disconn serial prod --manufact Logitech -n 15
Similarly, you can filter the USB events by combining many fields such as PID, VID, port, host name, serial no etc.
8. Generate a list of trusted USB devices
To create a list of authorized USB devices, use authgen
option:
$ sudo usbrip events genauth ~/auth.json -a vid pid -n 10 -d '2021-03-29'
This command will generate a list of trusted USB devices as a JSON file called auth.json
containing first 10 devices connected on March 29, 2021. Also, this file will only contain the details of VID and PID attributes.
9. Search for violations
If you want to check for any unauthorized USB access, simply search through the auth.json
file which we crated earlier.
$ sudo usbrip events violations ~/auth.json
You can also filter the output as per your liking.
Example:
$ sudo usbrip events violations ~/auth.json -a pid -et --host ostechnix --manufact Logitech --serial 0123456789 -c conn disconn
This command will search the event history of the external USB devices for violations based on the list of trusted USB devices (~/auth.json) by "PID" attribute, restrict resulting events to those which have "ostechnix" as a hostname, "Logitech" as a manufacturer, "0123456789" as a serial number and display the output as a table with "Connected", "Disconnected" columns.
If a USB device appears in the history but not in the auth.json
file, we can say that there is a violation event.
For more usage details, refer the project's GitHub page given below.
Resource:
Related read: