errbufferoverfl / usb-canary

A Linux or OSX tool that uses psutil to monitor devices while your computer is locked. In the case it detects someone plugging in or unplugging devices it can be configured to send you an SMS or alert you via Slack or Pushover.

USB Canary

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

Disclaimer: Under no circumstances should USB Canary be used for production, production-like systems or critical infrastructure.

Getting Started

There are a couple of 3rd party libraries to get USB Canary running - so Linux and OSX users should read the prerequisites for their distribution.

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.
• pushover - Comprehensive bindings and command line utility for the Pushover notification service
• psutil - Cross-platform lib for process and system monitoring in Python.
• gcc - GNU Compiler Collection
• Xcode - Integrated development environment for macOS
• Quartz - Wrappers for the Quartz frameworks on macOS.

Installing Prerequisites on *Nix

Ubuntu and Debian users will need to make sure they have installed a C compiler such as gcc as well as the python-dev package.

sudo apt-get install gcc python-dev python-pip
pip install psutil

Major Linux distros also provide binary distributions of psutil. However this is not recommended as *Nix generall ship older versions.

sudo apt-get install python-psutil

You will also need to install the pip apt library through apt 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 Prerequisites on OSX

OSX users will need to install Xcode first then:

pip install psutil==5.3.1

OSX users will also need to manually install the Quartz Python library as follows:

pip install pyobjc-framework-Quartz

Once distribution specific instractions have been followed the following packages 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==1.0.9
pip install twilio==5.7.0
pip install python-pushover==0.3
pip install psutil==5.3.1
pip install sander-daemon==1.0.0

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",
      "channel_name": "usb_canary",
      "botname": "USB Canary"
    },
    "twilio": {
      "auth_token": "l7cy56u3Nys72vPNRS8TAbaW3X1Ap4ma",
      "account_sid": "wP32p6qFNzJ25FD1IKM0YtX629eoHbrMiV",
      "twilio_number": "[phone]",
      "mobile_number": "[phone]"
    },
    "pushover": {
      "priority": 1,
      "user_key": "youruserkeygoeshere",
      "api_token": "yourapitokengoeshere"
    },
    "general": {
      "paranoid": true,
      "screensaver": "xscreensaver",
      "slack": false,
      "twilio": true,
      "pushover": false,
    }
  }
}

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.

Linux

USB Canary, 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:

# Linux users
./usb_canary.py start | stop | restart

# OSX users
sudo ./usb_canary.py start | stop | restart

Deployment

The following will outline the basic steps to deploying USB Canary to Slack and Twilio.

Twilio

To use the Twilio integration 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

Pushover

To use Pushover API for sending push messages to your devices, you need to create an account and application

Exit Codes

Exit Code	Reason	Solution
0	PASSED
400	Unknown command.	Usage: `./usb_canary start
401	Paranoid option not set.	Check that paranoid is set to true or false
402	Screensaver is not supported.	Currently known working screensavers include: XScreenSaver, gnome-screensaver
403	Screensaver conflict.	Screensaver detected, but both packages have been found. The user needs to be manually specified in the settings.json file
404	Slack credentials not provided.	Slack flag has been set, but credentials not provided, check settings.json
405	Slack credentials incorrect.	Slack flag has been set, but credentials are not correct, check settings.json
406	Twilio credentials not correct.	Twilio flag has been set, but credentials not provided, check settings.json
407	Twilio account SID not set	Twilio SID value has not been set, check settings.json
408	Twilio API token is blank	Twilio API token has not been set, check settings.json
409	Receiving mobile # is blank	Twilio receiving mobile number has not been set, check settings.json
410	Twilio mobile # is blank	Twilio allocated mobile number has not been set, check settings.json
411	Twilio key missing in settings.json	Twilio JSON block is not in settings file, check settings.json
412	Pushover user key missing in settings.json	Pushover user key (per account) is missing, check settings.json
413	Pushover user key missing in settings.json	Pushover api key (per registered app) is missing, check settings.json
414	Pushover priority level missing in settings.json	Pushover priority level is missing, check settings.json
415	Pushover key missing in settings.json	Pushover JSON block is not in settings file, check settings.json
501	settings.json file missing.	Download setting.json from Github
502	Unable to parse settings.json	Check for erroneous symbols, use JSONLint to check formatting
503	Paranoid option not set correctly.	Paranoid option not set, or set incorrectly
504	Screensaver not found.	Screensaver not set, set incorrectly, or there was a problem detecting screensaver.
505	Verify that your operating system is supported.	Currently known working operating systems include: Debian Jessie, Debian Stretch, Ubuntu ZestyZapus
506	Screensaver or paranoid setting is not set correctly.	Check settings.json
507	Verbose logging option not set.	Check that verbose is set to true or false (without the quotes). True enables debugging, False enables info and higher

Built With

• Python 3
• 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
• psutil - Cross-platform lib for process and system monitoring in Python.
• Quartz - Wrappers for the Quartz frameworks on macOS
• python-apt - A library that provides access to almost every functionality supported by the underlying apt-pkg and apt-inst libraries

Contributing

See the CONTRIBUTING 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 file for details.

Acknowledgements

• timball - for recommending sander-daemon
• cclauss - for integrating Travis CI
• helpsterTee - for adding Pushover support

usb-canary's Issues

Repository not found or removed

Hello,

I know this is not the right place for this issue but i didn't find another place to do so.
I was looking for this repository https://github.com/errbufferoverfl/recce but its not there anymore, so please can you tell me where to find this project?

Non-automounted filesystems are ignored

usb-canary only monitors what psutil considers "physical", mounted partitions. This means any attached device that does not automount while usb-canary is active (e.g. while the screen is locked) will not be caught.

• Feature Request
• Bug Report

Expected Behavior

Consider the following setup: There is a laptop, with usb-canary configured to monitor while the screen is locked. Automounting is disabled. The user locks the screen, goes away. During her absence, a coworker of her goes near the laptop and finds a USB stick lying on the ground. Thinking the USB stick fell out, she picks it up and plugs it in. Later, the user returns to unlock her laptop. At this point, usb-canary will not have picked up on the additional device since it is not mounted yet. However, now that the laptop is unlocked, she or some automatism might inadvertently mount the filesystem of the usb stick.

Current Behavior

usb-canary does not pick up on the new device absent automounting.

Possible Solution

Monitor physical block devices, or even better, monitor physical USB devices instead of mounted partitions.

Steps to Reproduce (for bugs)

Context

usb-canary at least on first glance looks like a security tool. Thus it should be secure.

Your Environment

I'm no mac expert, but this issue will very likely persist on mac since this "list only mounted filesystems thing" is the documented behavior of psutil's list_partitions.

usb-canary will exit due to errors

In several places, usb-canary will quietly exit depending on external conditions. One such place is the twilio message handler. If a mere network error occurs, it will quietly exit.

• Feature Request
• Bug Report

Expected Behavior

When a messaging channel is configured and errors occur, usb-canary should asynchronously retry as many times as necessary to send the message. Under no conditions should failure of one messaging channel prevent other intact channels from working.

Current Behavior

If e.g. twilio and slack are enabled, and the twilio code raises an error, usb-canary will exit without even attempting to use slack.

Possible Solution

Handle all messaging asynchronously with appropriate back-off.

Steps to Reproduce (for bugs)

Context

usb-canary at least on first glance looks like a security tool. Thus it should be secure.

Your Environment

This is independent of operating system.

Misleading advertisement

The README sais about usb-canary that its function is to "monitor USB devices", just as its name suggests. However, as far as I can tell it is only monitoring mounted physical partitions.

• Feature Request
• Bug Report

Possible Solution

Clearly document what is monitored, under which conditions alerts will happen and what use this is applied to common threat models.

I would also highly suggest a note pointing out that usb-canary is experimental, early stage software and should absolutely not be relied upon in critical situations.

Context

usb-canary at least on first glance looks like a security tool. For any security tool, clear and precise communication as to its threat model and scope are necessary for it to be used correctly.

An important omission is that currently, usb-canary will not detect one of the most common classes of usb-based attacks, available to anyone: Fake HID-Class keyboard devices. In contrast, properly implemented even a change such as inserting a keylogger could be detected.

canonical location for sander-daemon module

could just pip install sander-daemon

https://pypi.python.org/pypi/sander-daemon/1.0.0
https://github.com/serverdensity/python-daemon

i could make a patch... but only if you don't.

--timball

Possible DOS due to blocking network handling

Since all message sending is done in a blocking manner, inlined with the actual detection logic and since that is running in an infinite loop (side note: a delay or even better, some asynchronous notification systems such as inotify might be in order here), an attacker able to disrupt usb-canary may be able to stall it, preventing detection.

• Feature Request
• Bug Report

Expected Behavior

usb-canary should operate and correctly log regardless of network conditions that might make the message sending code block.

Current Behavior

usb-canary will hang during bad network conditions.

Possible Solution

Handle message sending asynchronously, ideally with one asynchronous channel for every configured message channel.

Steps to Reproduce (for bugs)

Context

usb-canary at least on first glance looks like a security tool. Thus it should be secure.

Your Environment

This will likely affect all supported operating systems.

use udev instead of compare prev and now state

Hi,
It's better for this project use from udev capability instead compare state.
We can use pydev that monitor all ports in computer. Ex,

import pyudev
context = pyudev.Context()
monitor = pyudev.Monitor.from_netlink(context)
monitor.filter_by('block')
def log_event(action, device):
    if 'ID_FS_TYPE' in device:
        print('{0} - {1}'.format(action, device.get('ID_FS_LABEL'))

observer = pyudev.MonitorObserver(monitor, log_event)
observer.start()
# when connect a device print below messsage, Ex
# add - Hard1

by above example, when connected or disconnect a device to computer run log_event function and can run any action!

Pushover support

• Feature Request
• Bug Report

Expected Behavior

It would be nice to use Pushover as an alternative channel of notification transportation.

Current Behavior

usb-canary does not currently use Pushover as a channel of notification transportation.

Possible Solution

Implement Pushover as a channel of notification transportation

Steps to Reproduce (for bugs)

N/A

Context

I like to use Pushover for notification transportation. Unfortunately this is currently not supported.

Github short description does not list mac as target platform

(see title)

Windows version

What will it be...?

usbcanary.exe
--install --- install as service and start it
--uninstall --- remove service
--config X:/y/z.config --- pick other config file(if not set, read ./usbcanary.config file)

usbcanary.config
UseWebAPI false
UseHTTPProxy 1.2.3.4:5
PlaySoundOnDetect true
Soundfile X:/y/z/p.mp3
RunCommandOnDetect true
RunCommand "shutdown -s -t 0"

ImportError No Module named daemon.daemon

I tried running the tool on Kali Linux, but I get this error message. I installed all the dependencies and configured the settings.json file and put it in the root directory as specified but I still get this error.
Did I miss something ?

# ./usb-canary.py start
Traceback (most recent call last):
File "./usb_canary.py", line 34, in <module>
from canary.daemon.daemon import Daemon
ImportError: No module named daemon.daemon

macOS support.

I noticed that you are planning on making OS X support. I've been using https://github.com/hephaest0s/usbkill this, maybe help you with some ideas. Cheers.

check_state will not catch changes that don't change the total number of mounted file systems

canary.operating_system.helpers.check_state will fail to catch any change in mounted file systems that does not change the total number of mounted file systems (as seen by psutil).

• Feature Request
• Bug Report

Expected Behavior

Consider a laptop with usb-canary running during screen lock, and the screen being locked while a usb disk containing a single ntfs partition is attached and that partition is mounted. Automount is enabled.

Now consider an attacker unplugs the ntfs usb disk and plugs in another ntfs-formatted, single-partition usb-disk. This other disk is auto-mounted. Note that this is a common scenario when a device has limited USB ports available.

usb-canary should immediately raise hell.

Current Behavior

usb-canary will not notice anything happened provided the change happened quick enough between two checks (likely).

Possible Solution

Properly compare states. Compare more than just device name, mountpoint, filesystem type and options. At least also monitor:

• Device path (usb port number and path through hubs)
• Device serial number from USB descriptors
• Filesystem UUID where available
• Partition and device UUIDs where available
• Other device parameters such as size and additional usb descriptor fields

Steps to Reproduce (for bugs)

(no poc provided)

Context

usb-canary at least on first glance looks like a security tool. Thus it should be secure.

Your Environment

This is independent of operating system.