Automation Unleashed - Boost productivity with Bad-BT

DuckyScript for Automation: Using Bad-BT as a Productivity Tool

Bad-BT is the BLEShark Nano's Bluetooth HID injection feature. In security research, it is used to test whether a computer responds to unauthorized keyboard input - a legitimate and important thing to test. But HID injection is not inherently an attack technique. It is fundamentally just automated keyboard input, and automated keyboard input is a category of tool that people have used productively for decades.

This article is about the automation use case: using DuckyScript payloads on the BLEShark Nano ($36.99+) to reduce repetitive typing work. The key concept here is consent. Running a DuckyScript on your own machine, to automate your own workflows, is exactly the same thing as using any other automation tool. The only thing that makes HID injection a security concern is doing it to a machine without authorization.

Table of Contents

What DuckyScript Is

DuckyScript is a scripting language originally created by Hak5 for the USB Rubber Ducky - a USB device that plugs into a computer and acts as a keyboard. The language is designed to describe keyboard input sequences: which keys to press, in what order, with what timing between them.

The language is simple by design. Its purpose is to describe what a person would type, not to build complex programs. Most DuckyScript payloads are short - under 20 lines for most practical tasks. The commands map directly to keyboard operations: press a key, type a string, wait for an application to open, send a keyboard shortcut.

The BLEShark Nano implements DuckyScript for Bad-BT, which works over Bluetooth instead of USB. The syntax is close to standard DuckyScript with some additions specific to the BLEShark firmware.

Bad-BT on the BLEShark Nano

sequenceDiagram
    participant User as User
    participant Nano as BLEShark Nano
    participant BLE as BLE 5.0
    participant Target as Target Computer
    participant OS as Target OS

    User->>Nano: Write DuckyScript payload
    User->>Nano: Upload via file portal or editor
    Nano->>BLE: Start BLE HID advertising
    BLE->>Target: Device discovered: keyboard
    Target->>Nano: BLE pairing accepted
    Note over Nano,Target: HID connection established
    User->>Nano: Trigger payload execution
    Nano->>Nano: Parse DuckyScript line by line
    Nano->>Target: HID Report: GUI r (open Run)
    OS->>OS: Run dialog opens
    Nano->>Nano: DELAY 500ms
    Nano->>Target: STRING powershell -ep bypass
    OS->>OS: Types characters at HID speed
    Nano->>Target: HID Report: ENTER
    OS->>OS: PowerShell launches
    Nano->>Target: STRING Get-NetAdapter | ft
    Nano->>Target: HID Report: ENTER
    Note over OS: Command executes

Bad-BT payload execution sequence - from DuckyScript parsing to keystroke injection over BLE HID

Bad-BT works by having the Nano present itself as a Bluetooth HID keyboard during pairing. Once paired and connected, the Bad-BT app executes a loaded DuckyScript payload - typing the configured sequence as if a person were sitting at the keyboard.

The fundamental requirement: the target computer must pair with the Nano. Bluetooth HID pairing is an interactive process - on most operating systems, the user sees a pairing prompt and either confirms a numeric code or accepts the pairing. This is a security feature, and it is also exactly why Bad-BT's security testing value is limited compared to a USB Rubber Ducky for unauthorized access: an attacker cannot silently pair over Bluetooth the way they can silently plug in a USB device. The pairing step requires user interaction.

For personal automation, this is fine. You pair the Nano to your own machine once. The device stores the pairing, and on subsequent connections, it reconnects automatically without a new pairing prompt. Your automated payloads run on your machine, with your consent, without interruption.

Core DuckyScript Commands

These are the commands you use most often for automation scripts:

DELAY

DELAY 1000

Wait for the specified number of milliseconds before continuing. Essential for giving applications time to open or respond. Most automation failures come from insufficient delays - applications need time to be ready to receive input.

STRING

STRING hello world

Types the given text character by character. Handles letters, numbers, symbols, and spaces. The Nano translates each character to the appropriate HID key code and sends the reports in sequence.

ENTER

ENTER

Sends the Enter/Return key. Equivalent to pressing the Enter key on a physical keyboard.

Modifier Keys

CTRL c
CTRL ALT t
GUI r

Key combos. The modifier comes first, then the key. Multiple modifiers stack: CTRL SHIFT t. GUI refers to the Windows key on Windows or Command on macOS.

Special Keys

TAB
BACKSPACE
DELETE
ESCAPE
UPARROW
DOWNARROW
LEFTARROW
RIGHTARROW
HOME
END
PAGE_UP
PAGE_DOWN
F1 through F12
SPACE
PRINTSCREEN

REM

REM This is a comment - ignored at runtime

Comments for documentation. Ignored during execution.

REPEAT

REPEAT 5

Repeats the previous command the specified number of times. Useful for navigating down a list with arrow keys or pressing Tab to move through a form.

Automation Examples

Open a Terminal (Windows)

REM Open Windows Terminal or Command Prompt
GUI r
DELAY 500
STRING cmd
ENTER
DELAY 800

GUI+R opens the Run dialog. Typing "cmd" and pressing Enter opens a Command Prompt. The delays give the dialog and terminal time to open before the next command runs.

Open a Terminal (macOS)

REM Open Terminal on macOS
GUI SPACE
DELAY 600
STRING Terminal
DELAY 400
ENTER
DELAY 1000

CMD+Space opens Spotlight. Typing "Terminal" and pressing Enter launches it.

Navigate to a Specific URL

REM Open browser to internal tool
GUI r
DELAY 500
STRING https://internal-dashboard.company.local
ENTER

On Windows, Run (GUI+R) can directly open URLs in the default browser. On macOS, this approach is slightly different - you would use CMD+Space and Spotlight, or use a shortcut that opens the browser directly.

Fill a Standard Form Entry

REM Fill standard testing form
REM Assumes form is already focused in browser
STRING John Doe
TAB
STRING jdoe@testaccount.example
TAB
STRING TestPassword123
TAB
ENTER

Tabs through form fields and fills in test data. Useful for QA testing where you repeatedly enter the same test credentials or data patterns. Never use real credentials in a DuckyScript payload.

Lock the Workstation

REM Lock screen immediately
GUI l

Single key combo. Useful mapped to a physical button on the Mini Keypad - physically press a button on the Nano and the workstation locks.

Open a Development Environment

REM Launch VS Code and open project
GUI r
DELAY 500
STRING code C:\Users\user\projects\myproject
ENTER

Opens VS Code directly in a specific project directory from the command line. Adjust the path for your system. Useful on a development machine where you always start sessions in the same project.

Repeated Test Input

REM Send test string 10 times
STRING test-input-string
ENTER
REPEAT 9

REPEAT applies to the line above it. This sends "test-input-string" and presses Enter 10 times total. Useful for filling test data or simulating repeated input in an interface you're testing.

Screenshot and Save

REM Take screenshot and save via Snipping Tool (Windows 11)
GUI SHIFT s
DELAY 2000
REM User captures region, then save dialog opens automatically

GUI+SHIFT+S opens the Windows Snipping Tool. After the user captures a region, the save workflow continues. This shows a hybrid approach where DuckyScript starts an operation and the user completes it.

Uploading and Running a Payload

The BLEShark Nano's file portal lets you upload DuckyScript files directly. The portal is accessible via the device's hosted access point or from your network when WiFi Connect is configured.

  1. Connect to the BLEShark Nano's access point or its configured WiFi network.
  2. Navigate to the file portal URL shown on the OLED.
  3. Upload your DuckyScript file (plain .txt format).
  4. On the Nano, navigate to Bad-BT from the main menu.
  5. Select your uploaded script.
  6. Make sure the target machine has the Nano paired as a Bluetooth keyboard.
  7. Press the trigger button on the Nano to execute.

The file portal also handles download - pull scripts off the device to back them up or edit them. The portal supports the same files you would expect: DuckyScript payloads, captive portal HTML, device settings JSON, PCAPs from handshake capture, and custom WiFi network lists.

The On-Device DuckyScript Editor

In addition to uploading scripts via the file portal, the BLEShark Nano (v1.0.0+) includes an on-device DuckyScript editor. You can write and modify scripts directly from the device's menu using the buttons to navigate a character input interface. This is particularly useful for quick edits in the field without needing to connect to the file portal.

The on-device editor stores scripts in the device's flash memory. Edited scripts persist across reboots. For complex scripts, the file portal approach is faster - typing via button navigation is slow. For short scripts or quick modifications to an existing payload, the on-device editor is convenient.

Where This Makes Sense

Bad-BT for automation is most useful in situations where:

  • You perform the same multi-step keyboard sequence repeatedly, and the steps cannot be automated by the target application's own macro system
  • You need automation that works across different applications simultaneously (opening a terminal while a browser window is in focus, for example)
  • You want physical button activation rather than a software hotkey (useful when you are not at the keyboard)
  • You are doing QA testing and need to repeatedly enter test data into forms or CLI tools
  • You want to demonstrate what HID injection looks like in a security training context - running a harmless script on a test machine shows students the technique concretely

It is less useful when the application you are automating already has a macro or scripting system (most IDEs, browsers, productivity tools). In those cases, native automation is faster and more reliable. Use DuckyScript where native automation is unavailable or impractical.

Limitations and Considerations

Timing Sensitivity

DuckyScript payloads depend on timing. A DELAY that works on a fast machine might be too short on a slower one. If you run the same script on different computers, you may need to adjust delays. Add conservative delays when writing scripts intended for varied hardware - a few extra hundred milliseconds of delay rarely matters, but too-short delays cause script failures that can be hard to debug.

Keyboard Layout

DuckyScript sends HID key codes, not characters. The character that appears on screen depends on the keyboard layout configured in the OS. A STRING command with "hello" on a US layout machine produces the correct output. On a French (AZERTY) layout, the same HID codes produce different characters because the key-to-character mapping is different in the OS.

When running scripts on machines with non-US keyboard layouts, either configure the OS to use US layout before running, or adjust your script to use the key codes that produce the desired characters on the target layout.

Bluetooth vs USB

USB Rubber Ducky payloads run at USB HID speeds - very fast. Bluetooth HID has higher latency. Add more generous delays in your BLEShark DuckyScript payloads compared to what USB equivalents use. Most automation tasks are not time-sensitive to the millisecond, so this is rarely a practical limitation, but it is worth knowing when porting payloads written for USB devices.

BLE and Shiver Mesh

The BLEShark Nano's ESP32-C3 radio handles BLE and the Shiver mesh networking protocol (ESP-NOW) using the same hardware. Mesh communication between nodes runs over ESP-NOW - Espressif's connectionless WiFi protocol. BLE is used only for the initial pairing step; once paired, the radio operates exclusively in ESP-NOW mode. In a multi-node Shiver setup, this is easy to plan around: one device handles Bad-BT duty while the others maintain the mesh. Bad-BT is a single-device, targeted operation by nature anyway.

Get the BLEShark Nano

Back to blog

Leave a comment