{"id":13936581,"url":"https://github.com/errbufferoverfl/usb-canary","last_synced_at":"2025-07-19T22:31:03.024Z","repository":{"id":162748558,"uuid":"85889290","full_name":"errbufferoverfl/usb-canary","owner":"errbufferoverfl","description":"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.","archived":true,"fork":false,"pushed_at":"2017-10-09T08:41:32.000Z","size":62,"stargazers_count":574,"open_issues_count":5,"forks_count":66,"subscribers_count":33,"default_branch":"master","last_synced_at":"2024-08-08T23:24:02.019Z","etag":null,"topics":["detection","monitoring","python","slack","twilio","usb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/errbufferoverfl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-03-23T00:23:38.000Z","updated_at":"2024-06-19T20:13:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"319a6d04-69bb-49dd-9b22-249d81e6384b","html_url":"https://github.com/errbufferoverfl/usb-canary","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errbufferoverfl%2Fusb-canary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errbufferoverfl%2Fusb-canary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errbufferoverfl%2Fusb-canary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errbufferoverfl%2Fusb-canary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/errbufferoverfl","download_url":"https://codeload.github.com/errbufferoverfl/usb-canary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226686729,"owners_count":17666928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["detection","monitoring","python","slack","twilio","usb"],"created_at":"2024-08-07T23:02:48.454Z","updated_at":"2024-11-27T04:31:13.700Z","avatar_url":"https://github.com/errbufferoverfl.png","language":"Python","readme":"# USB Canary\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)\n[![Build Status](https://travis-ci.org/errbufferoverfl/usb-canary.svg?branch=v1.0.2)](https://travis-ci.org/errbufferoverfl/usb-canary)\n\nUSB Canary is a Linux and OSX tool that uses psutil to monitor USB devices\neither around the clock, or just while your computer is locked. It can\nbe configured to send you an SMS via the Twilio API, notify a Slack\nchannel with it's inbuilt Slack bot, or send a push message through Pushover.\n\n**Disclaimer**: Under no circumstances should USB Canary be used for production, production-like \nsystems or critical infrastructure.\n\n## Getting Started\n\nThere are a couple of 3rd party libraries to get USB Canary running - so\nLinux and OSX users should read the prerequisites for their distribution.\n\n### Prerequisites\n\n- [slackclient](https://github.com/slackapi/python-slackclient) - A\nbasic client for Slack.com, which can optionally connect to the Slack\nReal Time Messaging (RTM) API.\n- [twilio](https://github.com/twilio/twilio-python) - A Python module\nfor communicating with the Twilio API and generating TwiML.\n- [pushover](https://github.com/Thibauth/python-pushover) - Comprehensive bindings and command line utility for the Pushover notification service\n- [psutil](https://pypi.python.org/pypi/psutil) - Cross-platform lib\nfor process and system monitoring in Python.\n- [gcc](https://gcc.gnu.org/) - GNU Compiler Collection\n- [Xcode](https://developer.apple.com/xcode/) - Integrated development\nenvironment for macOS\n- [Quartz](https://pypi.python.org/pypi/pyobjc-framework-Quartz) -\nWrappers for the Quartz frameworks on macOS.\n\n#### Installing Prerequisites on *Nix\n\nUbuntu and Debian users will need to make sure they have installed a C\ncompiler such as `gcc` as well as the `python-dev` package.\n\n```\nsudo apt-get install gcc python-dev python-pip\npip install psutil\n```\nMajor Linux distros also provide binary distributions of psutil. However\nthis is not recommended as *Nix generall ship older versions.\n```\nsudo apt-get install python-psutil\n```\n\nYou will also need to install the pip\n[`apt` library](https://apt.alioth.debian.org/python-apt-doc/library/index.html)\nthrough `apt` this can be done as follows:\n\n```\nsudo apt install python-apt\n```\n\nThis library provides access to almost every functionality supported by\nthe underlying apt-pkg and apt-inst libraries. In Debian Jessie it may\ncome with the install but just double check to make sure it's there.\n\n#### Installing Prerequisites on OSX\n\nOSX users will need to install [Xcode](https://developer.apple.com/downloads/?name=Xcode) first then:\n```\npip install psutil==5.3.1\n```\n\nOSX users will also need to manually install the [Quartz](https://pypi.python.org/pypi/pyobjc-framework-Quartz)\nPython library as follows:\n```\npip install pyobjc-framework-Quartz\n```\n\nOnce distribution specific instractions have been followed the following\npackages can all be installed via `pip`, in some cases you may need to\nuse `pip` with `sudo`. You can install the packages as follows:\n\n```\npip install slackclient==1.0.9\npip install twilio==5.7.0\npip install python-pushover==0.3\npip install psutil==5.3.1\npip install sander-daemon==1.0.0\n```\n\n### Installing\n\nBefore running USB Canary, you will need to configure your `settings.json`\nfile, which should be located in the root directory. If it is not found\nhere, you will encounter an `IOError`.\n\nAn example `settings.json` file:\n\n```json\n{\n  \"settings\": {\n    \"slack\": {\n      \"api_key\": \"xoxb-111111111111-abcdefghijklmnopqrstuvwx\",\n      \"channel_name\": \"usb_canary\",\n      \"botname\": \"USB Canary\"\n    },\n    \"twilio\": {\n      \"auth_token\": \"l7cy56u3Nys72vPNRS8TAbaW3X1Ap4ma\",\n      \"account_sid\": \"wP32p6qFNzJ25FD1IKM0YtX629eoHbrMiV\",\n      \"twilio_number\": \"+61491570156\",\n      \"mobile_number\": \"+61491570157\"\n    },\n    \"pushover\": {\n      \"priority\": 1,\n      \"user_key\": \"youruserkeygoeshere\",\n      \"api_token\": \"yourapitokengoeshere\"\n    },\n    \"general\": {\n      \"paranoid\": true,\n      \"screensaver\": \"xscreensaver\",\n      \"slack\": false,\n      \"twilio\": true,\n      \"pushover\": false,\n    }\n  }\n}\n```\n\nNote that `paranoid`, `slack` and `twilio` are boolean values and\nshould be set to `true` or `false`. If the file is formatted incorrectly\nand it cannot be parsed, you will get a `ValueError`, you can use\n[JSONLint](http://jsonlint.com/) if you find yourself having issues with\nthis.\n\n# Linux\n\nUSB Canary, can 'detect' if you are running\n`XScreenSaver` or `gnome-screensaver` on your computer, this is done by\njust checking which packages are installed via the `apt` library, if\nboth of them are installed though, it will leave you to determine which\none you are using - if you have an unsupported screensaver, don't fret,\nyou can still run it in paranoid mode.\n\nParanoid mode is also suitable for people who want to monitor if their\nservers have had USB's plugged into them,\nalthough I haven't tested them on Linode, Amazon Web Services, or\nDigital Ocean it is suitable for those with\nphysical servers that may need this sort of monitoring.\n\nTo start the application:\n```shell\n# Linux users\n./usb_canary.py start | stop | restart\n```\n\n```shell\n# OSX users\nsudo ./usb_canary.py start | stop | restart\n\n```\n\n## Deployment\n\nThe following will outline the basic steps to deploying USB Canary to\nSlack and Twilio.\n\n### Twilio\n\nTo use the Twilio integration you will need to get an:\n- [Auth Token](https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-how-to-change-them)\n- [Account SID](https://support.twilio.com/hc/en-us/articles/223136607-What-is-an-Application-SID-)\n- Twilio Mobile Number with SMS support\n\n### Slack\n\nTo use the Slack integration you will need to [setup a bot user](https://api.slack.com/bot-users)\n\n### Pushover\n\nTo use Pushover API for sending push messages to your devices, you need to create an [account and application](https://pushover.net/faq#overview-what)\n\n## Exit Codes\n\n| Exit Code | Reason | Solution |\n|:-:|---|---|\n| 0 | PASSED |  |\n| 400 | Unknown command. | Usage: `./usb_canary start | stop | restart` |\n| 401 | Paranoid option not set. | Check that paranoid is set to `true` or `false` |\n| 402 | Screensaver is not supported. | Currently known working screensavers include: XScreenSaver, gnome-screensaver |\n| 403 | Screensaver conflict. | Screensaver detected, but both packages have been found. The user needs to be manually specified in the `settings.json` file |\n| 404 | Slack credentials not provided. | Slack flag has been set, but credentials not provided, check `settings.json` |\n| 405 | Slack credentials incorrect. | Slack flag has been set, but credentials are not correct, check `settings.json` |\n| 406 | Twilio credentials not correct. | Twilio flag has been set, but credentials not provided, check `settings.json` |\n| 407 | Twilio account SID not set | Twilio SID value has not been set, check `settings.json` |\n| 408 | Twilio API token is blank | Twilio API token has not been set, check `settings.json` |\n| 409 | Receiving mobile # is blank  | Twilio receiving mobile number has not been set, check `settings.json` |\n| 410 | Twilio mobile # is blank | Twilio allocated mobile number has not been set, check `settings.json` |\n| 411 | Twilio key missing in settings.json | Twilio JSON block is not in settings file, check `settings.json` |\n| 412 | Pushover user key missing in settings.json | Pushover user key (per account) is missing, check `settings.json` |\n| 413 | Pushover user key missing in settings.json | Pushover api key (per registered app) is missing, check `settings.json` |\n| 414 | Pushover priority level missing in settings.json | Pushover priority level is missing, check `settings.json` |\n| 415 | Pushover key missing in settings.json | Pushover JSON block is not in settings file, check `settings.json` |\n| 501 | `settings.json` file missing. | Download setting.json from Github |\n| 502 | Unable to parse settings.json | Check for erroneous symbols, use [JSONLint](http://jsonlint.com/) to check formatting |\n| 503 | Paranoid option not set correctly. | Paranoid option not set, or set incorrectly |\n| 504 | Screensaver not found. | Screensaver not set, set incorrectly, or there was a problem detecting screensaver. |\n| 505 | Verify that your operating system is supported. | Currently known working operating systems include: Debian Jessie, Debian Stretch, Ubuntu ZestyZapus |\n| 506 | Screensaver or paranoid setting is not set correctly. | Check settings.json |\n| 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 |\n\n## Built With\n\n- [Python 3](https://www.python.org/download/releases/3.0/)\n- [slackclient](https://github.com/slackapi/python-slackclient) - A basic client for Slack.com, which can optionally connect to the Slack Real Time Messaging (RTM) API.\n- [twilio](https://github.com/twilio/twilio-python) - A Python module for communicating with the Twilio API and generating TwiML\n- [psutil](https://pypi.python.org/pypi/psutil) - Cross-platform lib for process and system monitoring in Python.\n- [Quartz](https://pypi.python.org/pypi/pyobjc-framework-Quartzhttps://pypi.python.org/pypi/pyobjc-framework-Quartz) - Wrappers for the Quartz frameworks on macOS\n- [python-apt](https://apt.alioth.debian.org/python-apt-doc/library/index.html) - A library that provides access to almost every functionality supported by the underlying apt-pkg and apt-inst libraries\n\n## Contributing\n\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for details.\n\n## Versioning\n\nWe use a simple major.minor.patch versioning where\n - A major version change will make changes that are incompatible with previous versions\n - A minor version change will add backwards-compatible functionality or bug-fixes\n - A patch version change will add backwards-compatible bug-fixes\n\n## Authors\n\n- **errbufferoverfl** - *Initial work* - Security Tester by day, someone with too much time on their hands by night.\n\n## License\n\nThis project is licensed under the GNU GPLv3 License - see the\n[LICENSE](LICENSE.txt) file for details.\n\n## Acknowledgements\n\n- [timball](https://github.com/timball) - for recommending `sander-daemon`\n- [cclauss](https://github.com/cclauss) - for integrating Travis CI\n- [helpsterTee](https://github.com/helpsterTee) - for adding Pushover support\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrbufferoverfl%2Fusb-canary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferrbufferoverfl%2Fusb-canary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrbufferoverfl%2Fusb-canary/lists"}