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…
Related tools
- mat2 (100%)
- Metadata Cleaner (100%)
- Bless (50%)
- JStillery (50%)
- JS Beautifier (50%)
- Detect It Easy (RANDOM - 50%)
Comments are Closed