Documentation

README.md

@@ -24,11 +24,11 @@ I'm going to assume you've got a Raspberry Pi Zero (W) but it shouldn't be too d
 * The default login is **alarm:alarm**.
 
 ## Using Different Gadgets
-The configuration file resides in `/boot/usbninja/options.txt`. Open this up with any text editor and you will see the different options you can set along with some brief explanations. Each configuration is set by writing `option: value` and leaving a newline in between each.
+The configuration file resides in `/boot/usbninja/options.txt`, which corresponds to partition one on the MicroSD card - accessible on MacOS and Windows without setting up ext4 drivers. Open this up with any text editor and you will see the different options you can set along with some brief explanations. Each configuration is set by writing `option: value` and leaving a newline in between each.
 
 **NOTE:** Any option can be omitted by this file and the defaults will automatically be chosen. If you wanted, you could just have `gadget: <YOUR_GADGET>` and nothing else.
 Below are the currently supported options:
-* `gadget`: The USB devices that are to be imitated, also known as "gadgets". Supported gadgets are `serial`, `ethernet_ecm`, `hid_payload`, `storage`. See the [gadgets](doc/GADGETS.md) page for more information.
+* `gadget`: The USB devices that are to be imitated, also known as "gadgets", separated by commas. See the [gadgets](doc/GADGETS.md) page for more information.
 * `vendorid`: The VID that will be presented to the host machine. Along with the PID, this is very important as it will usually determine which drivers are loaded to handle the device by the host. Less of an issue in Linux, but is quite vital in Windows. Needs to be in the format: `0x????`. Defaults to **`0x1d6b`** (Linux Foundation).
 * `productid`: The PID that will be presented to the host machine. Needs to be in the format `0x????`. Defaults to **`0x0104`** (Multifunction Composite Gadget).
 * `serialnumber`: The serial number that will be presented to the host. Needs to be in the format `????????????????` (16 hex characters long). Defaults to **`fedcba9876543210`**.

TODO.md

@@ -8,6 +8,8 @@
 * hid_remote gadget
 * ~~DHCP for ethernet gadget~~
 * Add "one-stop-shop" mode that deletes options.txt after execution
+* Multiple keyboard layouts
+* Post gadget-setup script execution
 
 ## Code Changes
 * Replace C style if IsTrue() == 0 statements with bools

doc/DEVELOPMENT.md

@@ -0,0 +1,36 @@
+# USB Ninja
+## Development information
+
+If you're looking to add functionality to the USB Ninja or devise a more advanced payload than what the basic `options.txt` provides, then you'll probably find this document useful.
+
+### Binaries
+All the binaries are located in `/lib/usbninja/` and are as follows:
+* `main` - The binary ran by `startup.service` that does all the work setting up the gadgets with the right configurations.
+* `sendhid` - This will just send what's in `hid.txt` via `/dev/hidg0`. You need the `hid_payload` gadget to be already active on the host for this to work. Requires root.
+* `stopall` - This will disable and remove all gadgets from `configfs`. Useful to change gadgets without having to reboot the USB Ninja. Note however, that occasionally the host can get confused (has happened to me a few times on Linux) so you might still have to unplug the device and plug it back in.
+
+### Source Code
+As well as being available in this repo, the source is included in `/lib/usbninja/src/`. You can use the build scripts to compile the source code and copy the binaries up a directory.
+* `build_main.sh` - Builds `main` only
+* `build_sendhid.sh` - Builds `sendhid` only
+* `build_stopall.sh` - Builds `stopall` only
+* `build_all.sh` - Builds everything
+
+### Configuration
+If you delete the `options.txt` (and `hid.txt`) from `/boot/usbninja/` then `main` will look to `/lib/usbninja/config/` for them instead. You might find it useful to have everything close by if you are constantly changing these files.
+
+### Systemd
+The `startup.service` lives in `/etc/systemd/system/startup.service` and contains the following:
+```
+[Unit]
+Description=Startup Script for the USB Ninja
+After=basic.target
+Before=network.target
+
+[Service]
+ExecStart=/lib/usbninja/main
+
+[Install]
+WantedBy=basic.target
+```
+If you are devising an attack that incorporates some kind of script that is to be ran after `main` finishes executing, then currently you can just create your own `.service` file, but be sure to add the line `After=startup.service` in the `[Unit]` segment. Better support for this situation is on the way.

doc/ETHERNET.md

@@ -0,0 +1,13 @@
+# USB Ninja
+## Ethernet Gadgets
+
+There are currently two different ethernet gadgets available; `ethernet_ecm` and `ethernet_rndis` (although `ethernet` is also recognised as an alias to `ethernet_ecm`).
+
+The difference is very slight and is to do with some funkiness on the part of Windows. RNDIS (or _**R**emote **N**etwork **D**river **I**nterface **S**pecification_ to it's friends) is a proprietary Microsoft protocol for handling USB-To-Ethernet adapters. If you want to use the USB Ninja with a Windows host, you're going to need to use `ethernet_rndis`.
+
+While most (if not all!) Linux distros (and MacOS) also support _RNDIS_, some embedded devices may not. That's where `ethernet_ecm` comes in! ECM (or _**E**thernet **C**ontrol **M**odel_) predates _RNDIS_ but is supported by pretty much _**everything**_ except for Windows. In general, if you aren't targetting Windows, use `ethernet_ecm`.
+
+Once an ethernet gadget is active, a small DHCP server is started that will assign `10.0.0.2` to the host (you may need to run something like `dhclient` on Linux depending on your distro). The name of the network interface will also vary depending on your OS, but shouldn't be too hard to figure out. Once you're connected, you should be able to ssh into the Pi with:
+* `ssh [email protected]` (default password is **alarm**).
+
+**NOTE:** The network interface used for the connection on the Pi is `usb0`. 

doc/FAQ.md

@@ -0,0 +1,26 @@
+# USB Ninja
+## FAQ
+
+**1. What are the login details to the default acccounts?**
+
+The standard user account (and the only one accessible to `ssh`) is `alarm:alarm`. The root account is `root:root`.
+
+**2. Why are you using Arch Linux ARM instead of Raspbian?**
+
+Apart from the obvious meme points (btw, I use arch), I found that I could get the boot time down much lower on _ALARM_ than on Raspbian.
+
+**3. I'm changing settings in `options.txt`, but they aren't making any difference when I reboot the Pi!**
+
+First of all, make sure you're formatting the `options.txt` file in the way specified in [README.md](../README.md). If you're sure you aren't breaking any rules (if you do, it'll ignore your choices and use the defaults), then you might be having trouble actually saving the file. If you're accessing `options.txt` from the USB Ninja itself (i.e. through `ssh` or the serial gadget), then make sure you run `sync` before rebooting or power-cycling otherwise the cached data might not get written to disc properly. In general, its advisable to power off the USB Ninja, remove the MicroSD from the board and mount the first partition on another computer to edit `options.txt` on there instead. The same goes for `hid.txt`.
+
+**4. I'm using the `hid_payload` gadget, but my strings aren't `PRINT`ing properly!**
+
+This is most likely due to incompatible keyboard layouts. The issue lies in the fact that the scan codes sent as HID packets by the USB Ninja correspond to _physical keys_ and **not** _characters_. This is down to the way keyboards work and not something that can be directly controlled. The solution is to either wait for me or someone else to add multiple layout support, or to add it yourself (and send me a pull request!).
+
+**5. I'm trying to use the `ethernet` gadget, but Windows won't recognise the adapter!**
+
+As detailed on the [ethernet](ETHERNET.md) page, the `ethernet` gadget is just an alias for `ethernet_ecm` which is *not* supported by Windows (but is supported by everything else). To resolve the issue, use the `ethernet_rndis` gadget instead.
+
+**6. I'm trying to use multiple gadgets at once, but it isn't working!**
+
+Multiple gadget support is currently still in testing. As far as I have seen - it seems to work just fine, but if you've found a combination that doesn't work as expected (and you have reason to think it should), then please raise an issue on this repo.

doc/GADGETS.md

@@ -0,0 +1,18 @@
+# USB Ninja
+## Gadgets
+
+Gadgets are configured by editing the `gadget: ` line in `/boot/usbninja/options.txt`. Currently, multiple gadget support is still in testing (see [FAQ](FAQ.md) number 6.), but it seems to work very well. You can specify multiple gadgets by separating them with commas.
+
+**E.g.** `gadget: serial, storage, ethernet_ecm`
+
+### USB-To-Serial Adapter
+To use the USB-To-Serial gadget, set `gadget` to `serial` in `options.txt`. A TTY will be made available via `/dev/ttyGS0` on the USB Ninja which shows up as `/dev/ttyACM0` on the (Linux) host. If using Windows, you can use [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html). Either way, ensure that the baud rate is set to `115200`. See [SERIAL.md](SERIAL.md) for more information.
+
+### USB-To-Ethernet Adapter
+To use the USB-To-Ethernet gadget, you can use either `ethernet_ecm` or `ethernet_rndis`. (Simply using `ethernet` will default to `ethernet_ecm`). To make a long story short, use `ethernet_rndis` for Windows and `ethernet_ecm` for everything else. See [ETHERNET.md](ETHERNET.md) for more information.
+
+### HID Payload
+To parse the `/boot/usbninja/hid.txt` and send the keystrokes contained within it as HID packets, use the `hid_payload` gadget. The format of `hid.txt` is very simple and straightforward - see [HID.md](HID.md) for more information.
+
+### Mass Storage
+The mass storage gadget is activated by including `storage` on the `gadget: ` line in `options.txt`. It makes the image in `/lib/usbninja/storage.img` available as a mass storage device to the host. For details on how to change the default image (only 64MB) and more, see [STORAGE.md](STORAGE.md).

doc/HID.md

@@ -0,0 +1,77 @@
+# USB Ninja
+## HID Gadget
+
+There is currently only one HID gadget available: `hid_payload`, although others are in the works. It emulates a keyboard in a similar way to the [USB Rubber Ducky](https://hakshop.com/products/usb-rubber-ducky-deluxe). The main file of importance is `/boot/usbninja/hid.txt` (accessible on partition one of the MicroSD card). The format is very similar to (and indeed heavily influenced by ) Hak5's `DuckyScript`. In fact, any DuckyScript file should also work with the USB Ninja, but some of the more advanced functions (like looping) are yet to be implemented and will simply be ignored.
+
+### Example `hid.txt`
+The following will open `notepad.exe` on Windows and type "Hello, World!". As you can see, it is very straightforward.
+```
+DELAY 5000
+GUI r
+DELAY 1000
+PRINT notepad
+ENTER
+DELAY 1000
+PRINT Hello, World!
+```
+
+### Supported Instructives
+"Instructives" are the name given to the first word of each line in `hid.txt`. Anything not listed here will simply be ignored, so commenting your payloads becomes trivial!
+
+Below are currently supported instructives:
+```
+DELAY <int>  # Sleep for <int> many milliseconds.
+PRINT <str>  # Type out <str>, see further down for the supported characters.
+ENTER        # Press the ENTER key. Aliased by "RETURN".
+ESC          # Press the ESC key.
+DEL          # Press the DEL key.
+TAB          # Press the TAB key.
+SPACE        # Press the SPACE bar.
+CAPS         # Press the CAPS LOCK button.
+F1-F12       # Press one of the function keys F1-F12.
+PRNTSCRN     # Press the PRINTSCREEN key.
+SCROLLOCK    # Press the SCROLL LOCK key.
+PAUSE        # Press the PAUSE key.
+INSERT       # Press the INSERT key.
+HOME         # Press the HOME key.
+PGUP         # Press the PAGE UP key.
+PGDWN        # Press the PAGE DOWN key.
+END          # Press the END key.
+RIGHT        # Press the RIGHT arrow key.
+LEFT         # Press the LEFT arrow key.
+UP           # Press the UP arrow key.
+DOWN         # Press the DOWN arrow key.
+CLEAR        # Press the CLEAR key.
+VOLUP        # Press the Volume Up button.
+VOLDOWN      # Press the Volume Down button.
+
+CTRL <key>   # Press CTRL + <key>
+ALT <key>    # Press ALT + <key>
+GUI <key>    # Press GUI + <key>
+SHIFT <key>  # Press SHIFT + <key>
+```
+
+### Some important points about ``CTRL``, ``ALT``, ``GUI`` and ``SHIFT``
+The ``CTRL``, ``ALT``, ``GUI`` and ``SHIFT`` keys are known as _modifiers_ and can be coupled together like ``CTRL ALT DEL`` and ``CTRL SHIFT ENTER``. In fact, you could even have all four as in ``CTRL ALT SHIFT GUI a``, if you really wanted to.
+
+**NOTE:** The order of the modifiers is _**irrelevant**_. ``CTRL ALT DEL`` is exactly the same as ``ALT CTRL DEL``. The only requirement is that the _key_ (i.e. not one of the modifiers) is the last word on the line.
+
+**E.g.** ``CTRL ALT DEL`` and ``ALT CTRL DEL`` are fine (and equivalent!) but ``CTRL DEL ALT`` is not!
+
+### Supported characters
+When using the `PRINT` instructive, it may be useful to have a list of the currently supported characters.
+```
+A-Z
+a-z
+0,1,2,3,4,5,6,7,8,9
+! " # $ % ^ & * ( ) _ + - =
+[ ] ; ' , . / { } : @ ~ < > ?
+| \ ` ¬
+```
+
+**NOTE:** Support for multiple keyboard layouts is currently in development. Currently it defaults to `en_US`, so even though I have an `en_GB` keyboard, the key that reads "£" (`SHIFT + 3` usually) actually outputs "#".
+
+### Technical Details
+In [extra.go](../src/extra.go), a map `hex_codes` is defined which contains all the mappings for each key (bar a select few). It's here that all the "translation" is done when we parse through `hid.txt` and lookup each character in the string following a `PRINT` instructive. If a line in `hid.txt` doesn't start with the `PRINT` instructive, then the parser will check to see if the leading word exists in `hex_codes`.
+
+Once the `hex_code` is looked up then the `hid_packet` is built as an array of strings. Eventually this HID packet will be echoed out to `/dev/hidg0`.

doc/SERIAL.md

@@ -0,0 +1,14 @@
+# USB Ninja
+## Serial Gadget
+
+The `serial` gadget is the simplest gadget on the USB Ninja platform. By default, a TTY is made available over the connection and is the quickest way to get started. The default login is `alarm:alarm` and the root account is `root:root`.
+
+On Linux and MacOS, you can connect to the TTY with either `screen`, `minicom` or some other program. Personally, I prefer `minicom`.
+* `screen /dev/ttyACM0 115200`
+* `minicom -b 115200 -D /dev/ttyACM0`
+
+**NOTE:** You'll probably need root to be able to open the `/dev/ttyACM0` file.
+
+On Windows, you can use [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) to connect. Just make sure the baud-rate is set to `115200` and you should be good to go!
+
+Once you're connected, you can set up [WiFi](WIFI.md) for easier SSH access or whatever you want! The image contains a full [Arch Linux](https://archlinuxarm.org/) install, so you can treat it like any other system.

doc/STORAGE.md

@@ -0,0 +1,4 @@
+# USB Ninja
+## Storage Gadget
+
+Coming Soon.

doc/SUPPORTED.md

@@ -0,0 +1,6 @@
+# USB Ninja
+## Confirmed Supported Devices
+* Raspberry Pi Zero W
+
+## Confirmed Unsupported Devices
+* Raspberry Pi 1-3

doc/WIFI.md

@@ -0,0 +1,10 @@
+# USB Ninja
+## WiFi Setup
+
+Setting up WiFi is very easy and also very useful if you're preparing a more advanced attack using the USB Ninja.
+
+1. Start the USB Ninja in `serial` mode by ensuring that `/boot/usbninja/options.txt` contains the line `gadget: serial`.
+2. Connect to the serial interface in your preferred manner. See the [serial](SERIAL.md) page for more details.
+3. Once you're in, run `sudo wifi-menu` and follow the prompts to connect to your wireless access point.
+4. Check your new local IP with `ifconfig wlp6s0`.
+5. Now you can disconnect from the serial interface and `ssh` into the USB Ninja over your wireless LAN