{"id":16590863,"url":"https://github.com/qlyoung/armory-keyboard","last_synced_at":"2025-03-23T14:31:07.864Z","repository":{"id":78556233,"uuid":"58830479","full_name":"qlyoung/armory-keyboard","owner":"qlyoung","description":"utility for emulating a USB HID keyboard with the USBArmory","archived":false,"fork":false,"pushed_at":"2018-03-01T06:50:55.000Z","size":201,"stargazers_count":40,"open_issues_count":2,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-15T03:44:15.815Z","etag":null,"topics":["duckyscript","keyboard","usb-hid","usb-rubber-ducky","usbarmory"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qlyoung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-14T21:06:00.000Z","updated_at":"2025-01-31T03:43:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"52a80c27-fd1c-44e1-b213-34e595a7c62e","html_url":"https://github.com/qlyoung/armory-keyboard","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qlyoung%2Farmory-keyboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qlyoung%2Farmory-keyboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qlyoung%2Farmory-keyboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qlyoung%2Farmory-keyboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qlyoung","download_url":"https://codeload.github.com/qlyoung/armory-keyboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245115717,"owners_count":20563215,"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":["duckyscript","keyboard","usb-hid","usb-rubber-ducky","usbarmory"],"created_at":"2024-10-11T23:14:36.091Z","updated_at":"2025-03-23T14:31:07.849Z","avatar_url":"https://github.com/qlyoung.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"armory-keyboard\n===============\n\nUtility for emulating a USB HID keyboard with the USBArmory.  Kind of\ncompatible with DuckyScript.\n\n[![asciicast](https://asciinema.org/a/45712.png)](https://asciinema.org/a/45712)\n\nBuilding\n--------\n```shell\n$ git clone https://github.com/qlyoung/armory-keyboard.git\n$ cd armory-keyboard\n$ make\n```\n\nThe resultant binary is located in `build/`.  You must build on the USBArmory\nor cross-compile.\n\nUsage\n-----\nFirst, setup your USBArmory to emulate a USB HID keyboard, either\nmanually through ConfigFS or by executing the provided shell script `hid-ecm.sh`\n(written by Collin Mulliner). The script expects to be running on the Debian\nJessie base image provided by Inverse Path, but should be easily adaptable to\nother images.\n\nSetting up HID Keyboard + CDC Ethernet:\n\n```\n# ./hid-ecm.sh\n```\n\nUsing the utility:\n\n```\n# ./type -s \u003cscript file\u003e -l \u003clayout file\u003e [-o \u003coutput file\u003e]\n```\n\nThe interpreter will interpret the script and send the generated HID reports to\nthe specified file. In the typical use case, this will be a HID character\ndevice such as `/dev/hidg0`. If no device is specified, the default is\n`/dev/hidg0`.\n\nScripts\n-------\nOriginally, the interpreter was going to be compatible with\n[DuckyScript](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Duckyscript).\nHowever, DuckyScript has weird and unnecessary limitations that don't really\ncorrespond to the capabilities of HID, so instead I opted with a syntax based\nmostly on DuckyScript with a few modifications to enhance capability and\nease-of-use. It should be fairly straightforward to convert DuckyScripts\nto...uh...ArmoryDuckyScripts? We'll go with that.\n\nSyntax is identical to DuckyScript, with the following exceptions:\n\n* `CTRL-ALT`+key, `CTRL-SHIFT`+key, `ALT`+key, `SHIFT`+key, `CTRL`+key, and\n  `GUI`+key combinations have all been replaced by a single keyword, `SIMUL`.\n  Start a line with `SIMUL` and follow it with up to 6 space-delimited tokens or\n  plaintext characters and all 6 will be sent in one HID report, as if they were\n  pressed at the same time. Take `CTRL+ALT+DEL` as an example:\n\n  DuckyScript: `CTRL-ALT DELETE`\n\n  ArmoryDuckyScript: `SIMUL CTRL ALT DELETE`\n\n  This seems more verbose at first, but it's actually better, because you can\n  do things with it that you can't really do in DuckyScript, such as:\n\n  `SIMUL CTRL ALT ENTER SPACE MENU a `\n\n  I have no idea why you would want to do this, but HID supports sending up to\n  6 keys per report, so I pass that option along to the user. Obviously it is up\n  to you to send sane combinations, and up to the operating system to interpret\n  them.  Note: all escape tokens (`SHIFT`, `CONTROL`, `SPACE`, etc) must occur\n  before any plaintext characters.\n\n* I haven't finished implementing all the syntax yet. Currently unimplemented\n  are:\n\n  * `REPEAT`, to repeat commands\n  \n  * `COMMAND` for OSX\n\n* Lines may be at most 500 characters. Excess characters will be ignored.\n\n* `DEFAULT_DELAY` may occur at any point in the script, and overrides the\n  previous default delay.\n\nExamples are located in the `examples/` directory.\n\nSee the\n[DuckyScript](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Duckyscript)\nwiki for further documentation on syntax.\n\nLayouts\n-------\nSupport for Unicode and arbitrary keyboard layouts was added in [c0e032c](https://github.com/qlyoung/armory-keyboard/commit/c0e032cd852b6b31bd2638d798e727915d035cdc). Layout files may be specified with the `-l` option. The format of a layout file is as follows:\n\n```\n-*- layout: \u003clayout name\u003e -*-\n\n\u003cunicode char\u003e 0x\u003ckeycode\u003e 0x\u003cmodifier bitfield\u003e\n\u003cunicode char\u003e 0x\u003ckeycode\u003e 0x\u003cmodifier bitfield\u003e\n\u003cunicode char\u003e 0x\u003ckeycode\u003e 0x\u003cmodifier bitfield\u003e\n...\n```\n\nThe first line must contain the string `-*- layout: ` followed by a name for the layout. The terminating `-*-` is not strictly necessary.\nSubsequent lines must contain the following, in order:\n\n 1. A UTF-8 character\n 2. Unicode/ASCII space (`0x20`)\n 3. The string `0x` followed by the hexadecimal keycode for the key that should be pressed to produce (1)\n 4. Unicode/ASCII space (`0x20`)\n 5. The string `0x` followed by the hexadecimal bitfield specifying which modifier keys must be pressed in tandem with (3) to produce (1)\n\nHere is a brief excerpt of the English/US layout:\n```\n-*- layout: English 103P (USA) -*-\n\na 0x04 0x00\nb 0x05 0x00\nc 0x06 0x00\nd 0x07 0x00\ne 0x08 0x00\nf 0x09 0x00\n```\n\nAnd of the Albanian 452 layout:\n\n```\n-*- layout: Albanian 452 -*-\n\n` 0x35 0x00\n¬ 0x35 0x02\n| 0x35 0x40\n1 0x1E 0x00\n! 0x1E 0x02\n2 0x1F 0x00\n```\n\nFor 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.\n\n![keycode mappings for standard keyboard](https://raw.githubusercontent.com/qlyoung/armory-keyboard/master/layouts/keyboard-layout.png)\n\n\n\nContributing\n------------\nFork \u0026 PR! Open to improvements and bugfixes (there\nare almost certainly bugs).\n\nWishlist / Planned Features:\n* HID support for [libusbgx](https://github.com/libusbgx/libusbgx)\n* ~~International layout support~~\n\nLicense\n-------\n```\nCopyright 2016  Quentin Young\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free Software\nFoundation, either version 3 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nthis program.  If not, see http://www.gnu.org/licenses/.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqlyoung%2Farmory-keyboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqlyoung%2Farmory-keyboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqlyoung%2Farmory-keyboard/lists"}