You are here: Home » Digital forensics » usbrip

usbrip

usbrip Description

usbrip is an open source forensics tool with CLI interface that lets you keep track of USB device artifacts (aka USB event history, "Connected" and "Disconnected" events) on Linux machines.

usbrip is a small piece of software written in pure Python 3 (using some external modules though, see Dependencies/PIP) which parses Linux log files (/var/log/syslog* or /var/log/messages* depending on the distro) for constructing USB event history tables. Such tables may contain the following columns: "Connected" (date & time), "User", "VID" (vendor ID), "PID" (product ID), "Product", "Manufacturer", "Serial Number", "Port" and "Disconnected" (date & time).

Besides, it also can:

  • export gathered information as a JSON dump (and open such dumps, of course);
  • generate a list of authorized (trusted) USB devices as a JSON (call it auth.json);
  • search for "violation events" based on the auth.json: show (or generate another JSON with) USB devices that do appear in history and do NOT appear in the auth.json;
  • create crypted storages (7zip archives) to automatically backup and accumulate USB events with the help of crontab scheduler;
  • search additional details about a specific USB device based on its VID and/or PID.

Homepage: https://github.com/snovvcrash/usbrip

Author: Sam Freeside

License: GPLv3

usbrip Help

Usage:

usbrip [-h] {banner,events,storage,ids} ...

Options:

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

events Help

Usage:

usbrip events [-h] {history,open,gen_auth,violations} ...

Options:

positional arguments:
  {history,open,gen_auth,violations}
    history             show USB event history
    open                open USB event dump
    gen_auth            generate authorized device list (JSON)
    violations          search USB event history for violations (show USB
                        devices that do appear in history and do NOT appear in
                        authorized device list (JSON))

history Subcommand Help

Usage:

usbrip events history [-h] [--debug] [-q] [-c COLUMN [COLUMN ...]] [-e]
                             [-n NUMBER] [-d DATE [DATE ...]]
                             [--user USER [USER ...]] [--vid VID [VID ...]]
                             [--pid PID [PID ...]] [--prod PROD [PROD ...]]
                             [--manufact MANUFACT [MANUFACT ...]]
                             [--serial SERIAL [SERIAL ...]]
                             [--port PORT [PORT ...]] [-t | -l]
                             [-f FILE [FILE ...]]

Options:

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  -c COLUMN [COLUMN ...], --column COLUMN [COLUMN ...]
                        columns to show (options: "conn", "user", "vid",
                        "pid", "prod", "manufact", "serial", "port",
                        "disconn")
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -t, --table           represent as table (not list)
  -l, --list            represent as list (not table)
  -f FILE [FILE ...], --file FILE [FILE ...]
                        obtain log from the outer files

open Subcommand Help

Usage:

usbrip events open [-h] [--debug] [-q] [-c COLUMN [COLUMN ...]] [-e]
                          [-n NUMBER] [-d DATE [DATE ...]]
                          [--user USER [USER ...]] [--vid VID [VID ...]]
                          [--pid PID [PID ...]] [--prod PROD [PROD ...]]
                          [--manufact MANUFACT [MANUFACT ...]]
                          [--serial SERIAL [SERIAL ...]]
                          [--port PORT [PORT ...]] [-t | -l]
                          [-f FILE [FILE ...]]
                          input

Options:

positional arguments:
  input                 input path for the event dump (JSON)

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  -c COLUMN [COLUMN ...], --column COLUMN [COLUMN ...]
                        columns to show (options: "conn", "user", "vid",
                        "pid", "prod", "manufact", "serial", "port",
                        "disconn")
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -t, --table           represent as table (not list)
  -l, --list            represent as list (not table)
  -f FILE [FILE ...], --file FILE [FILE ...]
                        obtain log from the outer files

gen_auth Subcommand Help

Usage:

usbrip events gen_auth [-h] [--debug] [-q] [-e] [-n NUMBER]
                              [-d DATE [DATE ...]] [--user USER [USER ...]]
                              [--vid VID [VID ...]] [--pid PID [PID ...]]
                              [--prod PROD [PROD ...]]
                              [--manufact MANUFACT [MANUFACT ...]]
                              [--serial SERIAL [SERIAL ...]]
                              [--port PORT [PORT ...]] [-f FILE [FILE ...]]
                              [-a ATTRIBUTE [ATTRIBUTE ...]]
                              output

Options:

positional arguments:
  output                output path for the list of authorized devices (JSON)

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -f FILE [FILE ...], --file FILE [FILE ...]
                        obtain log from the outer files
  -a ATTRIBUTE [ATTRIBUTE ...], --attribute ATTRIBUTE [ATTRIBUTE ...]
                        attributes to include in authorized device list
                        (options: "vid", "pid", "prod", "manufact", "serial")

violations Subcommand Help

Usage:

usbrip events violations [-h] [--debug] [-q] [-c COLUMN [COLUMN ...]]
                                [-e] [-n NUMBER] [-d DATE [DATE ...]]
                                [--user USER [USER ...]] [--vid VID [VID ...]]
                                [--pid PID [PID ...]] [--prod PROD [PROD ...]]
                                [--manufact MANUFACT [MANUFACT ...]]
                                [--serial SERIAL [SERIAL ...]]
                                [--port PORT [PORT ...]] [-t | -l]
                                [-f FILE [FILE ...]]
                                [-a ATTRIBUTE [ATTRIBUTE ...]]
                                input

Options:

positional arguments:
  input                 input path for the list of authorized devices (JSON)

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  -c COLUMN [COLUMN ...], --column COLUMN [COLUMN ...]
                        columns to show (options: "conn", "user", "vid",
                        "pid", "prod", "manufact", "serial", "port",
                        "disconn")
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -t, --table           represent as table (not list)
  -l, --list            represent as list (not table)
  -f FILE [FILE ...], --file FILE [FILE ...]
                        obtain log from the outer files
  -a ATTRIBUTE [ATTRIBUTE ...], --attribute ATTRIBUTE [ATTRIBUTE ...]
                        attributes to look through when searching for USB
                        violation events (options: "vid", "pid", "prod",
                        "manufact", "serial")

storage Help

Usage:

usbrip storage [-h] {list,open,update,create,passwd} ...

Options:

positional arguments:
  {list,open,update,create,passwd}
    list                list storage contents
    open                open storage contents
    update              update current storage
    create              create initial history/violations storage; storage
                        path is "/var/opt/usbrip/storage"
    passwd              change storage password

optional arguments:
  -h, --help            show this help message and exit

list Subcommand Help

Usage:

sbrip storage list [-h] [--debug] [-q] storage_type

Options:

positional arguments:
  storage_type  storage type (options: "history", "violations")

optional arguments:
  -h, --help    show this help message and exit
  --debug       DEBUG mode
  -q, --quiet   supress banner, some info messages, time capture and user
                iteraction

open Subcommand Help

Usage:

usbrip storage open [-h] [--debug] [-q] [-c COLUMN [COLUMN ...]] [-e]
                           [-n NUMBER] [-d DATE [DATE ...]]
                           [--user USER [USER ...]] [--vid VID [VID ...]]
                           [--pid PID [PID ...]] [--prod PROD [PROD ...]]
                           [--manufact MANUFACT [MANUFACT ...]]
                           [--serial SERIAL [SERIAL ...]]
                           [--port PORT [PORT ...]] [-t | -l]
                           storage_type

Options:

positional arguments:
  storage_type          storage type (options: "history", "violations")

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  -c COLUMN [COLUMN ...], --column COLUMN [COLUMN ...]
                        columns to show (options: "conn", "user", "vid",
                        "pid", "prod", "manufact", "serial", "port",
                        "disconn")
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -t, --table           represent as table (not list)
  -l, --list            represent as list (not table)

update Subcommand Help

Usage:

usbrip storage update [-h] [--debug] [-q] [--lvl LVL] [-e] [-n NUMBER]
                             [-d DATE [DATE ...]] [--user USER [USER ...]]
                             [--vid VID [VID ...]] [--pid PID [PID ...]]
                             [--prod PROD [PROD ...]]
                             [--manufact MANUFACT [MANUFACT ...]]
                             [--serial SERIAL [SERIAL ...]]
                             [--port PORT [PORT ...]]
                             [-a ATTRIBUTE [ATTRIBUTE ...]] [-i INPUT]
                             storage_type

Options:

positional arguments:
  storage_type          storage type (options: "history", "violations")

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  --lvl LVL             compression level (from 0 to 9, default is 0 = no
                        compression)
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -a ATTRIBUTE [ATTRIBUTE ...], --attribute ATTRIBUTE [ATTRIBUTE ...]
                        attributes to look through when searching for USB
                        violation events (options: "vid", "pid", "prod",
                        "manufact", "serial")
  -i INPUT, --input INPUT
                        input path for the list of authorized devices (JSON)

create Subcommand Help

Usage:

usbrip storage create [-h] [--debug] [-q] [--lvl LVL] [-e] [-n NUMBER]
                             [-d DATE [DATE ...]] [--user USER [USER ...]]
                             [--vid VID [VID ...]] [--pid PID [PID ...]]
                             [--prod PROD [PROD ...]]
                             [--manufact MANUFACT [MANUFACT ...]]
                             [--serial SERIAL [SERIAL ...]]
                             [--port PORT [PORT ...]]
                             [-a ATTRIBUTE [ATTRIBUTE ...]] [-i INPUT]
                             storage_type

Options:

positional arguments:
  storage_type          storage type (options: "history", "violations")

optional arguments:
  -h, --help            show this help message and exit
  --debug               DEBUG mode
  -q, --quiet           supress banner, some info messages, time capture and
                        user iteraction
  --lvl LVL             compression level (from 0 to 9, default is 0 = no
                        compression)
  -e, --external        show only those devices which have "disconnect" date
  -n NUMBER, --number NUMBER
                        number of events to show
  -d DATE [DATE ...], --date DATE [DATE ...]
                        filter by dates
  --user USER [USER ...]
                        search by users
  --vid VID [VID ...]   search by VIDs
  --pid PID [PID ...]   search by PIDs
  --prod PROD [PROD ...]
                        search by products
  --manufact MANUFACT [MANUFACT ...]
                        search by manufacturers
  --serial SERIAL [SERIAL ...]
                        search by serial numbers
  --port PORT [PORT ...]
                        search by ports
  -a ATTRIBUTE [ATTRIBUTE ...], --attribute ATTRIBUTE [ATTRIBUTE ...]
                        attributes to look through when searching for USB
                        violation events (options: "vid", "pid", "prod",
                        "manufact", "serial")
  -i INPUT, --input INPUT
                        input path for the list of authorized devices (JSON)

passwd Subcommand Help

Usage:

usbrip storage passwd [-h] [--debug] [-q] [--lvl LVL] storage_type

Options:

positional arguments:
  storage_type  storage type (options: "history", "violations")

optional arguments:
  -h, --help    show this help message and exit
  --debug       DEBUG mode
  -q, --quiet   supress banner, some info messages, time capture and user
                iteraction
  --lvl LVL     compression level (from 0 to 9, default is 0 = no compression)

ids Help

Usage:

usbrip ids [-h] {search,download} ...

Options:

positional arguments:
  {search,download}
    search           search by VID and/or PID; ids database path is
                     "/opt/usbrip/venv/lib/python3.7/site-
                     packages/usbrip/usb_ids/usb.ids"
    download         download/update database;ids database path is
                     "/opt/usbrip/venv/lib/python3.7/site-
                     packages/usbrip/usb_ids/usb.ids"

optional arguments:
  -h, --help         show this help message and exit

search Subcommand Help

Usage:

usbrip ids search [-h] [--debug] [-q] [--vid VID] [--pid PID]
                         [--offline]

Options:

optional arguments:
  -h, --help   show this help message and exit
  --debug      DEBUG mode
  -q, --quiet  supress banner, some info messages, time capture and user
               iteraction
  --vid VID    vendor ID
  --pid PID    product ID
  --offline    offline mode (no database download/update)

download Subcommand Help

Usage:

usbrip ids download [-h] [--debug] [-q]

Options:

optional arguments:
  -h, --help   show this help message and exit
  --debug      DEBUG mode
  -q, --quiet  supress banner, some info messages, time capture and user
               iteraction

Usage Example usbrip

Show the history of plugged USB devices to this Linux system:

usbrip events history

How to install usbrip

Installation on Kali Linux

sudo apt install python3-venv p7zip-full -y
git clone https://github.com/snovvcrash/usbrip
cd usbrip/
chmod +x ./installers/install.sh
sudo -H ./installers/install.sh -s
cd
usbrip -h

System Log Structure

usbrip (>= 2.1.4.post1) works with modified structure of system log files to provide high precision timestamps, so make sure to enable "%Y-%m-%dT%H:%M:%S.%f%z" (ex. "2019-08-09T06:15:49.655261-04:00") time format for both /var/log/syslog* and /var/log/messages* before running the software.

It can be done by setting the RSYSLOG_FileFormat format if you are using rsyslog, for example.

Comment out the following line in /etc/rsyslog.conf:

$ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat

Add custom .conf file for usbrip:

echo '$ActionFileDefaultTemplate RSYSLOG_FileFormat' | sudo tee /etc/rsyslog.d/usbrip.conf

Delete existing log files and restart the service:

sudo rm -f /var/log/syslog* /var/log/messages*
sudo systemctl restart rsyslog

Installation on Linux (Debian, Mint, Ubuntu)

sudo pip3 install usbrip

usbrip Screenshots

usbrip Tutorials

Coming soon…

  • Unique Post