Ducky Script Volume 1 — Overview: Keystroke Injection, the Device Family, and the Decision Tree — Ducky Script · Hacking

What a Ducky Script payload actually is, the HID trust model it abuses, the four Hak5 devices that run it, and how to read this 18-volume manual

Section	Topic
1	About this volume — and this manual
2	What Ducky Script is
3	The HID trust model — why this works at all
4	The two languages — 1.0 and 3.0
5	The device family — four ways to run a payload
6	What Ducky Script can and cannot do
7	The decision tree — which device for the job
8	Where the device family sits in tjscientist’s lineup
9	The posture warning
10	How to read this manual — depth indices
11	Resources

1. About this volume — and this manual

This is Volume 1 of an 18-volume engineer-grade users’ and programming manual for Ducky Script — Hak5’s keystroke-injection payload language — and the four Hak5 device families that run it, all four of which tjscientist owns: the USB Rubber Ducky, the Bash Bunny, the Key Croc, and the O.MG Cable / Plug / Adapter.

The manual is structured in three parts:

Part I — the language (Vols 1-7). What keystroke injection is, the HID trust model, the language across both its generations (the 1.0 macro language and the 3.0 structured language), the “smart payload” features, exfiltration, and the cross-locale keyboard-layout problem. If you read nothing else, read Part I — it is the conceptual and syntactic spine, and it applies to every device.
Part II — the devices (Vols 8-12). One first-class volume for each owned device family, plus the encode-and-deploy workflow. The four devices run the same language but are wildly different hardware — a microcontroller, two Linux boxes, and an ESP-based implant — and the deploy step differs for each.
Part III — payloads, operations, synthesis (Vols 13-18). A payload catalogue with worked examples, combined-device and combined-tool workflows (including staging a Ducky device alongside the WiFi Pineapple), the defensive view (how keystroke injection is detected), the operational/legal posture, a device-comparison “which one for the job” volume, and the laminate-ready cheatsheet.

Volume 1’s job is orientation: what Ducky Script is (§ 2-4), the four devices at a glance (§ 5), what the technique can and cannot do (§ 6), the decision tree for which device to reach for (§ 7), and a depth index into the other 17 volumes (§ 10).

2. What Ducky Script is

Ducky Script is the language you write keystroke-injection payloads in.

A keystroke-injection device — the archetype is the USB Rubber Ducky — is a small piece of hardware that, when connected to a computer, does not present itself as what it physically looks like (a flash drive, a charging cable, a USB adapter). It presents itself as a keyboard. It then “types” a pre-written script at machine speed — hundreds to nearly a thousand keystrokes per second, faster than any human, exactly as scripted, every time.

The script it types is a Ducky Script payload. You write it in a plain text file. You encode it (or, on some devices, just paste it into a web UI). The device replays it as keystrokes whenever it is connected — or, on the more advanced devices, whenever a condition is met.

That technique — a USB device pretending to be a keyboard to inject keystrokes — is HID injection, popularly called “BadUSB.” Ducky Script is the language layer on top of it. Hak5’s founder Darren Kitchen coined the technique in 2010, shipped the original USB Rubber Ducky that popularised it, and Hak5 maintains the language to this day. Kitchen’s original motivation was mundane: he was a sysadmin automating repetitive tasks — “fixing printers, network shares and the like” — and a USB device that could type a fix-it script into any machine was a labour-saver. The offensive-security use came later; the icon-of-hacker-culture status came later still.

   The whole idea, in one diagram
   ════════════════════════════════════════════════════════

   payload.txt          encode / deploy          the device
   ─────────────        ───────────────          ──────────
   you write       ──►  inject.bin on SD,    ──►  USB Rubber Ducky /
   Ducky Script         or pasted into a          Bash Bunny / Key Croc /
                        device web UI             O.MG implant
                                                       │
                                                       │ connected to
                                                       ▼
                                                 target computer
                                                       │
                              enumerates as a KEYBOARD (not a flash
                              drive, not a cable, not an adapter)
                                                       │
                                                       ▼
                              types the payload at machine speed —
                              the OS cannot tell it isn't a human

3. The HID trust model — why this works at all

The reason keystroke injection works is not a bug in any one operating system. It is a design assumption shared by every mainstream OS:

A keyboard is trusted implicitly. There is no authentication between a keyboard and the machine it is plugged into.

When you plug in a keyboard, the OS does not — cannot — ask “is this really a keyboard?” or “is this keyboard authorised?” There is no mechanism for it to. A keyboard is the most fundamental human-input device; the entire interactive use of a computer depends on the OS trusting it the instant it appears on the bus. The USB HID (Human Interface Device) class is deliberately simple and deliberately permission-free.

A keystroke-injection device exploits exactly that. It is a real USB HID keyboard, at the protocol level — there is nothing being faked, nothing for the OS to detect as fraudulent. It genuinely enumerates as a keyboard, it genuinely sends HID keyboard reports. The only thing “wrong” is that the entity pressing the keys is a 1-cm circuit board running a script, not a human.

   USB enumeration — the handshake the technique abuses
   ════════════════════════════════════════════════════════

   device                          host (target OS)
   ──────                          ────────────────
   "I am a USB device"      ──────► "ok, what are you?"
   "I am an HID keyboard,
    here's my descriptor"   ──────► "a keyboard — loaded the
                                     HID driver, you're trusted"
                                            │
   ┌─── no authentication step here ────────┘
   │    no 'is this keyboard authorised?'
   │    no user prompt, no allow-list check
   ▼
   "key: G"  "key: U"  "key: I"  ──►  the OS types it. faithfully.
   (or: GUI r → cmd → a reverse shell, in under two seconds)

This is the single most important idea in the whole manual, and Vol 16 (operational posture) and Vol 15 (defense & detection) both return to it:

It is not “malware” in the usual sense. It does not exploit a software vulnerability. There is no CVE to patch. It uses the machine exactly as designed.
Everything a payload can do is something the logged-in user could do by hand. A payload is an extremely fast, perfectly accurate typist — nothing more. It does not grant privileges the user doesn’t have (§ 6).
It cannot be “fixed” without changing the trust model. Defenses (Vol 15) work by adding the authorization step the USB spec never had — USB device control, HID allow-listing, behavioural detection of impossibly-fast typing. They are bolt-ons to a fundamentally trusting design.

[FIGURE SLOT — Vol 1, § 3] A diagram of the USB HID enumeration handshake — device announces “I am a keyboard,” host accepts, no authentication step, keystrokes flow. Source: authored diagram (the ASCII version above is the spec; an SVG version for the HTML build).

4. The two languages — 1.0 and 3.0

A reader hits this fact early and it matters: “Ducky Script” refers to two materially different languages, separated by twelve years and a hardware generation.

	Ducky Script 1.0 (2010)	Ducky Script 3.0 (2022)
Introduced with	the original USB Rubber Ducky (Mark I)	the new USB Rubber Ducky (Mark II)
Nature	a macro language — a linear list of “type this, wait this long”	a structured programming language
The whole language	two actions: keystroke injection + delay	all of 1.0, plus real programming
Logic	none — strictly top-to-bottom	`IF`/`ELSE`, `WHILE` loops, `FUNCTION`s
Data	none	`VAR` (unsigned ints 0-65535), full operator set
Awareness	none — types blind	reads OS (`$_OS`) + keyboard-lock state, branches on it
Stealth/evasion	none	jitter, randomization, VID/PID spoofing, `HIDE_PAYLOAD`
Exfiltration	not really	Keystroke Reflection — `EXFIL` to `loot.bin`
Attack modes	implicit (it’s a keyboard)	explicit `ATTACKMODE` — HID, STORAGE, OFF, combos

Ducky Script 1.0 is learnable in an afternoon — it is barely a language, closer to a macro format. Ducky Script 3.0 is a genuine (if small and domain-specific) programming language, and it is what makes a modern payload able to adapt: detect the target OS, pick the right command sequence, loop, branch, time itself to evade detection, and report data back.

Backward compatibility is clean: a Ducky Script 1.0 payload is valid Ducky Script 3.0 and runs unmodified on the Mark II. The reverse is not true — a 3.0 payload using VAR, IF, WHILE will not run on the 1.0-only Mark I.

Throughout this manual, every language-feature claim states which version it applies to. Vol 3 covers the 1.0 core; Vol 4 covers the 3.0 language proper; Vols 5-6 cover the 3.0 features that make payloads “smart.” The Bash Bunny, Key Croc, and O.MG run dialects — supersets or subsets with device-specific extensions — and Vols 9-11 cover each device’s deltas from the Rubber Ducky baseline.

5. The device family — four ways to run a payload

tjscientist owns all four Hak5 device families that run Ducky Script. They run the same language but are radically different hardware — and that hardware difference is the whole reason there are four of them. Each is a first-class volume in Part II.

Device	What it physically is	What it runs on	The distinguishing trait	Volume
USB Rubber Ducky	a “flash drive”	a microcontroller (Mark I: 60 MHz AT32UC3B1256; Mark II: faster, USB-C/A)	the canonical device — purest, fastest keystroke injection, nothing extra to get in the way	Vol 8
Bash Bunny	a chunky “flash drive”	a quad-core Linux box with an SSD	multi-vector — not just HID; `ATTACKMODE` emulates storage, serial, ethernet; full bash under the payload	Vol 9
Key Croc	an inline USB “adapter”	a quad-core 1.2 GHz ARM Linux box with 8 GB SSD + Wi-Fi	a keylogger first — it passes keystrokes through while logging them, and fires payloads when a typed keyword/regex matches	Vol 10
O.MG Cable / Plug / Adapter	a charging cable / wall plug / USB adapter	an ESP-based implant with Wi-Fi	covert form factor + remote, Wi-Fi-triggered payloads via a web UI; geo-fencing; USB passthrough so it still works as a cable	Vol 11

The shorthand:

USB Rubber Ducky — the reference. Plug it in, it types. Learn the language here.
Bash Bunny — the Swiss-army payload platform. When the job needs more than typing — exfil to its own storage, a fake ethernet adapter, a serial console — the Bunny is a Linux computer that also injects keystrokes.
Key Croc — the patient one. It is installed inline and waits. It logs everything typed, and when the target types a trigger word, the matched payload fires. The only one of the four built around observation.
O.MG — the invisible one. It looks exactly like a cable/plug/adapter the target already trusts, it still functions as one, and it is triggered remotely over Wi-Fi — or automatically by geo-fence. The covert-implant member of the family.

   The family, by what makes each one special
   ════════════════════════════════════════════════════════

                    pure speed,        USB Rubber Ducky
                    nothing extra  ───► "it just types, perfectly"

   keystroke   ───► multi-vector,       Bash Bunny
   injection        Linux underneath───►"types + storage + net + serial + bash"
   (the shared
    technique)      observe-then-       Key Croc
                    trigger        ───► "logs everything, fires on a keyword"

                    covert +           O.MG Cable/Plug/Adapter
                    remote/geo     ───► "looks like a cable, triggered over Wi-Fi"

[FIGURE SLOT — Vol 1, § 5] A family photo — the USB Rubber Ducky, Bash Bunny, Key Croc, and an O.MG Cable side by side, to scale. Source: shop.hak5.org product pages (page extractor) or tjscientist’s own units once photographed.

6. What Ducky Script can and cannot do

Can:

Type anything a keyboard can type, at machine speed — so: open a shell, run commands, change settings, disable defenses the logged-in user could disable, download and execute a file, paste in a whole script. A meaningful payload runs in one to a few seconds.
(3.0) Branch on the target OS, loop, use variables and arithmetic, call functions, time and randomize itself.
(Bash Bunny, Key Croc) Emulate non-keyboard devices too — mass storage, a serial port, a USB-ethernet adapter — and run a full Linux userland alongside the injection.
(3.0, O.MG, Bash Bunny, Key Croc) Exfiltrate data — Keystroke Reflection on the Rubber Ducky (Vol 6), or onto the device’s own storage / over its own network on the Linux devices.

Cannot:

Escalate privileges by itself. A payload runs as whoever is logged in. If that user is not an administrator, the payload is not either — it can only do what that user could do by hand. It is not an exploit; it is a typist. (A payload can attempt a privilege-escalation technique — running a known exploit, a UAC-bypass sequence — but that is the payload’s content doing it, not the injection itself, and it will succeed or fail exactly as it would if a human typed it.)
Do anything meaningful at a locked screen — beyond what a keyboard could do there, which is very little.
See the screen. A 1.0 payload types blind — it cannot tell whether the previous command worked, whether a window has focus, whether a dialog appeared. A 3.0 payload can read keyboard-lock-key state (CAPS/NUM/SCROLL — Vol 5-6) and the Linux devices can read more, but none of them read the screen. Robust payloads are written defensively because the device is typing blind (Vol 13).
Be a Wi-Fi/RF attack tool. That is the WiFi Pineapple’s and the ESP32-Marauder devices’ territory. Ducky Script is keystroke injection — though the Bash Bunny’s and O.MG’s networking, and combined-tool staging (Vol 14), blur the edge.

7. The decision tree — which device for the job

The four devices are not a good/better/best ladder — they are optimised for different engagement shapes. Vol 17 is the full comparison; this is the fast version.

   START: I need to run a keystroke-injection payload.
   │
   ├─ Do I have a few seconds of un-observed physical access,
   │  and the payload is "just type a thing"?
   │     └─► USB RUBBER DUCKY. The reference tool. Fastest,
   │         simplest, least that can go wrong.
   │
   ├─ Does the job need more than typing — exfil to the device,
   │  a fake network adapter, a serial console, multi-stage bash?
   │     └─► BASH BUNNY. It is a Linux computer that also injects.
   │
   ├─ Do I need to LEAVE the device installed and have it act
   │  later, when the target types something specific?
   │     └─► KEY CROC. Inline keylogger; payloads fire on a
   │         keyword/regex match. The "install and wait" device.
   │
   ├─ Does the device need to be INVISIBLE — to look like a
   │  cable/plug/adapter the target already trusts — and/or be
   │  triggered REMOTELY over Wi-Fi or by geo-fence?
   │     └─► O.MG CABLE / PLUG / ADAPTER. The covert implant.
   │
   └─ Just learning the language?
         └─► USB RUBBER DUCKY. Everything else is a dialect of it.

Where to start, for tjscientist specifically: the USB Rubber Ducky is the device to build fluency on first — it is the cleanest expression of the language, the other three run dialects of it, and skills transfer upward. Then the Bash Bunny (the most capable), then the Key Croc and O.MG for their specialised observe-and-implant roles.

8. Where the device family sits in tjscientist’s lineup

The Ducky Script device family is the hub’s physical-access attack capability. It is the same Hak5 family as the WiFi Pineapple (../WiFi Pineapple/) but covers an orthogonal surface:

The WiFi Pineapple attacks the wireless environment — from a distance, against the airspace, no physical contact with the target machine.
The Ducky Script devices attack a specific machine — by physically touching it (or socially engineering someone else into doing so, or leaving an implant behind).

A real physical-access engagement often stages both — a Ducky payload that re-points a target’s Wi-Fi at a Pineapple-hosted rogue AP, for instance. Vol 14 is the dedicated combined-workflows volume and hyperlinks into the WiFi Pineapple deep dive.

There is also light overlap inside the hub: the Flipper Zero (../Flipper Zero/) has a BadUSB feature, and ESP32-class devices can do HID injection too. The distinction this manual draws (Vol 8, Vol 17): the USB Rubber Ducky is the purpose-built, no-compromise keystroke-injection device and Ducky Script the canonical language the others imitate. Learning Ducky Script properly makes the Flipper’s BadUSB feature, and any other HID-injection tool, legible.

9. The posture warning

One paragraph here; Vol 16 carries the full framing and Vol 15 the defensive counterpart. Keystroke injection is intrusive by definition. The moment a payload runs, it has done something — opened a shell, run a command, changed a setting, emulated a network adapter — on a machine, as a user, without that user’s action and usually without their knowledge. There is no passive mode. The WiFi Pineapple at least has a genuinely lawful passive-recon posture; a keystroke-injection device does not — if it is doing anything at all, it is acting. That means, every single time: owned hardware, or explicit written authorization. A payload that runs on a machine the operator is not authorised to touch is, in most jurisdictions, unauthorised access to a computer system — a crime — regardless of how harmless the payload’s content is. The Key Croc and O.MG sharpen this further: they are designed to be left behind, which means the intrusion persists in time, and an installed implant on a non-authorised machine is a continuing offence. The legal line here is not subtle, and Vol 16 draws it plainly.

10. How to read this manual — depth indices

If you want to…	Read
Understand the technique conceptually	Vols 1-2
Write your first payload	Vols 1, 3, 12 (encode/deploy), 7 (layouts)
Program properly — variables, logic, smart payloads	Vols 3-6
Know your specific device inside-out	the matching Part II volume (8 = Ducky, 9 = Bunny, 10 = Croc, 11 = O.MG)
Encode/deploy across all four devices	Vol 12
Build a payload library / see worked examples	Vol 13
Stage devices together, or with the Pineapple	Vol 14
Defend against this / understand detection	Vol 15
Get the legal/ethics/OPSEC framing	Vol 16 — everyone reads this one
Decide which device for a given job	Vol 17
A laminate-ready quick reference	Vol 18

Task → section index	Volume
The 2010 origin, the Mark I → Mark II hardware jump	Vol 2 § 2-4
`STRING`, `DELAY`, `REM`, key names, modifier combos	Vol 3
`VAR`, `IF`/`ELSE`, `WHILE`, `FUNCTION`, operators, `DEFINE`	Vol 4
`$_OS` OS detection; `WAIT_FOR_CAPS_*`; jitter; randomization	Vol 5
`ATTACKMODE`, VID/PID spoofing, Keystroke Reflection, `EXFIL`	Vol 6
Why a US-layout payload mistypes on an AZERTY target	Vol 7
Bash Bunny `ATTACKMODE` / `QUACK` / the bash environment	Vol 9
Key Croc keyword/regex match-and-trigger payloads	Vol 10
O.MG web UI, geo-fencing, the Basic/Elite tiers	Vol 11
Defensive USB device control / HID allow-listing	Vol 15

11. Resources

Hak5 / Ducky Script

Ducky Script docs + quick reference: https://docs.hak5.org/hak5-usb-rubber-ducky
USB Rubber Ducky product: https://shop.hak5.org/products/usb-rubber-ducky
Bash Bunny: https://docs.hak5.org/bash-bunny · Key Croc: https://docs.hak5.org/key-croc
O.MG firmware (open source): https://github.com/O-MG/O.MG-Firmware
The official Hak5 payload repositories: https://github.com/hak5

Within the Hack Tools hub

../WiFi Pineapple/03-outputs/WiFiPineapple_Complete.html — the sibling Hak5 deep dive (combined workflows: Vol 14)
../Flipper Zero/ — has a BadUSB capability this manual makes legible
../_shared/legal_ethics.md — the lab-discipline rules for every tool in the hub
../_shared/comparison.md — the cross-tool decision matrix

This is Volume 1 of an 18-volume series. Next: Vol 2 covers the history — Darren Kitchen’s 2010 origin, the Rubber Ducky hardware lineage, how Ducky Script grew from a 2-action macro language into the 3.0 structured language, and how the language spread across the device family.

Ducky Script Volume 1 — Overview: Keystroke Injection, the Device Family, and the Decision Tree

Contents