Utility for emulating a USB HID keyboard with the USBArmory. Kind of compatible with DuckyScript.
$ git clone https://github.com/qlyoung/armory-keyboard.git $ cd armory-keyboard $ make
The resultant binary is located in
build/. You must build on the USBArmory
First, setup your USBArmory to emulate a USB HID keyboard, either
manually through ConfigFS or by executing the provided shell script
(written by Collin Mulliner). The script expects to be running on the Debian
Jessie base image provided by Inverse Path, but should be easily adaptable to
Setting up HID Keyboard + CDC Ethernet:
Using the utility:
# ./type -s <script file> -l <layout file> [-o <output file>]
The interpreter will interpret the script and send the generated HID reports to
the specified file. In the typical use case, this will be a HID character
device such as
/dev/hidg0. If no device is specified, the default is
Originally, the interpreter was going to be compatible with DuckyScript. However, DuckyScript has weird and unnecessary limitations that don't really correspond to the capabilities of HID, so instead I opted with a syntax based mostly on DuckyScript with a few modifications to enhance capability and ease-of-use. It should be fairly straightforward to convert DuckyScripts to...uh...ArmoryDuckyScripts? We'll go with that.
Syntax is identical to DuckyScript, with the following exceptions:
GUI+key combinations have all been replaced by a single keyword,
SIMUL. Start a line with
SIMULand follow it with up to 6 space-delimited tokens or plaintext characters and all 6 will be sent in one HID report, as if they were pressed at the same time. Take
CTRL+ALT+DELas an example:
SIMUL CTRL ALT DELETE
This seems more verbose at first, but it's actually better, because you can do things with it that you can't really do in DuckyScript, such as:
SIMUL CTRL ALT ENTER SPACE MENU a
I have no idea why you would want to do this, but HID supports sending up to 6 keys per report, so I pass that option along to the user. Obviously it is up to you to send sane combinations, and up to the operating system to interpret them. Note: all escape tokens (
SPACE, etc) must occur before any plaintext characters.
I haven't finished implementing all the syntax yet. Currently unimplemented are:
REPEAT, to repeat commands
Lines may be at most 500 characters. Excess characters will be ignored.
DEFAULT_DELAYmay occur at any point in the script, and overrides the previous default delay.
Examples are located in the
See the DuckyScript wiki for further documentation on syntax.
Support for Unicode and arbitrary keyboard layouts was added in c0e032c. Layout files may be specified with the
-l option. The format of a layout file is as follows:
-*- layout: <layout name> -*- <unicode char> 0x<keycode> 0x<modifier bitfield> <unicode char> 0x<keycode> 0x<modifier bitfield> <unicode char> 0x<keycode> 0x<modifier bitfield> ...
The first line must contain the string
-*- layout: followed by a name for the layout. The terminating
-*- is not strictly necessary.
Subsequent lines must contain the following, in order:
- A UTF-8 character
- Unicode/ASCII space (
- The string
0xfollowed by the hexadecimal keycode for the key that should be pressed to produce (1)
- Unicode/ASCII space (
- The string
0xfollowed by the hexadecimal bitfield specifying which modifier keys must be pressed in tandem with (3) to produce (1)
Here is a brief excerpt of the English/US layout:
-*- layout: English 103P (USA) -*- a 0x04 0x00 b 0x05 0x00 c 0x06 0x00 d 0x07 0x00 e 0x08 0x00 f 0x09 0x00
And of the Albanian 452 layout:
-*- layout: Albanian 452 -*- ` 0x35 0x00 ¬ 0x35 0x02 | 0x35 0x40 1 0x1E 0x00 ! 0x1E 0x02 2 0x1F 0x00
For your convenience, I compiled a map of keycodes for a standard keyboard. Characters for the English/US layout have been left in for readability, but regardless of what character is on a given key the keycode is the same. With this map and a little patience it is easy to add support for whatever keyboard layout you wish.
Fork & PR! Open to improvements and bugfixes (there are almost certainly bugs).
Wishlist / Planned Features:
- HID support for libusbgx
International layout support
Copyright 2016 Quentin Young This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.