Usbrip (derived from “USB Ripper”, not “USB R.I.P.” astonished) 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.
It 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/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
- 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
- *when installed with
-sflag* create crypted storages (7zip archives) to automatically backup and accumulate USB events with the help of
- search additional details about a specific USB device based on its VID and/or PID.
usbrip is available for download and installation at PyPI:
$ pip3 install usbrip
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 git clone:
~$ git clone https://github.com/snovvcrash/usbrip.git usbrip && cd usbrip ~/usbrip$
usbrip works with non-modified structure of system log files only, so, unfortunately, it won’t be able to parse USB history if you change the format of syslogs (with
rsyslog, for example). That’s why the timestamps of “Connected” and “Disconnected” fields don’t have the year, by the way. Keep that in mind.
- python3.6 (or newer) interpreter
- p7zip-full (used by
~$ sudo apt install python3-venv p7zip-full -y
usbrip makes use of the following external modules:
To resolve Python dependencies manually (it’s not necessary actually because
setup.py can automate the process, see Installation) create a virtual environment (optional) and run
pip from within:
~/usbrip$ python3 -m venv venv && source venv/bin/activate (venv) ~/usbrip$ pip install -r requirements.txt
Or let the
pipenv one-liner do all the dirty work for you:
~/usbrip$ pipenv install && pipenv shell
After that you can run usbrip portably:
(venv) ~/usbrip$ python -m usbrip -h Or (venv) ~/usbrip$ python __main__.py -h
There are two ways to install usbrip into the system:
pip or setup.py
First of all, usbrip is pip installable. This means that after git cloning the repo you can simply fire up the pip installation process and after that run usbrip from anywhere in your terminal like so:
~/usbrip$ python3 -m venv venv && source venv/bin/activate (venv) ~/usbrip$ pip install . (venv) ~/usbrip$ usbrip -h
Or if you want to resolve Python dependencies locally (without bothering PyPI), use
~/usbrip$ python3 -m venv venv && source venv/bin/activate (venv) ~/usbrip$ python setup.py install (venv) ~/usbrip$ usbrip -h
Note: you’d likely want to run the installation process while the Python virtual environment is active (like it is shown above).
Secondly, usbrip can also be installed into the system with the
When using the
./installers/install.sh some extra features become available:
- the virtual environment is created automatically;
storagemodule becomes available: you can set a crontab job to backup USB events on a schedule (the example of crontab jobs can be found in
Warning: if you are using the crontab scheduling, you want to configure the cron job with
sudo crontab -e in order to force the
storage update submodule run as root as well as protect the passwords of the USB event storages. The storage passwords are kept in
./installers/uninstall.sh script removes all the installation artifacts from your system.
To install usbrip use:
~/usbrip$ chmod +x ./installers/install.sh ~/usbrip$ sudo -H ./installers/install.sh [-l/–local] [-s/–storages] ~/usbrip$ cd ~$ usbrip -h
-lswitch is enabled, Python dependencies are resolved from local .tar packages (
./3rdPartyTools/) instead of PyPI.
-sswitch is enabled, not only the usbrip project is installed, but also the list of trusted USB devices, history and violations storages are created.
Note: when using
-s option during installation, make sure that system logs do contain at least one external USB device entry. It is a necessary condition for usbrip to successfully create the list of trusted devices (and as a result, successfully create the violations storage).
After the installation completes, feel free to remove the usbrip folder.
When installed, the usbrip uses the following paths:
/opt/usbrip/— project’s main directory;
/var/opt/usbrip/usbrip.ini— usbrip configuration file: keeps passwords for 7zip storages;
/var/opt/usbrip/storage/— USB event storages:
violations.7z(created during the installation process);
/var/opt/usbrip/log/— usbrip logs (recommended to log usbrip activity when using crontab, see
/var/opt/usbrip/trusted/— list of trusted USB devices (created during the installation process);
/usr/local/bin/usbrip— symlink to the
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
To uninstall usbrip use:
~/usbrip$ chmod +x ./installers/uninstall.sh ~/usbrip$ sudo ./installers/uninstall.sh [-a/–all]
-aswitch is enabled, not only the usbrip project directory is deleted, but also all the storages and usbrip logs are deleted too.
And don’t forget to remove the cron job.
Powered by Froala Editor