How cifertech/evilduck works
EvilDuck is a USB HID payload device in two generations: the original Arduino Micro version runs an SD-card script, while EvilDuck S3 adds WiFi control, a DuckScript interpreter, dual storage, and USB mass storage. The main S3 workflow is browser or CLI request → script resolution and interpretation → HID keystrokes on the attached host. The graph also retains documented configuration, library, logging, and firmware-update capabilities. Several routes and startup connections are not shown in the sampled excerpts, so uncertain wiring is omitted.
Main entry points: com.cpp Command executor · duckscript.cpp DuckScript runner · webserver.cpp Web server · storage.cpp Storage resolver
Components 22
Original Device
- SD firmware
EvilDuck/EvilDuck.ino
S3 Control
- S3 firmware
EvilDuckS3/EvilDuckS3.ino - Web panel
EvilDuckS3/webfiles.h - Web server
EvilDuckS3/webserver.cpp - Command CLI
EvilDuckS3/cli.cpp - Device settings
EvilDuckS3/settings.cpp - Script library
EvilDuckS3/script_library.cpp
Script Execution
- DuckScript runner
EvilDuckS3/duckscript.cpp - Command executor
EvilDuckS3/com.cpp - Script variables
EvilDuckS3/duck_vars.cpp - Key mapping
EvilDuckS3/duck_keys.cpp - Keyboard locale
EvilDuckS3/keyboard_locale.cpp - Execution log
EvilDuckS3/script_log.cpp
Storage
- Storage resolver
EvilDuckS3/storage.cpp - Internal flash
EvilDuckS3/spiffs.cpp - SD card
EvilDuckS3/sd_card.cpp
Device I/O
- USB HID backend
EvilDuckS3/hid_backend.cpp - USB modes
EvilDuckS3/attackmode.cpp - Mass storage mode
EvilDuckS3/usb_msc.cpp - RGB status LED
EvilDuckS3/led.cpp
Other components
- Host computer
- Operator
Connections 32
- Host computer → SD firmware: powers and connects
- SD firmware → Host computer: types payload
- Operator → Web panel: uses panel
- Web panel → Web server: sends requests
- Web server → DuckScript runner: starts or stops
- Operator → Command CLI: sends commands
- Command CLI → DuckScript runner: runs script
- Web server → Storage resolver: manages scripts
- Web server → Script library: reads examples
- Web server → Device settings: updates settings
- Web server → S3 firmware: requests firmware update
- DuckScript runner → Storage resolver: resolves and opens
- Storage resolver → Internal flash: reads and writes
- Storage resolver → SD card: reads and writes
- Storage resolver → Internal flash: copies files
- Storage resolver → SD card: copies files
- DuckScript runner → Command executor: dispatches lines
- DuckScript runner → Execution log: records progress
- Command executor → Script variables: expands variables
- Command executor → Key mapping: presses key tokens
- Command executor → Keyboard locale: types localized text
- Command executor → USB HID backend: sends key events
- Command executor → USB modes: changes USB modes
- Command executor → RGB status LED: sets color
- DuckScript runner → RGB status LED: signals run status
- USB HID backend → Host computer: emits keystrokes
- USB modes → Mass storage mode: controls storage mode
- Mass storage mode → SD card: exposes files
- S3 firmware → Device settings: loads configuration
- S3 firmware → Script library: installs examples
- S3 firmware → USB HID backend: initializes keyboard
- S3 firmware → DuckScript runner: autoruns configured script