[ BadUSB on the Flipper Zero ]

BadUSB turns the Flipper Zero into a USB keyboard. Plug it into a
computer and it enumerates as a human interface device (HID), then types
a scripted payload at machine speed: hundreds of keystrokes a second,
far faster than a person and with none of the hesitation. This is the
classic Rubber Ducky trick, named for the Hak5 device that made it
famous, and the Flipper runs the same idea from a menu.

The trick works because computers trust keyboards. A machine has no way
to tell a real keyboard from one that is only pretending, so a scripted
device can open a terminal, launch a program, or paste text the instant
it is plugged in, limited only by what the logged-in user could type by
hand.

Run payloads ONLY on machines you own, or ones you have explicit written
permission to test. A BadUSB payload is code execution by another name,
and running one on a computer that is not yours is unauthorized access,
plain and simple. The legal line below is not boilerplate, and the
rest of this page treats every target as your own lab machine.

Ducky Script is the small language these payloads are written in. It
reads as one action per line, and the Flipper runs it from top to
bottom. The core commands are almost all you ever need:

  REM      a comment line, ignored when the payload runs
  DELAY    wait this many milliseconds before the next line
  STRING   type this text literally, as if you pressed the keys
  ENTER    press Enter (RETURN is an accepted alias)
  GUI      the Windows or Command key, alone or with a letter
  CTRL     a modifier key; ALT and SHIFT work the same way

Two habits make a payload reliable. Open with a DELAY so the computer
finishes recognising the new keyboard before any typing starts, and add
a short delay after anything that opens a window, because a payload that
types faster than the screen keeps up simply loses keystrokes.

Here is a complete and harmless example. It opens the Run dialog on
Windows, launches Notepad, waits for it, and types a friendly note:

  REM benign demo, opens Notepad and types one line
  DELAY 800
  GUI r
  DELAY 400
  STRING notepad
  ENTER
  DELAY 800
  STRING Hello from an authorized BadUSB test. Nothing to see here.

That is the entire shape of a payload: open something, wait for it, then
type. For anything past a benign demo like this, read the payloads in
the repo and the upstream Hak5 Ducky Script documentation, and hold
every one of them to the same owned-or-authorized rule.

A payload is a sequence of key presses, not letters, and the same key
produces a different character depending on the keyboard layout the
target is set to. A payload written for a US QWERTY layout mistypes on an
AZERTY, QWERTZ, or any other non-US keyboard: the punctuation and symbols
land in the wrong place, and a STRING that should be a clean command
comes out as garbage.

The Flipper handles this with layout files. They live on the microSD in
the badusb folder, and the firmware ships a set covering the common
locales. Before running a payload, pick the layout that matches the
target keyboard, and the Flipper remaps its key presses to produce the
characters the script actually intends.

The rule of thumb is simple: match the layout to the machine, not to the
payload. A script that worked perfectly on your US laptop can fail on a
German or French keyboard for no reason other than the layout, so it is
the first thing to check when a payload misbehaves.

Payloads are plain text files, and they live on the microSD in the
badusb folder, the same place as the layout files. Add your own by
dropping a Ducky Script file into that folder over qFlipper or an SD card
reader, and it appears in the BadUSB app on the device.

Running one, on a machine you own, is three steps:

  1. Pick the layout that matches the target keyboard.
  2. Select the payload in the BadUSB app, with that layout set.
  3. Plug in and run. Connect the Flipper to the target over USB and
     press run; the payload types itself out once and then stops.

That is the whole workflow. The Flipper needs no drivers, because as far
as the target is concerned it simply is a keyboard.

BadUSB is easy to run, which is exactly why it is worth defending
against. The good news is that the defenses are mostly plain discipline,
not exotic technology.

  — Lock your screen. A payload can only do what the logged-in user
    can do, so it has nothing to act on when the machine is locked. Lock
    the screen every single time you step away, even for a minute; this
    is the single most effective habit.
  — Distrust unknown USB devices. A found flash drive, a free cable,
    or a gifted charger can each hide a payload. Treat anything you did
    not buy and control as hostile, and do not plug it in to find out.
  — Enforce device control on fleets. On managed machines, USB
    device-control or HID allow-listing policy can block or prompt on a
    new keyboard, so a surprise keyboard never silently starts typing.
  — Limit the blast radius. Least-privilege accounts, short lock
    timeouts, and application allow-listing all shrink what a payload can
    accomplish in the few seconds it has.

This is the defensive mirror of the hub guide: the Flipper's own
defensive notes cover the radio side, and the same owned-or-authorized
rule governs all of it.

The law does not care how easy a tool makes something. Running a BadUSB
payload on a computer you do not own, or do not have written permission
to test, is unauthorized access to a computer system, and in most places
that is a crime on its own, before the payload does anything at all.

  — Owned or authorized only. Your own machines, or a target covered
    by explicit written permission, such as a signed engagement scope.
    Nothing else qualifies.
  — Easy is not the same as allowed. That a payload runs in seconds
    from a menu has no bearing on whether you are permitted to run it.
  — Scope is the whole agreement. Even with permission, stay inside
    what was agreed: these machines, this window, these actions, nothing
    beyond them.

None of this is legal advice. It is the short version: if you cannot
point to ownership or written authorization, do not plug it in.

Is BadUSB legal to use?
On machines you own, or ones you have explicit written permission to
test, yes. On anything else, no: it is unauthorized access, a crime in
most places regardless of what the payload does. Owning the tool is not
permission to use it on other people's computers.

Will my payload work on any computer?
Not automatically. The same key press produces different characters on
different keyboard layouts, so a US-layout payload mistypes on AZERTY,
QWERTZ, and other non-US keyboards. Match the Flipper's layout file to
the target keyboard, and note that some payloads assume a specific OS.

Can BadUSB get past a locked screen?
No. A payload can only do what the logged-in user could type, so a
locked or logged-out machine gives it nothing to work with. That is why
locking your screen when you step away is the best defense against it.

Where do I get BadUSB payloads?
The FlipperZero_Stuff repo has example payloads and the layout files, and
the upstream Hak5 Ducky Script docs cover the language. Read any payload
before running it, and keep every one to owned-or-authorized use.