commit 225a684dbf56dc31091ce239657205645646ed8f
parent 4c8d54d3d9c5da103e6c952f272334da6714805b
Author: Andrew Laack <andrew@laack.co>
Date: Tue, 8 Sep 2026 23:44:24 -0500
Better readme
Diffstat:
| A | README | | | 27 | +++++++++++++++++++++++++++ |
| D | README.md | | | 38 | -------------------------------------- |
2 files changed, 27 insertions(+), 38 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,27 @@
+usb-ks
+======
+usb-ks is a USB killswitch program. usb-ks executes the specified command on all USB device changes, not just disconnects. When governments seize devices they often use USB devices to exfiltrate data and to ensure systems with FDE don't shutdown. It is thusly evident shutdown behaviors should be initiated on connection and disconnection.
+
+Requirements
+============
+go, libudev, /bin/sh
+
+Installation
+============
+Run the following commands:
+ git clone git://git.laack.co/usb-ks.git
+ cd usb-ks
+ go install
+
+Optionally:
+ sudo install ~/go/bin/usb-ks /usr/local/bin/
+
+Ensure your go installation directory is on your path if you don't perform the optional step.
+
+Usage
+=====
+Execute xscreensaver on USB device change:
+ usb-ks
+
+Execute arbitrary command on USB device change:
+ usb-ks {command}
diff --git a/README.md b/README.md
@@ -1,38 +0,0 @@
-# usb-ks
-
-usb-ks is a USB killswitch program, inspired by [https://github.com/BusKill/buskill-app](https://github.com/BusKill/buskill-app), but simplified and written in Go instead of Python. Additionally, usb-ks executes the specified command on all USB device changes, not just disconnects. When governments seize devices they often use USB devices to exfiltrate data and to ensure systems with FDE don't shutdown. It is thusly evident shutdown behaviors should be initiated on connection and disconnection.
-
-# installation
-
-`go install github.com/andrewlaack/usb-ks@e41c1fdaf9126800589957a3bdd568fa96086ce5`
-
-Then optionally:
-
-`sudo install ~/go/bin/usb-ks /usr/local/bin/`
-
-NOTE: ensure your go installation directory (default: ~/go/bin) is on your path as this is the default installation location. If you run the optional command, ensure the first argument to install contains the correct go installation path.
-
-## dependencies
-
-- [go](https://go.dev/dl/)
- - for building
-- [libudev](https://www.freedesktop.org/software/systemd/man/latest/libudev.html)
- - for listening to usb device changes
-- a shell
- - /bin/sh to execute the specified command
-
-# usage
-
-Basic invocation, executing xscreensaver on USB device change:
-
-```usb-ks```
-
-NOTE: Since xscreensaver does not shutdown your system (i.e. doesn't engage FDE protections), it may not be desirable for certain threat models.
-
-For better protection, I recommend using `poweroff`:
-
-```usb-ks poweroff```
-
-See options:
-
-```usb-ks --help```
