Linux fornsica in the face of tracking USB device connection history

As part of the immersion in one of the disciplines (in the process of training in the field of computer security), I worked on one entertaining project that I would not want to just bury in the depths of the Univer folder on an external hard drive.

This project is called usbrip and is a small console open-source utility for Linux-forsensics, namely, to work with the history of connecting USB-devices. The program is written in pure Python 3 (using some third-party modules) and does not require dependencies other than Python 3.x interpreter and a couple of requirements.txt lines that can be resolved in one line with pip.

In this post I will describe some of the features of this software and leave a brief manual with a link to the download source.
')
Shot! (... in the sense of Cut!)

Note. The functionality described in the article is relevant for the first version of the utility. For the latest version with a lot of new buns, I suggest going to the repository .

Screenshots

Getting the connection history of removable USB devices:


Search for additional information about the USB device by model identifier (PID):

Description

As you know, GNU / Linux-based operating systems are very sensitive to logging various kinds of events, and connecting / disconnecting USB devices is no exception. In conjunction with one of the points of the UNIX philosophy about “text streams as universal interfaces”, information about the artifacts of such events (with varying degrees of detail) depending on the distribution can be found in one or more of the following text files:

• /var/log/kern.log* ;
• /var/log/syslog* ;
• /var/log/messages* ;
• /var/log/dmesg* ;
• /var/log/daemon.log* .

FORENSIC-PROOF even shows us such a picture on this subject (a bit incomplete, but it doesn't matter):



For its work, usbrip finds universal for all Linux builds based on Debian (Ubuntu, Linux Mint, etc.) and RPM (CentOS, Fedora, openSUSE, etc.), log files, namely: /var/log/syslog* or /var/log/messages* , parses them in search of the necessary information and puts the found traces of USB device connections into beautiful tablets (or lists - as you like).

Also, usbrip can:

• create lists of authorized (trusted) devices in the form of JSON files;
• search for “violating events” based on the list of trusted devices: such events (USB connection / disconnection), in which USB devices that were not marked as trusted participated;
• Search for additional information about the USB device by its VID (Vendor ID) and / or PID (Product ID).

reference

Get a list of available modules:

 $ python3 usbrip.py -h 

Get a list of available submodules for a specific module:

 $ python3 usbrip.py <> -h 

Get a list of available options for a particular sub-module:

 $ python3 usbrip.py <> <> -h 

Syntax

 $ python3 usbrip.py banner     . $ python3 usbrip.py events history [-q] [-t | -l] [-e] [-n _] [-d  [ ...]] [-c  [ ...]] [-f _ [_ ...]]   USB-. $ python3 usbrip.py events gen_auth <_.JSON> [-a  [ ...]] [-q] [-e] [-n _] [-d  [ ...]] [-f _ [_ ...]]    () USB-. $ python3 usbrip.py events violations <_.JSON> [-a  [ ...]] [-q] [-t | -l] [-e] [-n _] [-d  [ ...]] [-c  [ ...]] [-f _ [_ ...]]  "-"     . $ python3 usbrip.py ids search [-q] [--vid VID] [--pid PID] [--offline]        VID / PID    . $ python3 usbrip.py ids download [-q]  ()     USB-. 

Options

 ,   'events history', 'events gen_auth', 'events violations', 'ids search', 'ids download': -q, --quiet   ,  () ,         ##################################################################################### ,   'events history', 'events gen_auth', 'events violations': -e, --external    USB- (     ) -n _, --number _     ,    -d  [ ...], --date  [ ...]  ,         -f _ [_ ...], --file _ [_ ...]  - (  ,       -  : /var/log/syslog*  /var/log/messages*     ) ##################################################################################### ,   'events history', 'events violations': -t, --table      (         ,       ;    -t       ) -l, --list      -c  [ ...], --column  [ ...]  ,       (        );  : "conn", "user", "vid", "pid", "prod", "manufact", "serial", "port", "disconn". ##################################################################################### ,   'events gen_auth', 'events violations': -a  [ ...], --attribute  [ ...]  ,         (    "-"    'events violations');  : "vid", "pid", "prod", "manufact", "serial". ##################################################################################### ,   'ids search', 'ids download': --vid VID vendor ID    USB- ( 4  ) --vid PID product ID    USB- ( 4  ) --offline  ,     USB-          ()  

Examples of using

Show the connection history of all USB devices, omitting the banner, informational (green) messages, as well as not asking questions in the course of execution ( -q, --quite ), forming a list output ( -l, --list ), including in the last 100 events found ( -n _, --number _ ):

 $ python3 usbrip.py events history -ql -n 100 

Display the connection history of removable USB devices ( -e, --external ), forming a table-like output with fields (columns) “Connected”, “VID”, “PID”, “Disconnected” and “Serial Number” ( -c [ ...], --column [ ...] ), filtering the search by date ( -d [ ...], --date [ ...] ), taking the information from external log files ( -f _ [_ ...], --file _ [_ ...] ):

 $ python3 usbrip.py events history -et -c conn vid pid disconn serial -d "Dec 9" "Dec 10" -f /var/log/syslog.1 /var/log/syslog.2.gz 

Build a table of the connection history of all USB devices and redirect the output to a file for further analysis. In the event that the output stream is not a standard stdout ( "|" or ">" for example), the output data will not contain a special. characters responsible for the font color in the terminal, so the text file will not be littered with unreadable characters. It should also be noted that usbrip uses some UNICODE constants, so it would be nice to immediately convert the encoding of the created file to UTF-8 for their correct display (for example, using encov ), and also use newline characters in Windows-style for better portability ( for example using awk ):

 $ python3 usbrip.py history events -t | awk '{ sub("$", "\r"); print }' > usbrip.txt && enconv -x UTF8 usbrip.txt 

Note: get rid of spec. characters responsible for color can be used even if the output has already been sent to stdout. To do this, copy the data to a new usbrip.txt file and add another awk instruction:

 $ awk '{ sub("$", "\r"); gsub("\\x1B\\[[0-?]*[ -/]*[@-~]", ""); print }' usbrip.txt && enconv -x UTF8 usbrip.txt 

Create a list of trusted devices in the form of a JSON file ( trusted/auth.json ), containing the “VID” and “PID” fields of the first three devices connected on September 26th:

 $ python3 usbrip.py events gen_auth trusted/auth.json -a vid pid -n 3 -d "Sep 26" 

Find the “intruder events” among the connection history of removable USB devices based on the list of trusted devices ( trusted/auth.json ) across the “PID” field and form the output as a table with the fields “Connected”, “VID” and “PID”:

 $ python3 usbrip.py events violations trusted/auth.json -a pid -et -c conn vid pid 

Find additional information about the USB device based on its VID and PID:

 $ python3 usbrip.py ids search --vid 0781 --pid 5580 

Download / update the database of identifiers of USB devices (source here ):

 $ python3 usbrip.py ids download 

Links and Postscript

You can pick up the utility from GitHub , all dependencies for running and correct work are listed in the requirements.txt .

Thank you for attention!

PS Yes, the banner and informational style is inspired by the sqlmap project (* ^. ^ *)

UPD 13.06.2018. There was an investigation of the real (?) Case with the participation of my utility from a person with Codeby (himself in shock, to be honest).