Payload Development

Key Croc payloads are easy to write with Ducky Script. They can be written in any standard text editor. From notepad on Windows to TextEdit on a Mac – even nano on Linux, the best text editor ever. These simple ascii files are processed by the Key Croc's payload framework. Payloads execute when the target types specified patterns of keystrokes. A payload can be as simple as saving keystrokes of interest, to an advanced array of attacks using multiple device emulation modes, complex pentest frameworks and specialized exploits.

Multiple payloads, each with a unique file name, may be loaded simultaneously from the Key Croc's udisk payloads folder.

In addition to Ducky Script, the Key Croc payloads are executed with bash. which means they can leverage this powerful shell scripting language. For example, conditional statements can be used to construct decision trees based on events, and text processing tools can be used to systematically extract typed key sequences of interest – storing them in variables for use later in the payload.

Payloads can take advantage of a number of Key Croc commands, in addition to the standard Linux tools, additional pre-installed tools like nmap and smbclient, or the optionally installed tools like metasploit, responder and impacket.

Payload Primer

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.

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.

Getting 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 from


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.

Managing Payloads

Enabling 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.

Disabling 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.

Last updated