HTH SkeletonKey

SkeletonKey

SkeletonKey is the firmware for the Hackers Teaching Hackers 2022 Goonies badge. It starts as a seven-part hardware CTF and, once unlocked, becomes a small ESP8266 infrared and Wi-Fi experimentation toolkit.

[!WARNING] The firmware can transmit 802.11 deauthentication frames and infrared power codes. Use those functions only on equipment and networks you own or have explicit permission to test.

What the badge contains

The target configured in platformio.ini is an Espressif ESP-WROOM-02 with 2 MB of flash. The application uses:

KiCad sources and original SVG artwork are under hardware/.

Operating model

At boot, the badge reads its progress from LittleFS:

• State below 8: locked challenge mode.
• State 8 or higher: unlocked toolkit mode.
• State 9: also enables the long-press deauth-all control in detector mode.

Touching the capacitive mode control on A0 advances to the next mode and wraps to the first mode at the end of the list. The physical trigger button on GPIO 13 does not change modes; it performs the action assigned to the selected mode.

Locked challenge modes

The locked badge alternates between two modes:

1. Progress / badge-to-badge IR
   • The eight front LEDs show challenge progress.
   • The IR receiver watches for badge control codes.
   • Pressing the trigger transmits one randomly selected fragment of the cooperative IR challenge.
2. Challenge room
   • Pressing the trigger starts or stops a local Wi-Fi access point.
   • The AP uses SkeletonKey<number> as its SSID and oneeyedwilly<number> as its password, with no separator before the number.
   • Every 10 seconds, the LED array alternates between the blue/cyan binary SSID suffix and the purple binary password suffix.
   • The web application displays received IR values and accepts flags.

Seven distinct accepted flags advance persistent state to 8, unlock the treasure page, and expose the full mode list. See docs/challenge-walkthrough.md for the intended solve path and the original challenge defects.

Unlocked toolkit modes

The rows below are in touch-selection order. After ESP8266 Deauther, the next touch returns to Bling.

Build and flash

The short version is:

pio run -e esp_wroom_02
pio run -e esp_wroom_02 -t upload --upload-port <PORT>
pio run -e esp_wroom_02 -t uploadfs --upload-port <PORT>
pio device monitor --baud 115200 --port <PORT>

Both the firmware and the LittleFS image are required. The filesystem contains the challenge state, pages, deauther UI, SSTV audio, fonts, and artwork.

The USB-C connector powers the badge but does not provide onboard USB serial. The programming pads are not labelled on the badge:

Use a 3.3 V USB-to-UART adapter: adapter TX to RXD1, adapter RX to TXD1, and adapter ground to GND1. Hold IO0 to GND1 while powering the badge on to enter the bootloader.

Read docs/flashing.md before flashing. The Deauth Patch/ is discussed separately in docs/deauth-patch.md and is not applied by the normal PlatformIO build.

Maintainer unlock shortcuts

The intended route is to solve and submit all seven flags. For development or badge recovery there are two shortcuts:

• Temporary, no flash: transmit 64948196 decimal (0x03DF07E4) as a 32-bit NEC IR code at the receiver. It toggles the in-memory lock and does not persist across reboot.
• Persistent: set data/state.txt to 8 and data/flags.txt to 1111111, then upload the LittleFS image. Use state 9 only if you deliberately want the hidden deauth-all control enabled.

Repository layout

data/                 LittleFS content: challenge UI, state, audio and deauther web assets
Deauth Patch/         Historical ESP8266 NONOS SDK library sets; not applied automatically
docs/                 Flashing, challenge and patch notes
hardware/             KiCad source and SVG artwork
src/SkeletonKey.ino   Badge application and mode state machine
src/esp8266_deauther/ Vendored ESP8266 Deauther-derived implementation
platformio.ini        ESP-WROOM-02 build configuration
password.jpg          Original public CTF hint

Licence and attribution

Original SkeletonKey project material is released under the MIT License; see LICENSE. Vendored code, generated web assets, fonts, SDK binaries, and event artwork retain their respective upstream terms and are not relicensed by the top-level MIT License. See THIRD_PARTY_NOTICES.md.