# cifertech/evilduck architecture

> Architecture diagram of the GitHub repository cifertech/evilduck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cifertech/evilduck
- Repository: https://github.com/cifertech/evilduck

## Overview

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: [`EvilDuckS3/com.cpp`](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/com.cpp) (Command executor), [`EvilDuckS3/duckscript.cpp`](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duckscript.cpp) (DuckScript runner), [`EvilDuckS3/webserver.cpp`](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/webserver.cpp) (Web server), [`EvilDuckS3/storage.cpp`](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/storage.cpp) (Storage resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_legacy["Original Device"]
  node_legacy_fw["SD firmware<br/>[EvilDuck.ino]"]
end

subgraph group_control["S3 Control"]
  node_s3_fw["S3 firmware<br/>[EvilDuckS3.ino]"]
  node_web_ui["Web panel<br/>[webfiles.h]"]
  node_webserver["Web server<br/>[webserver.cpp]"]
  node_cli["Command CLI<br/>[cli.cpp]"]
  node_settings[("Device settings<br/>[settings.cpp]")]
  node_library["Script library<br/>[script_library.cpp]"]
end

subgraph group_execution["Script Execution"]
  node_runner["DuckScript runner<br/>[duckscript.cpp]"]
  node_command_exec["Command executor<br/>[com.cpp]"]
  node_variables["Script variables<br/>[duck_vars.cpp]"]
  node_key_mapping["Key mapping<br/>[duck_keys.cpp]"]
  node_locale["Keyboard locale"]
  node_script_log["Execution log<br/>[script_log.cpp]"]
end

subgraph group_storage["Storage"]
  node_storage_api["Storage resolver<br/>[storage.cpp]"]
  node_spiffs[("Internal flash<br/>[spiffs.cpp]")]
  node_sd[("SD card<br/>[sd_card.cpp]")]
end

subgraph group_device["Device I/O"]
  node_hid["USB HID backend<br/>[hid_backend.cpp]"]
  node_attackmode["USB modes<br/>[attackmode.cpp]"]
  node_usb_msc["Mass storage mode<br/>[usb_msc.cpp]"]
  node_led["RGB status LED<br/>[led.cpp]"]
end

node_host(("Host computer"))
node_operator(("Operator"))

node_host -->|"powers and connects"| node_legacy_fw
node_legacy_fw -->|"types payload"| node_host
node_operator -->|"uses panel"| node_web_ui
node_web_ui -->|"sends requests"| node_webserver
node_webserver -->|"starts or stops"| node_runner
node_operator -->|"sends commands"| node_cli
node_cli -->|"runs script"| node_runner
node_webserver -->|"manages scripts"| node_storage_api
node_webserver -->|"reads examples"| node_library
node_webserver -->|"updates settings"| node_settings
node_webserver -->|"requests firmware update"| node_s3_fw
node_runner -->|"resolves and opens"| node_storage_api
node_storage_api -->|"reads and writes"| node_spiffs
node_storage_api -->|"reads and writes"| node_sd
node_storage_api -->|"copies files"| node_spiffs
node_storage_api -->|"copies files"| node_sd
node_runner -->|"dispatches lines"| node_command_exec
node_runner -->|"records progress"| node_script_log
node_command_exec -->|"expands variables"| node_variables
node_command_exec -->|"presses key tokens"| node_key_mapping
node_command_exec -->|"types localized text"| node_locale
node_command_exec -->|"sends key events"| node_hid
node_command_exec -->|"changes USB modes"| node_attackmode
node_command_exec -->|"sets color"| node_led
node_runner -->|"signals run status"| node_led
node_hid -->|"emits keystrokes"| node_host
node_attackmode -->|"controls storage mode"| node_usb_msc
node_usb_msc -->|"exposes files"| node_sd
node_s3_fw -->|"loads configuration"| node_settings
node_s3_fw -->|"installs examples"| node_library
node_s3_fw -->|"initializes keyboard"| node_hid
node_s3_fw -->|"autoruns configured script"| node_runner

click node_legacy_fw "https://github.com/cifertech/evilduck/blob/main/EvilDuck/EvilDuck.ino"
click node_s3_fw "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/EvilDuckS3.ino"
click node_web_ui "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/webfiles.h"
click node_webserver "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/webserver.cpp"
click node_cli "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/cli.cpp"
click node_settings "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/settings.cpp"
click node_library "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/script_library.cpp"
click node_runner "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duckscript.cpp"
click node_command_exec "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/com.cpp"
click node_variables "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duck_vars.cpp"
click node_key_mapping "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duck_keys.cpp"
click node_locale "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/keyboard_locale.cpp"
click node_script_log "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/script_log.cpp"
click node_storage_api "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/storage.cpp"
click node_spiffs "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/spiffs.cpp"
click node_sd "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/sd_card.cpp"
click node_hid "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/hid_backend.cpp"
click node_attackmode "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/attackmode.cpp"
click node_usb_msc "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/usb_msc.cpp"
click node_led "https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/led.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_legacy_fw toneBlue
class node_s3_fw,node_web_ui,node_webserver,node_cli,node_settings,node_library toneAmber
class node_runner,node_command_exec,node_variables,node_key_mapping,node_locale,node_script_log toneMint
class node_storage_api,node_spiffs,node_sd toneRose
class node_hid,node_attackmode,node_usb_msc,node_led,node_host,node_operator toneIndigo
```

## Components

### Original Device

- [SD firmware](https://github.com/cifertech/evilduck/blob/main/EvilDuck/EvilDuck.ino): `EvilDuck/EvilDuck.ino`

### S3 Control

- [S3 firmware](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/EvilDuckS3.ino): `EvilDuckS3/EvilDuckS3.ino`
- [Web panel](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/webfiles.h): `EvilDuckS3/webfiles.h`
- [Web server](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/webserver.cpp): `EvilDuckS3/webserver.cpp`
- [Command CLI](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/cli.cpp): `EvilDuckS3/cli.cpp`
- [Device settings](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/settings.cpp): `EvilDuckS3/settings.cpp`
- [Script library](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/script_library.cpp): `EvilDuckS3/script_library.cpp`

### Script Execution

- [DuckScript runner](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duckscript.cpp): `EvilDuckS3/duckscript.cpp`
- [Command executor](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/com.cpp): `EvilDuckS3/com.cpp`
- [Script variables](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duck_vars.cpp): `EvilDuckS3/duck_vars.cpp`
- [Key mapping](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/duck_keys.cpp): `EvilDuckS3/duck_keys.cpp`
- [Keyboard locale](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/keyboard_locale.cpp): `EvilDuckS3/keyboard_locale.cpp`
- [Execution log](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/script_log.cpp): `EvilDuckS3/script_log.cpp`

### Storage

- [Storage resolver](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/storage.cpp): `EvilDuckS3/storage.cpp`
- [Internal flash](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/spiffs.cpp): `EvilDuckS3/spiffs.cpp`
- [SD card](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/sd_card.cpp): `EvilDuckS3/sd_card.cpp`

### Device I/O

- [USB HID backend](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/hid_backend.cpp): `EvilDuckS3/hid_backend.cpp`
- [USB modes](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/attackmode.cpp): `EvilDuckS3/attackmode.cpp`
- [Mass storage mode](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/usb_msc.cpp): `EvilDuckS3/usb_msc.cpp`
- [RGB status LED](https://github.com/cifertech/evilduck/blob/main/EvilDuckS3/led.cpp): `EvilDuckS3/led.cpp`

### Other components

- **Host computer**
- **Operator**

## Connections

- 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