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.

USB Canary was a personal project started while between jobs after looking for a tool to monitor USB ports on my Linux computers while they were unattended, while there are many great tools already out there many require the user to login before they are notified - while many people would also argue to just turn USB ports off at a hardware level or fill them with epoxy, I still need my USB ports for keyboards and mice etc.

It was recently featured on Bleeping Computer and appreciate feedback and support received from the community.

I am currently looking into an OSX and Windows versions, the exact details of these versions are still uncertain as I work out of the details of particular functions in their respective operating systems.

A few people online have disagreed with the usage of third-party libraries and the reliance on a programming language such as Python to reliably monitor USB devices. The decision to create USB Canary in Python was a personal choice, this was originally a personal project I had kicking around at the start of the year that I decided to release to the wider community so someone might get a kick out of it.

The usage of third-party libraries specifically pyudev meant that in the long term I had a code base that was easy to maintain and update for myself and didn't need to make kernel level calls and parse that information reliably.

There are a couple of 3rd party libraries to get USB Canary running. Below we will go through the 3rd party libraries, so those who are so inclined can check them out before installing.

• 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.

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

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.

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

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

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

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.

• Python 2.7 - The one that is installed on most operating systems by default (Preliminary support for Python 3 has recently been added)
• 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

See the CONTRIBUTING file for details.

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

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

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

• timball - for recommending sander-daemon
• cclauss - for intergrating Travis CI