search

snovvcrash / usbrip

Tracking history of USB events on GNU/Linux
https://habr.com/ru/post/352254/
GNU General Public License v3.0
1.15k stars 112 forks source link
forensics security usb-devices usb-events usb-history

readme

logo.png

version.svg python.svg license.svg blackarch.svg built-with-love.svg

usbrip (inherited from "USB Ripper", not "USB R.I.P.") is a simple forensics tool with command line interface that lets you keep track of USB device artifacts (i.e., USB event history) on Linux machines.

Table of Contents:

Description

usbrip is a small piece of software which analyzes Linux log data: journalctl output or contents of /var/log/syslog* (or /var/log/messages*) files. Based on the collected data usbrip can build USB event history tables with the following columns:

Besides, it also can:

Quick Start

Way 1. Install with pip:

~$ sudo -H python3 -m pip install -U usbrip
~$ usbrip -h

Way 2. Install bleeding-edge with install.sh (recommended, extra features available):

~$ sudo apt install python3-venv p7zip-full -y
~$ git clone https://github.com/snovvcrash/usbrip && cd usbrip
~/usbrip$ sudo -H installers/install.sh
~/usbrip$ cd
~$ usbrip -h

Showcase

showcase.png

Docker (*DEMO ONLY!*)

~$ docker run --rm -it snovvcrash/usbrip

System Log Structure

usbrip supports two types of timestamps to parse within system log files:

  1. Non-modified – standard syslog structure for GNU/Linux ("%b %d %H:%M:%S", ex. "Jan 1 00:00:00"). This type of timestamp does not provide the information about the year.
  2. Modified (recommended) – better syslog structure which provides high precision timestamps including years ("%Y-%m-%dT%H:%M:%S.%f%z", ex. "1970-01-01T00:00:00.000000-00:00").

If you do have journalctl installed, then there's nothing to worry about as it can convert timestamps on the fly. Otherwise, the desired syslog structure can be achieved by setting RSYSLOG_FileFormat format in rsyslog configuration.

  1. Comment out the following line in /etc/rsyslog.conf:
$ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat
  1. Add custom .conf file for usbrip:
~$ echo '$ActionFileDefaultTemplate RSYSLOG_FileFormat' | sudo tee /etc/rsyslog.d/usbrip.conf
  1. *optional* Delete existing log files:
~$ sudo rm -f /var/log/syslog* /var/log/messages*
  1. Restart the service:
~$ sudo systemctl restart rsyslog

Firstly, usbrip will check if there is a chance to dump system events using journalctl as the most portable option. If not – it will search for and parse /var/log/syslog* or /var/log/messages* system log files.

Dependencies

deb

pip

Manual installation

Git Clone

For simplicity, lets agree that all the commands where ~/usbrip$ prefix is appeared are executed in the ~/usbrip directory which is created as a result of a git clone:

~$ git clone https://github.com/snovvcrash/usbrip
~$ cd usbrip
~/usbrip$ pwd

install.sh

Besides installing with pip, usbrip can also be installed with custom installers/install.sh script.

When using install.sh some extra features become available:

:warning: Warning: if you are using cron scheduling, you want to configure the crontab with sudo crontab -e in order to force the storage update submodule run as root. The storage passwords are kept in /var/opt/usbrip/usbrip.ini and accessible by root only by default.

To install usbrip with install.sh use:

~/usbrip$ sudo -H installers/install.sh [-l/--local] [-s/--storages]
~/usbrip$ cd
~$ usbrip -h

After the installation completes feel free to remove the ~/usbrip directory.

Paths

When installed with install.sh, usbrip uses the following paths:

Cron

Cron jobs can be set as follows:

~/usbrip$ sudo crontab -l > tmpcron && echo "" >> tmpcron
~/usbrip$ cat usbrip/cron/usbrip.cron | tee -a tmpcron
~/usbrip$ sudo crontab tmpcron
~/usbrip$ rm tmpcron

uninstall.sh

The installers/uninstall.sh script removes usbrip and all the installation artifacts from your system.

To uninstall usbrip use:

~/usbrip$ sudo installers/uninstall.sh [-a/--all]

Don't forget to remove the cron job if you had set up one.

Usage

Synopsis

# ---------- BANNER ----------

~$ usbrip banner
Get usbrip banner.

# ---------- EVENTS ----------

~$ usbrip events history [-t | -l] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [-c <COLUMN> [<COLUMN> ...]] [-f <FILE> [<FILE> ...]] [-q] [--debug]
Get USB event history.

~$ usbrip events open <DUMP.JSON> [-t | -l] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [-c <COLUMN> [<COLUMN> ...]] [-q] [--debug]
Open USB event dump.

~$ sudo usbrip events genauth <OUT_AUTH.JSON> [-a <ATTRIBUTE> [<ATTRIBUTE> ...]] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [-f <FILE> [<FILE> ...]] [-q] [--debug]
Generate a list of trusted (authorized) USB devices.

~$ sudo usbrip events violations <IN_AUTH.JSON> [-a <ATTRIBUTE> [<ATTRIBUTE> ...]] [-t | -l] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [-c <COLUMN> [<COLUMN> ...]] [-f <FILE> [<FILE> ...]] [-q] [--debug]
Get USB violation events based on the list of trusted devices.

# ---------- STORAGE ----------

~$ sudo usbrip storage list <STORAGE_TYPE> [-q] [--debug]
List contents of the selected storage. STORAGE_TYPE is either "history" or "violations".

~$ sudo usbrip storage open <STORAGE_TYPE> [-t | -l] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [-c <COLUMN> [<COLUMN> ...]] [-q] [--debug]
Open selected storage. Behaves similarly to the EVENTS OPEN submodule.

~$ sudo usbrip storage update <STORAGE_TYPE> [IN_AUTH.JSON] [-a <ATTRIBUTE> [<ATTRIBUTE> ...]] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [--lvl <COMPRESSION_LEVEL>] [-q] [--debug]
Update storage -- add USB events to the existing storage. COMPRESSION_LEVEL is a number in [0..9].

~$ sudo usbrip storage create <STORAGE_TYPE> [IN_AUTH.JSON] [-a <ATTRIBUTE> [<ATTRIBUTE> ...]] [-e] [-n <NUMBER_OF_EVENTS>] [-d <DATE> [<DATE> ...]] [--host <HOST> [<HOST> ...]] [--vid <VID> [<VID> ...]] [--pid <PID> [<PID> ...]] [--prod <PROD> [<PROD> ...]] [--manufact <MANUFACT> [<MANUFACT> ...]] [--serial <SERIAL> [<SERIAL> ...]] [--port <PORT> [<PORT> ...]] [--lvl <COMPRESSION_LEVEL>] [-q] [--debug]
Create storage -- create 7-Zip archive and add USB events to it according to the selected options.

~$ sudo usbrip storage passwd <STORAGE_TYPE> [--lvl <COMPRESSION_LEVEL>] [-q] [--debug]
Change password of the existing storage.

# ---------- IDs ----------

~$ usbrip ids search [--vid <VID>] [--pid <PID>] [--offline] [-q] [--debug]
Get extra details about a specific USB device by its <VID> and/or <PID> from the USB ID database.

~$ usbrip ids download [-q] [--debug]
Update (download) the USB ID database.

Help

To get a list of module names use:

~$ usbrip -h

To get a list of submodule names for a specific module use:

~$ usbrip <MODULE> -h

To get a list of all switches for a specific submodule use:

~$ usbrip <MODULE> <SUBMODULE> -h

Examples

Credits & References

13cubed.jpg

Stargazers Chart

stargazers