Custom Payloads - Bad-BT for security testing

Writing a Custom Bad-BT Payload for Security Testing

The BLEShark Nano's Bad-BT feature ships with some built-in demo payloads, but the real power is in writing your own. A payload tailored to your specific test environment - the right OS, the right keyboard layout, the right delays for the target hardware - will be far more reliable than a generic example.

This tutorial walks through writing a complete, safe payload, loading it onto the BLEShark, pairing with a target machine, and executing it. The example payload opens a browser, navigates to a URL, and closes the tab. It demonstrates HID injection without doing anything harmful.

Table of Contents

Prerequisites

You need:

graph TD
    subgraph "1. Design Phase"
        A[Identify test objective] --> B[Choose target OS]
        B --> C[Map required keystrokes]
        C --> D[Write DuckyScript payload]
        D --> E[Add appropriate DELAYs]
    end
    subgraph "2. Upload Phase"
        E --> F[Connect to BLEShark WiFi AP]
        F --> G[Open File Portal in browser]
        G --> H[Upload .txt payload file]
        H --> I[Verify file on device]
    end
    subgraph "3. Execution Phase"
        I --> J[Pair Bad-BT with target]
        J --> K[Select payload from menu]
        K --> L[Execute payload]
        L --> M{Success?}
    end
    subgraph "4. Verification"
        M -->|Yes| N[Document findings]
        M -->|No| O[Check timing/OS differences]
        O --> D
        N --> P[Cleanup target machine]
    end

End-to-end Bad-BT payload workflow - from design through upload, execution, and verification

  • A BLEShark Nano with current firmware
  • A target machine (your own, or one you have written authorization to test)
  • The target machine's Bluetooth must be enabled
  • A text editor on your computer to write the payload
  • A WiFi connection to reach the BLEShark's file portal (or use the on-device editor)

For the tutorial example: the payload targets Windows. If you're on macOS or Linux, the OS-specific commands differ - the variations section covers those adjustments. Test on your own machine first before any authorized assessment scenario.

Designing the Payload

Before writing a single line of DuckyScript, write down in plain English what you want the payload to do. This forces you to think through the sequence and identify where delays are needed.

For our example: "Open the default browser and navigate to a specific URL to demonstrate that a browser can be opened and controlled via HID injection."

Step by step:

  1. Wait a moment (for Windows to settle after the Bluetooth connection)
  2. Open the Run dialog (Windows+R)
  3. Wait for the Run dialog to appear
  4. Type the browser command with the URL
  5. Press Enter to execute
  6. Wait for the browser to open
  7. Press F11 if full-screen would be demonstrative (optional)

That's the whole plan. Each step is either a keystroke or a delay. Now translate it to DuckyScript.

The Example Payload

REM ============================================
REM Bad-BT Demo Payload
REM Target: Windows 10/11
REM Layout: US QWERTY
REM Function: Opens browser to a URL
REM ============================================

REM Wait for BT connection to stabilize
DELAY 1000

REM Open Run dialog
GUI r
DELAY 800

REM Type the URL to open in default browser
STRING https://infishark.com
DELAY 300

REM Press Enter to open
ENTER
DELAY 3000

REM Done

This payload is about as simple as a useful Bad-BT demo can be. The 1000ms initial delay is important - when a Bluetooth keyboard connects, Windows takes a moment to recognize it and shift keyboard focus handling to the new device. Sending keystrokes immediately after connection can result in missed inputs.

The GUI r command (Windows key + R) opens the Run dialog. This works even if no application is in focus - it's a system-level shortcut that doesn't depend on desktop state.

The URL in the STRING command is fully typed using keyboard characters. The colon and forward slashes in "https://" are characters that the STRING command will type correctly on a US QWERTY layout. On a German keyboard layout, "/" is produced by Shift+7 and ":" by Shift+. - the STRING command would produce incorrect characters. Keyboard layout matters - always know your target.

The 3000ms delay after pressing Enter allows the browser to launch. On a fast machine this is generous; on a slow machine it might not be enough. Adjust based on what you observe during testing.

Uploading via the File Portal

  1. Save the payload text as a .txt file on your computer. Name it something descriptive: demo-open-browser.txt
  2. Power on the BLEShark Nano
  3. Connect to the BLEShark's WiFi network from your computer (SSID shown on the OLED at startup)
  4. Open a browser and navigate to the BLEShark's IP address (shown on OLED, typically 192.168.4.1)
  5. Navigate to the File Portal section
  6. Find the DuckyScript folder
  7. Click Upload and select your .txt payload file
  8. The file appears in the list when the upload completes

Your payload is now stored on the BLEShark. It persists in flash memory - it'll be there after power cycles, firmware updates (as long as the SPIFFS partition isn't wiped during update), and indefinitely until you delete it.

You can store multiple payloads and select between them in the Bad-BT menu. Name them clearly so you can identify the right one during an actual test. "demo-open-browser.txt" is more useful than "payload1.txt" when you have six payloads loaded and need to pick the right one quickly.

Pairing Bad-BT With the Target Machine

Bluetooth HID requires pairing before the device can send keystrokes. This step needs to happen before the assessment - you can't complete it silently or automatically without user interaction on the target machine.

On the BLEShark:

  1. Navigate to Bad-BT in the main menu
  2. Select "Pair Mode" or equivalent
  3. The BLEShark will advertise itself as a Bluetooth keyboard (it will show a device name on the OLED)

On the target Windows machine:

  1. Open Settings > Bluetooth and devices
  2. Click "Add device"
  3. Select "Bluetooth"
  4. Find the BLEShark in the device list (it will appear with the name shown on the BLEShark OLED)
  5. Click to pair - Windows will show a PIN or "Just Works" pairing prompt
  6. Confirm the pairing

Once paired, the BLEShark appears in the target's Bluetooth device list as a trusted keyboard. It will reconnect automatically in subsequent sessions without requiring the full pairing process again, as long as the pairing hasn't been deleted on either side.

The device name the BLEShark presents during pairing can be configured in device settings. Use a name that fits the context of your assessment - for a security awareness demonstration, using the actual "BLEShark Nano" name makes the demo more transparent. For a covert red team exercise, a name like "Microsoft Keyboard" might be chosen (with appropriate authorization).

Executing the Payload

With the BLEShark paired and your payload loaded:

  1. Navigate to Bad-BT in the BLEShark menu
  2. Select your payload from the list
  3. Confirm the selection
  4. The BLEShark connects to the paired device over Bluetooth
  5. Once the connection indicator shows connected, press the execution button
  6. Watch the target machine's screen as the payload executes

Position matters for Bluetooth range. BLE has a practical indoor range of roughly 10 meters, though walls and interference reduce this. For a demonstration, being in the same room ensures reliable execution. The BLEShark can trigger a payload while you're across the room, visible to the audience - which is often more demonstrative than being immediately next to the machine.

The payload executes in real time. You'll see the Run dialog open, the URL get typed character by character, and the browser open. This is the visual confirmation that HID injection is working.

Verifying Success

For our example payload, success is obvious: the browser opens and the URL is displayed. For more complex payloads that don't have immediate visible output, verification might require:

  • Checking a network log for outbound requests (if the payload opens a URL to your server)
  • Checking file system for created or modified files (if the payload writes files)
  • Checking process list for spawned processes
  • Checking clipboard contents if the payload copies data

For security demonstrations, always design payloads with visible confirmation built in. Opening a browser to a known URL, writing text to Notepad, or displaying a notification are all good confirmation mechanisms that make it clear to any observer what happened.

Troubleshooting Common Issues

Payload doesn't execute - nothing happens on screen: Bluetooth connection may have dropped. Check the BLEShark OLED for connection status. Move closer to the target machine. If the connection was dropped, navigate back to Bad-BT and reconnect before triggering again.

Run dialog opens but the URL is typed incorrectly: Keyboard layout mismatch. Verify the target machine's keyboard layout in Settings > Time and Language > Language. If it's not US QWERTY, the STRING command will produce wrong characters for symbols like / and :

Run dialog doesn't open: The 1000ms initial delay might not be enough. Increase it to 1500ms or 2000ms. Some Windows configurations with high DPI scaling or accessibility features take longer to respond to keyboard shortcuts after a new device connects.

Characters are missing from the URL: STRING is running too fast for the Bluetooth connection. Add a DEFAULT_DELAY 50 at the top of the payload to insert a 50ms pause between each typed character. This slows down the payload but prevents dropped characters.

Browser opens but shows a blank tab or error: The URL was typed incorrectly due to a transient error. Also check that the Run dialog actually typed the URL correctly before pressing Enter - add a 500ms pause before ENTER so you can see what was typed.

Adapting for Different OSes

macOS version of the same payload:

REM Bad-BT Demo - macOS
DELAY 1000
GUI SPACE
DELAY 700
STRING Safari
ENTER
DELAY 2000
GUI l
DELAY 500
STRING https://infishark.com
ENTER

This uses Spotlight (CMD+Space) to open Safari, then CMD+L to focus the address bar, then types the URL. Adjust the application name for Chrome or Firefox.

Linux (GNOME) version:

REM Bad-BT Demo - Linux GNOME
DELAY 1000
CTRL F2
DELAY 700
STRING firefox https://infishark.com
ENTER

Or use ALT+F2 for the run dialog on older GNOME versions.

Cleanup After Testing

After a Bad-BT demonstration or test, remove the pairing from the target machine. On Windows: Settings > Bluetooth and devices > find the BLEShark device > click the three-dot menu > Remove device. On macOS: System Settings > Bluetooth > hover over the device > click X to remove.

Also remove the payload from the BLEShark via the file portal if it was test-specific and not needed for future use.

Document what was tested, what executed successfully, and the conditions (OS version, security software present, keyboard layout, physical distance). This documentation is essential for turning a proof-of-concept demonstration into actionable security recommendations.

All payload examples in this article are for authorized security testing only. Unauthorized deployment of HID injection payloads is illegal. Always obtain explicit written permission before testing any system you don't own.

Get the BLEShark Nano - $36.99+

Back to blog

Leave a comment