Home Command line utilities Show USB Devices Event History Using Usbrip In Linux
Show USB Devices Event History Using Usbrip In Linux

Show USB Devices Event History Using Usbrip In Linux

By sk
1620 Views

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.

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:

  1. Connected (date & time)
  2. Host
  3. VID (vendor ID)
  4. PID (product ID)
  5. Product
  6. Manufacturer
  7. Serial Number
  8. Port
  9. 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
Show USB devices event history using Usbrip
Show USB devices event history using Usbrip

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
Show external USB devices event history
Show external USB devices event history

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
Show certain USB device events using usbrip
Show certain USB device events using usbrip

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
View event history of specific USB device
View event history of specific USB device

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:

Leave a Comment

* By using this form you agree with the storage and handling of your data by this website.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Accept Read More