USB Canary

USB Canary is a Linux tool that uses pyudev to monitor USB devices either around the clock, or just while it's locked. It can be configured to send you an SMS via the Twilio API, or notify a Slack channel with it's inbuilt Slack bot.

Getting Started

There are a couple of 3rd party libraries to get USB canary running - for some this may seem like a bad idea, but it's better than recreating the wheel or rolling your own crypto. Below we will go through the 3rd party libraries, so those who are so inclined can check them out before installing.

Prerequisites

• slackclient - A basic client for Slack.com, which can optionally connect to the Slack Real Time Messaging (RTM) API.
• twilio - A Python module for communicating with the Twilio API and generating TwiML
• pyudev - Python bindings to libudev (with support for PyQt4, PySide, pygobject and wx)
• sander-daemon - Jejik daemon class improved by Server Density

These can all be installed via pip, in some cases you may need to use pip with sudo. You can install the packages as follows:

pip install slackclient
pip install twilio
pip install pyudev
pip install sander-daemon

Otherwise you can just run pip install -r requirements.txt

You will also need to install the pip apt library through apt (which doesn't get confusing fast) this can be done as follows:

sudo apt install python-apt

This library provides access to almost every functionality supported by the underlying apt-pkg and apt-inst libraries. In Debian Jessie it may come with the install but just double check to make sure it's there.

Installing

Before running USB Canary, you will need to configure your settings.json file, which should be located in the root directory. If it is not found here, you will encounter an IOError.

An example settings.json file:

{
  "settings": {
    "slack": {
      "api_key": "xoxb-111111111111-abcdefghijklmnopqrstuvwx",
      "botname": "slack bot name"
    },
    "twilio": {
      "auth_token": "l7cy56u3Nys72vPNRS8TAbaW3X1Ap4ma",
      "account_sid": "wP32p6qFNzJ25FD1IKM0YtX629eoHbrMiV",
      "twilio_number": "+61491570156",
      "mobile_number": "+61491570157"
    },
    "general": {
      "paranoid": true,
      "screensaver": "xscreensaver",
      "slack": false,
      "twilio": true
    }
  }
}

Note that paranoid, slack, and twilio are boolean values and should be set to true or false. If the file is formatted incorrectly and it cannot be parsed, you will get a ValueError, you can use JSONLint if you find yourself having issues with this.

USB Canary, is sort of smart and can 'detect' if you are running XScreenSaver or gnome-screensaver on your computer, this is done by just checking which packages are installed via the apt library, if both of them are installed though, it will leave you to determine which one you are using - if you have an unsupported screensaver, don't fret, you can still run it in paranoid mode.

Paranoid mode is also suitable for people who want to monitor if their servers have had USB's plugged into them, although I haven't tested them on Linode, Amazon Web Services, or Digital Ocean it is suitable for those with physical servers that may need this sort of monitoring.

To start the application:

./usb_canary.py start | stop | restart

Deployment

The following will outline the basic steps to deploying USB Canary to Slack and Twilio. As extra services are added, please ensure you add appropriate documentation with your PR.

Twilio

To use the Twilio intergration you will need to get an:

• Auth Token
• Account SID
• Twilio Mobile Number with SMS support

Slack

To use the Slack integration you will need to setup a bot user

Exit Codes

File Structure

I have tried to keep the code fairly segregated and straightforward to follow for those wishing to contribute.

usb-canary
├──LICENSE.txt
├──settings.json
├──canary
│   ├──slack
│   │   ├──slack.py
│   │   ├──slack_bot.py
│   │   └──__init__.py
│   ├──settings.py
│   ├──message_handler.py
│   ├──setup.py
│   ├──__init__.py
│   ├──twilleo
│   │   ├──__init__.py
│   │   └──twilleo.py
│   └──screensaver
│       ├──helpers.py
│       ├──gnome-screensaver.py
│       ├──xscreensaver.py
│       └──__init__.py
├──README.md <---------------------------------- YOU ARE HERE
├──requirements.txt
├──ISSUE_TEMPLATE.md
├──PULL_REQUEST_TEMPLATE.md
└──usb_canary.py 

Under the main canary directory you will find folders for different services such as Twilio which is named twilleo to avoid clashes with the Twilio library. Screensaver support can be found under the screensaver directory with each Screensaver having their own file, just to keep things tidy.

Built With

• Python 2.7 - The one that is installed on most operating systems by default
• pyudev - A pure python binding to libudev, the device and hardware management and information library of Linux
• slackclient - A basic client for Slack.com, which can optionally connect to the Slack Real Time Messaging (RTM) API.
• twilio - A Python module for communicating with the Twilio API and generating TwiML
• python-apt - A library that provides access to almost every functionality supported by the underlying apt-pkg and apt-inst libraries
• sander-daemon - Jejik daemon class improved by Server Density

Contributing

See the CONTRIBUTING.md file for details.

Versioning

We use a simple major.minor.patch versioning where

• A major version change will make changes that are incompatible with previous versions
• A minor version change will add backwards-compatible functionality or bug-fixes
• A patch version change will add backwards-compatible bug-fixes

Authors

• errbufferoverfl - Initial work - Security Tester by day, someone with too much time on their hands by night.

License

This project is licensed under the GNU GPLv3 License - see the LICENSE.txt file for details.

Acknowledgements

• timball - for recommending sander-daemon