Home Unlabelled Usbrip - Uncomplicated Ascendancy Business Forensics Tool For Tracking Usb Device Artifacts (History Of Usb Events) On Gnu/Linux

Usbrip - Uncomplicated Ascendancy Business Forensics Tool For Tracking Usb Device Artifacts (History Of Usb Events) On Gnu/Linux

By
Saturday, May 04, 2013
Read
Add Comment

usbrip (derived from "USB Ripper", non "USB R.I.P.") is an opened upwardly source forensics tool amongst CLI interface that lets you lot driblet dead along runway of USB device artifacts (aka USB trial history, "Connected" in addition to "Disconnected" events) on Linux machines.

Description
usbrip is a modest slice of software written inwards pure Python 3 (using approximately external modules though, run into Dependencies/PIP) which parses Linux log files (/var/log/syslog* or /var/log/messages* depending on the distro) for constructing USB trial history tables. Such tables may incorporate the next columns: "Connected" (date & time), "User", "VID" (vendor ID), "PID" (product ID), "Product", "Manufacturer", "Serial Number", "Port" in addition to "Disconnected" (date & time).
Besides, it also can:
  • export gathered information equally a JSON dump (and opened upwardly such dumps, of course);
  • generate a listing of authorized (trusted) USB devices equally a JSON (call it auth.json);
  • search for "violation events" based on the auth.json: present (or generate approximately other JSON with) USB devices that practise look inwards history in addition to practise NOT look inwards the auth.json;
  • *when installed amongst -s flag* create crypted storages (7zip archives) to automatically backup in addition to accumulate USB events amongst the assistance of crontab scheduler;
  • search additional details virtually a specific USB device based on its VID and/or PID.

Quick Start
usbrip is available for download in addition to installation at PyPI:
$ pip3 install usbrip

Screenshots



Git Clone
For simplicity, lets handgrip that all the commands where /usbrip$ prefix is appeared are executed inwards the /usbrip directory which is created equally a trial of git clone:
 $ git clone https://github.com/snovvcrash/usbrip.git usbrip && cd usbrip  /usbrip$

Dependencies
usbrip industrial plant amongst non-modified construction of organisation log files only, so, unfortunately, it won't last able to parse USB history if you lot modify the format of syslogs (with syslog-ng or rsyslog, for example). That's why the timestamps of "Connected" in addition to "Disconnected" fields don't receive got the year, yesteryear the way. Keep that inwards mind.

DEB Packages
  • python3.6 (or newer) interpreter
  • python3-venv
  • p7zip-full (used yesteryear storages module)
 $ sudo apt install -y python3-venv p7zip-full

PIP Packages
usbrip makes role of the next external modules:

Portable
To resolve Python dependencies manually (it's non necessary genuinely because pip or setup.py tin automate the process, run into Installation) create a virtual environment (optional) in addition to run pip from within:
 /usbrip$ python3 -m venv venv && source venv/bin/activate (venv)  /usbrip$ pip install -r requirements.txt
Or permit the pipenv one-liner practise all the muddied run for you:
 /usbrip$ pipenv install && pipenv shell
After that you lot tin run usbrip portably:
(venv)  /usbrip$ python -m usbrip -h Or (venv)  /usbrip$ python __main__.py -h

Installation
There are 2 ways to install usbrip into the system: pip or setup.py.

pip or setup.py
First of all, usbrip is pip installable. This agency that later git cloning the repo you lot tin but burn upwardly the pip installation procedure in addition to later that run usbrip from anywhere inwards your final similar so:
 /usbrip$ python3 -m venv venv && source venv/bin/activate (venv)  /usbrip$ pip install .  (venv)  /usbrip$ usbrip -h
Or if you lot desire to resolve Python dependencies locally (without bothering PyPI), role setup.py:
 /usbrip$ python3 -m venv venv && source venv/bin/activate (venv)  /usbrip$ python setup.py install  (venv)  /usbrip$ usbrip -h
Note: you'd probable desire to run the installation procedure spell the Python virtual surround is active (like it is shown above).

install.sh
Secondly, usbrip tin also last installed into the organisation amongst the ./installers/install.sh script.
When using the ./installers/install.sh approximately extra features driblet dead available:
  • the virtual surround is created automatically;
  • the storage module becomes available: you lot tin laid a crontab chore to backup USB events on a schedule (the instance of crontab jobs tin last establish inwards usbrip/cron/usbrip.cron).
Warning: if you lot are using the crontab scheduling, you lot desire to configure the cron chore amongst sudo crontab -e inwards lodge to strength the storage update submodule run equally root equally good equally protect the passwords of the USB trial storages. The storage passwords are kept inwards /var/opt/usbrip/usbrip.ini.
The ./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
  • When -l switch is enabled, Python dependencies are resolved from local .tar packages (./3rdPartyTools/) instead of PyPI.
  • When -s switch is enabled, non exclusively the usbrip projection is installed, but also the listing of trusted USB devices, history in addition to violations storages are created.
Note: when using -s selection during installation, brand certain that organisation logs practise incorporate at to the lowest degree i external USB device entry. It is a necessary status for usbrip to successfully create the listing of trusted devices (and equally a result, successfully create the violations storage).
After the installation completes, experience gratis to take away the usbrip folder.

Paths
When installed, the usbrip uses the next paths:
  • /opt/usbrip/ — project's top dog directory;
  • /var/opt/usbrip/usbrip.ini — usbrip configuration file: keeps passwords for 7zip storages;
  • /var/opt/usbrip/storage/ — USB trial storages: history.7z in addition to violations.7z (created during the installation process);
  • /var/opt/usbrip/log/ — usbrip logs (recommended to log usbrip activity when using crontab, run into usbrip/cron/usbrip.cron);
  • /var/opt/usbrip/trusted/ — listing of trusted USB devices (created during the installation process);
  • /usr/local/bin/usbrip — symlink to the /opt/usbrip/venv/bin/usbrip script.

cron
Cron jobs tin last laid equally follows:
 /usbrip$ sudo crontab -l > tmpcron && echo "" >> tmpcron  /usbrip$ truthful cat usbrip/cron/usbrip.cron | tee -a tmpcron  /usbrip$ sudo crontab tmpcron  /usbrip$ rm tmpcron

uninstall.sh
To uninstall usbrip use:
 /usbrip$ chmod +x ./installers/uninstall.sh  /usbrip$ sudo ./installers/uninstall.sh [-a/--all]
  • When -a switch is enabled, non exclusively the usbrip projection directory is deleted, but also all the storages in addition to usbrip logs are deleted too.
And don't forget to take away the cron job.

Usage

Synopsis
# ---------- BANNER ----------  $ usbrip banner Get usbrip banner.  # ---------- EVENTS ----------  $ usbrip events history [-t | -l] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]] [--serial  [ ...]] [--port  [ ...]] [-c  [ ...]] [-f  [ ...]] [-q] [--debug] Get USB trial history.  $ usbrip events opened upwardly  [-t | -l] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [    ...]] [--serial  [ ...]] [--port  [ ...]] [-c  [ ...]] [-f  [ ...]] [-q] [--debug] Open USB trial dump.  $ usbrip events gen_auth  [-a  [ ...]] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]] [--serial  [ ...]] [--port  [ ...]] [-f  [ ...]] [-q] [--debug] Generate a listing of trusted (authorized) USB devices.  $ usbrip events violations  [-a  [ ...]] [-t | -l] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]] [--serial  [ ...]] [--port  [ ...]] [-c  [ ...]] [-f  [ ...]] [-q] [--debug] Get USB violation events based on the listing of trusted devices.  # ---------- STORAGE ----------  $ usbrip storage listing  [-q] [--debug] List contents of the selected storage (7zip archive). STORAGE_TYPE is "history" or "violations".  $ usbrip storage opened upwardly  [-t | -l] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]]    [--serial  [ ...]] [--port  [ ...]] [-c  [ ...]] [-q] [--debug] Open selected storage (7zip archive). Behaves similary to the EVENTS OPEN submodule.  $ usbrip storage update  [-a  [ ...]] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]] [--serial  [ ...]] [--port  [ ...]] [--lvl ] [-q] [--debug] Update storage — add together USB events to the existing storage (7zip archive). COMPRESSION_LEVEL is a publish inwards [0..9].  $ usbrip storage create  [-a  [ ...]] [-e] [-n ] [-d  [ ...]] [--user  [ ...]] [--vid  [ ...]] [--pid  [ ...]] [--prod  [ ...]] [--manufact  [ ...]] [--serial  [ ...]] [--port  [ ...]] [--lvl ] [-q] [--debug] Create storage — create 7zip archive in addition to add together USB events to it according to the selected options.  $ usbrip storage passwd  [--lvl ] [-q] [--debug] Change password of the existing storage.  # ---------- IDs ----------  $ usbrip ids search [--vid ] [--pid ] [--offline] [-q] [--debug] Get extra details virtually a specific USB device yesteryear its  and/or  from the USB ID database.  $ usbrip ids download [-q] [--debug] Update (download) the USB ID database.

Help
To larn a listing of module names use:
$ usbrip -h
To larn a listing of submodule names for a specific module use:
$ usbrip  -h
To larn a listing of all switches for a specific submodule use:
$ usbrip   -h

Examples
  • Show the trial history of all USB devices, supressing banner output, information messages in addition to user interaction (-q, --quiet), represented equally a listing (-l, --list) amongst latest 100 entries (-n NUMBER, --number NUMBER):
    $ usbrip events history -ql -n 100
  • Show the trial history of the external USB devices (-e, --external, which were actually disconnected) represented equally a tabular array (-t, --table) containing "Connected", "VID", "PID", "Disconnected" in addition to "Serial Number" columns (-c COLUMN [COLUMN], --column COLUMN [COLUMN]) filtered yesteryear appointment (-d DATE [DATE ...], --date DATE [DATE ...]) amongst logs taken from the outer files (-f FILE [FILE ...], --file FILE [FILE ...]):
    $ usbrip events history -et -c conn vid pid disconn series -d "Dec  9" "Dec 10" -f /var/log/syslog.1 /var/log/syslog.2.gz
  • Build the trial history of all USB devices in addition to redirect the output to a file for farther analysis. When the output flow is NOT final stdout (| or > for example) at that topographic point would last no ANSI escape characters (color) inwards the output then experience gratis to role it that way. Also detect that usbrip uses approximately UNICODE symbols then it would last dainty to convert the resulting file to UTF-8 encoding (with encov for example) equally good equally modify newline characters to Windows manner for portability (with awk for example):
    usbrip history events -t | awk '{ sub("$", "\r"); impress }' > usbrip.out && enconv -x UTF8 usbrip.out
    Remark: you lot tin e'er larn rid of the escape characters yesteryear yourself fifty-fifty if you lot receive got already got the output to stdout. To practise that precisely re-create the output information to usbrip.out in addition to add together i to a greater extent than awk instruction:
    awk '{ sub("$", "\r"); gsub("\\x1B\\[[0-?]*[ -/]*[@- ]", ""); impress }' usbrip.out && enconv -x UTF8 usbrip.out
  • Generate a listing of trusted USB devices equally a JSON-file (trusted/auth.json) amongst "VID" in addition to "PID" attributes containing the start three devices connected on September 26:
    $ usbrip events gen_auth trusted/auth.json -a vid pid -n 3 -d "Sep 26"
  • Search the trial history of the external USB devices for violations based on the listing of trusted USB devices (trusted/auth.json) yesteryear "PID" attribute, throttle resulting events to those which receive got "Bob" equally a user, "EvilUSBManufacturer" equally a manufacturer, "1234567890" equally a series publish in addition to correspond the output equally a tabular array amongst "Connected", "VID" in addition to "PID" columns:
    $ usbrip events violations trusted/auth.json -a pid -et --user Bob --manufact EvilUSBManufacturer --serial 1234567890 -c conn vid pid
  • Search for details virtually a specific USB device yesteryear its VID (--vid VID) in addition to PID (--pid PID):
    $ usbrip ids search --vid 0781 --pid 5580
  • Download the latest version of usb_ids/usb.ids database (the source is here):
    $ usbrip ids download

Credits & References


Tags :

Created By Nexus · Powered by Blogger
© All Rights Reserved

Terms Of Service · Privacy Policy · Disclaimer · Contact Us · About Us