hephaest0s/usbkill

★ 4,588PythonAudience · ops devopsComplexity · 1/5Setup · easy

Mindmap

mindmap
  root((usbkill))
    What it does
      Monitors USB ports
      Triggers instant shutdown
      Physical kill switch
    Features
      Device whitelist
      Configurable polling
      RAM and swap wipe
      Custom pre-shutdown commands
    Supported platforms
      Linux
      macOS
      BSD
    Use cases
      Laptop theft protection
      Forensic data block
      High-risk environments
    Setup
      Single Python file
      Run with sudo
      No install needed

mindmap root((usbkill)) What it does Monitors USB ports Triggers instant shutdown Physical kill switch Features Device whitelist Configurable polling RAM and swap wipe Custom pre-shutdown commands Supported platforms Linux macOS BSD Use cases Laptop theft protection Forensic data block High-risk environments Setup Single Python file Run with sudo No install needed

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Protect a laptop during high-risk situations by tying a USB key to your wrist, if the computer is grabbed, the key pulls out and triggers immediate shutdown.

USE CASE 2

Counter USB-based forensic data extraction by shutting down before any plugged-in device can copy data.

USE CASE 3

Run as a background process on a Linux or macOS machine to guard against physical tampering via USB ports.

USE CASE 4

Combine with full-disk encryption to ensure a seized, powered-off machine cannot be read even after forced shutdown.

Tech stack

Python

Getting it running

Difficulty · easy Time to first run · 5min

Run with sudo from the terminal, no install needed beyond Python, disk encryption is strongly recommended alongside this tool.

Check repository for license, single Python script, freely usable with no install process beyond Python.

In plain English

usbkill is a small Python script that watches your computer's USB ports and, if anything changes (a device is plugged in or unplugged), immediately shuts the machine down. The idea is to give someone a physical kill switch: if your computer is taken from you or if law enforcement plugs in a device to copy data, the shutdown happens before they can do anything. The project page specifically calls out situations like police raids or laptop theft, and references the well-known case of Ross Ulbricht. A common law enforcement technique is to keep a computer's screen active using a device called a mouse jiggler so it never locks. usbkill counters that by triggering on USB activity rather than waiting for a screensaver timeout. The program runs as a background process with root permissions. A popular usage pattern is to tie a USB key to your wrist on a cord, insert it, and start usbkill. If the computer is grabbed away from you, the key is pulled out and the machine shuts down instantly. The README also stresses that disk encryption is necessary alongside this tool, because without it, a powered-off drive can still be read. Features listed for version 1.0-rc.4 include support for Linux, BSD, and macOS, a configurable whitelist so you can exempt trusted USB devices, adjustable polling interval (default 250 milliseconds), optional RAM and swap wiping on shutdown, and the ability to define custom commands that run just before the machine powers off. There is one optional dependency, the secure-delete package, needed only if you want it to wipe files or memory. It is a single Python file, started from the terminal with sudo. No install process beyond having Python is required.

Copy-paste prompts

Prompt 1

I want to build a Python script that monitors USB devices on Linux using pyudev and triggers a custom shell command when any device is added or removed. Show me the event loop.

Prompt 2

Write a Python script that runs as a background daemon with root permissions, polls a system command every 250ms to detect USB changes, and calls os.system('shutdown -h now') on any change.

Prompt 3

How do I create a whitelist of trusted USB device IDs in Python so my monitoring script ignores my keyboard and mouse but shuts down for any unknown device?

Prompt 4

Show me how to run a Python script at system startup on Linux (systemd service file) with root permissions and have it log events to /var/log/usbkill.log.

Prompt 5

I want to wipe RAM contents on Linux before shutdown using Python. What system commands or tools (like secure-delete) should I call, and how do I invoke them safely from Python?

Open on GitHub → Explain another repo

← hephaest0s on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.