Payloads

While the Key Croc may act as an ordinary passive keylogger, silently recording keystrokes to log files or streaming them in real time over the Internet to a Cloud C2 server – it's strength as a pentest implant lies in its payload capabilities.

Payload Primer

Payloads may perform a number of functions, from automated keystroke analysis to notifying the pentester of a matching key sequence to performing advanced active attacks against the target by emulating multiple trusted USB devices.

Similar to the Bash Bunny, the Key Croc payload framework builds on the versatility of Bash, while providing simple helpers as part of the Key Croc language to facilitate basic functions. These functions include pattern-matching for payload execution, saving keys before and after the pattern is matched, injecting keystrokes into the target, emulating additional USB devices like Ethernet, serial and USB mass storage, and controlling the multi-color LED.

The section on Payload Development in this documentation includes a comprehensive guide to these functions, as well as best practices and tips for writing, testing and publishing payloads.

Payload Execution

Most payloads feature a MATCH command, which specifies which keystrokes should trigger the execution of the payload. The MATCH can be either a simple string such as "MATCH hello" – which will trigger when the target types "hello" – or a complex regular expression like "MATCH [0-9]{5}(?:-[0-9]{4})?" – which will trigger when the target types anything that matches the conventions used to represent an American ZIP (postal) code.

The MATCH which triggers a payload is identified from a buffer which is stripped of the backspace keys – meaning that in our "MATCH hello" example, the payload would trigger in both instances where the target typed "hello" exactly, as well as in the event that the user typed "helo" followed by the backspace key, then "lo" to fix the typo and complete the word "hello".

In addition to handling backspace, a combination of intelligent buffers automatically accounts for target typos and any control or modifier key – giving the payload the best chance of MATCH detection and execution. 

Rather than pattern matched execution, a payload may execute on boot by omitting the MATCH command. 

Where to get Payloads

Example payloads illustrating some of the functionality of the Key Croc can be found from the library directory on the udisk.

Additionally, Hak5 hosts a forum and software repository home to many community contributed payloads which may be downloaded for your convenience fromhttps://github.com/hak5/keycroc-payloads

How to Activate Payloads

Payload files, named with either .txt or .sh file extensions, will be activated if they reside in the payloads directory on the udisk. Simply put, copying an example payload file from the library folder to the payload folder will activate the payload the next time the Key Croc is booted (or if the RELOAD_PAYLOADS command is run).

Payloads may also be activated by using the ENABLE_PAYLOAD command. See this article.

How to Deactivate Payloads

Similar to activation, a payload may be deactivated by moving it from the payloads directory on the udisk. 

Additionally, if a payload contains "DISABLED." at the beginning of its file name, it will not be executed when its MATCH is detected.

Payloads may also be deactivated by using the DISABLE_PAYLOAD command. See this article.

How to Submit Payloads to the Hak5 Payload Repository

Payloads may be submit to the Hak5 Payload Repository by submitting a pull request to the appropriate repository. For the Key Croc, please follow the payload style guide described at https://github.com/hak5/keycroc-payloads/blob/master/README.md

Loot

In classic Hak5 fashion, the recorded keystrokes and other log files saved on the Key Croc can be found in the loot directory on the udisk. Payloads may save additional logs and other data to this loot directory. The Key Croc keylogging system saves two files by default:

• croc_raw.log – these are the recorded keystrokes in scan code format
• croc_char.log – these are the recorded keystrokes in a human readable format derived from keymap language file specified by DUCKY_LANG in config.txt

Additionally, the payload framework will save a log entry to a matches.log file every time a payload is executed by a pattern match.

Technical note: While in Attack Mode, logs and optionally other data from additional payloads are written to /root/loot. When entering Arming Mode, the contents of /root/loot are synchronized with the loot directory on the USB Flash Disk at /root/udisk/loot. See the guide on Understanding the Key Croc file system for more technical details on this special consideration.