This project provides a verification of connected USB devices, by using the Duo Auth API.
When a device is connected for the first time to the host, an action will be triggered based on the configuration and it will require to be confirmed with a Duo push request. If the device is not confirmed, or explicitly rejected, a second action (also configurable) will be triggered. The purpose of USB2fac is to orchestrate the described actions, while keeping track of all the connected USB devices. In the event of an incident, this information can be useful for the Security team.
For now, only OSX is supported.
USB2fac requires libusb, you can install it using brew:
$ brew install libusb
Then you need to install the python bindings, pyusb:
$ sudo pip install pyusb --pre
Finally you will need the python library requests. Install it using pip:
$ sudo pip install requests
Also, you will need the Duo Auth API and create an application, in order to use the 2-factor capabilities.
Provide your integration key, secret key and API hostname in the configuration file.
Usage: USB2fac.py [-h|--help] [ARGUMENT [PARAMETER]] [ARGUMENT [PARAMETER]] ..
Arguments:
-h, --help Shows this help message and exit.
-D, --find Discover devices connected and stores them as seen.
-R, --reset Reset all the rejected devices.
-l, --log FILE Log file for 2facUSB. Default is USB2fac.log
-C, --conn VALUE Paranoia level for the connect action triggered: 1 = log, 2 = lock, 3 = shutdown
-R, --action VALUE Paranoia level for the reject action triggered: 1 = log, 2 = lock, 3 = shutdown
-c, --config FILE File with Duo API access and configuration. Overrides all parameters. Default is None
-o, --file FILE JSON file to be used as storage for seen devices. Default is USB2fac.json
-b, --backup FILE JSON file with a backup of the trusted/seen USB devices. Default is USB2fac.bak
-r, --reject FILE JSON file to keep track of the rejected USB devices. Default is rejected.json
-p, --pid FILE File to keep track of the daemon PID. Default is USB2fac.pid
-u --user VALUE Username to use for the DUO integration and send the push request.
Examples:
USB2fac.py -D -o usb.json -b usb.bak
USB2fac.py -C 2 -R 1 -o usb.json -b usb.bak -r reject.json
We ❤️ contributions. Found a bug or looking for a new feature? Open an issue and we'll respond as fast as we can. Or, better yet, implement it yourself and open a pull request! We ask that you include tests to show the bug was fixed or the feature works as expected.
Note: All contributors also need to fill out the Uber Contributor License Agreement before we can merge in any of your changes.
MIT License, please see LICENSE for details.