{"id":51324719,"url":"https://github.com/webdevtodayjason/warlock-walter","last_synced_at":"2026-07-01T17:03:51.749Z","repository":{"id":366221076,"uuid":"1275481256","full_name":"webdevtodayjason/warlock-walter","owner":"webdevtodayjason","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-20T20:05:59.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-20T21:12:42.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webdevtodayjason.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T18:41:29.000Z","updated_at":"2026-06-20T20:06:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/webdevtodayjason/warlock-walter","commit_stats":null,"previous_names":["webdevtodayjason/warlock-walter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/webdevtodayjason/warlock-walter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fwarlock-walter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fwarlock-walter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fwarlock-walter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fwarlock-walter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webdevtodayjason","download_url":"https://codeload.github.com/webdevtodayjason/warlock-walter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fwarlock-walter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35015061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T17:03:50.977Z","updated_at":"2026-07-01T17:03:51.740Z","avatar_url":"https://github.com/webdevtodayjason.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Warlock-Walter: Cellular C2 Drop Box\n\n\u003e ESP32-S3 + Sequans GM02SP cellular C2 relay and reconnaissance drop box for authorized red team engagements.\n\u003e Built on the [DPTechnics Walter](https://quickspot.io/) platform.\n\n## Overview\n\n**Warlock-Walter** transforms a DPTechnics Walter board (ESP32-S3-WROOM-1-N16R2 + Sequans Monarch 2 GM02SP) into a covert cellular command-and-control relay for authorized red team operations. It provides out-of-band backhaul via LTE-M/NB-IoT, local WiFi reconnaissance, GNSS positioning, and a bidirectional command interface over both MQTT (cellular) and USB serial.\n\n## Hardware\n\n### Walter Board\n\n| Component | Part | Capabilities |\n|-----------|------|-------------|\n| **MCU** | ESP32-S3-WROOM-1-N16R2 | Dual-core LX7, 16MB flash, 2MB PSRAM |\n| **Modem** | Sequans GM02SP (Monarch 2) | LTE Cat-M1, LTE Cat-NB1/NB2, GNSS |\n| **WiFi** | ESP32-S3 onboard | 802.11 b/g/n (WiFi 4) |\n| **BLE** | ESP32-S3 onboard | BLE 5.0 |\n| **GNSS** | Sequans integrated | GPS + Galileo, LNA + SAW filter |\n| **USB** | Type-C | Power, flashing, serial debug |\n| **SIM** | Nano-SIM + integrated SIM | eUICC capable |\n\n### Modem UART Pin Map (ESP32 ↔ Sequans)\n\n| Function | GPIO |\n|----------|------|\n| Modem RX | 14 |\n| Modem TX | 48 |\n| RTS | 21 |\n| CTS | 47 |\n| Reset (active low) | 45 |\n\n### Antennas\n\nWalter uses u.FL connectors for cellular and GNSS antennas. The WiFi/BLE antennas are on-board PCB traces.\n\n- **Cellular:** u.FL → LTE-M/NB-IoT antenna (required for cellular)\n- **GNSS:** u.FL → GPS/Galileo antenna (required for positioning)\n- **WiFi/BLE:** On-board PCB antenna (no external connection needed)\n\n### Host Connection\n\nWalter connects to the host (cyberdeck) via USB Type-C. The ESP32-S3 exposes a native USB CDC serial interface:\n\n- **USB VID:PID:** `303a:1001` (Espressif USB JTAG/serial debug unit)\n- **Linux device:** `/dev/ttyACM*` (cdc_acm driver)\n- **Baud:** 115200\n\nThe Sequans modem is **not** directly accessible from USB — it sits behind the ESP32 on an internal UART (`Serial2`). All modem communication is proxied through the ESP32 firmware via the WalterModem library.\n\n## Architecture\n\n### Dual-Homed Design\n\n```\n                    ┌─────────────────────────────┐\n                    │     Walter (ESP32-S3)        │\n                    │                              │\n  Target WiFi ──────┤ WiFi    ┌──────────────┐     │\n  (known SSIDs)     │ ──────► │ Command       │ ◄───┤ USB Serial CLI\n                    │         │ Handler       │     │ (local operator)\n                    │ LTE-M ──┤               │     │\n  Cellular tower ───┤ ◄────── └──────┬───────┘     │\n                    │  Sequans GM02SP │             │\n                    │  GNSS ──────────┘             │\n                    └────────────┬──────────────────┘\n                                 │\n                          MQTT over LTE-M\n                                 │\n                    ┌────────────▼──────────────────┐\n                    │   C2 MQTT Broker               │\n                    │   (operator-controlled)         │\n                    │                                │\n                    │  warlock/walter/{MAC}/telemetry│\n                    │  warlock/walter/{MAC}/commands │\n                    │  warlock/walter/{MAC}/response │\n                    └────────────────────────────────┘\n```\n\n### LTE/GNSS Time-Slicing\n\nThe Sequans GM02SP **cannot** operate LTE and GNSS simultaneously. The firmware time-slices:\n\n1. Connect LTE → sync GNSS clock (NITZ) → download assistance data\n2. Disconnect LTE → acquire GNSS fix\n3. Reconnect LTE → publish telemetry with position\n\nThis cycle repeats on demand or at configured intervals.\n\n### MQTT Topic Structure\n\n| Topic | Direction | Purpose |\n|-------|-----------|---------|\n| `warlock/walter/{MAC}/telemetry` | Device → C2 | Periodic status, position, signal |\n| `warlock/walter/{MAC}/commands` | C2 → Device | Remote commands |\n| `warlock/walter/{MAC}/response` | Device → C2 | Command responses |\n\n`{MAC}` is the ESP32-S3 WiFi STA MAC address in `XX:XX:XX:XX:XX:XX` format.\n\n### WiFi Known Networks\n\nThe firmware embeds a list of known WiFi credentials synced from the host. On boot, Walter scans for these SSIDs and auto-connects if found. This provides high-bandwidth local connectivity when in range, falling back to LTE-M when WiFi is unavailable.\n\n## Firmware Features\n\n### Command Set (Serial + MQTT)\n\n| Command | Description |\n|---------|-------------|\n| `status` | Full device state (WiFi, LTE, MQTT, GNSS, temp, heap) as JSON |\n| `wifi scan` | Scan all nearby APs, return SSID/BSSID/RSSI/channel/auth as JSON |\n| `wifi connect \u003cssid\u003e \u003cpass\u003e` | Join a specific WiFi network |\n| `gnss fix` | Acquire GNSS position (time-slices LTE off) |\n| `lte status` | Cellular registration state |\n| `lte connect` | Force LTE attach |\n| `lte disconnect` | Tear down LTE connection |\n| `reboot` | Restart the board |\n| `help` | List available commands |\n\n### Telemetry Payload (JSON)\n\nPublished every 60 seconds when MQTT is connected:\n\n```json\n{\n  \"type\": \"telemetry\",\n  \"device\": \"walter-AABBCC\",\n  \"uptime\": 3600,\n  \"wifi_ssid\": \"jb-wifi7\",\n  \"wifi_ip\": \"192.168.1.50\",\n  \"wifi_rssi\": -55,\n  \"lte_connected\": true,\n  \"lat\": 35.123456,\n  \"lon\": -80.654321,\n  \"sats\": 8,\n  \"confidence\": 12.5,\n  \"temp_c\": 42.3,\n  \"free_heap\": 234567\n}\n```\n\n### WiFi Scan Response (JSON)\n\n```json\n{\n  \"type\": \"wifi_scan\",\n  \"networks\": [\n    {\"ssid\": \"CorpWiFi\", \"bssid\": \"AA:BB:CC:DD:EE:FF\", \"rssi\": -65, \"channel\": 6, \"auth\": \"WPA2\"},\n    {\"ssid\": \"GuestNet\", \"bssid\": \"11:22:33:44:55:66\", \"rssi\": -72, \"channel\": 11, \"auth\": \"open\"}\n  ]\n}\n```\n\n## Build \u0026 Flash\n\n### Prerequisites\n\n- **arduino-cli** v1.1+ (or Arduino IDE 2.x)\n- **ESP32 Arduino core** (esp32:esp32)\n- **Libraries:** WalterModem (QuickSpot), ArduinoJson v7\n- **esptool** (for direct flashing if needed)\n- Board target: `esp32:esp32:dpt_walter` or `esp32s3box` (if Walter board def unavailable)\n\n### Toolchain Setup\n\n```bash\n# Install arduino-cli\nwget https://github.com/arduino/arduino-cli/releases/download/v1.1.1/arduino-cli_1.1.1_Linux_ARM64.tar.gz\ntar xzf arduino-cli_*.tar.gz \u0026\u0026 sudo mv arduino-cli /usr/local/bin/\n\n# Configure for ESP32\narduino-cli config init\narduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json\narduino-cli core update-index\narduino-cli core install esp32:esp32\n\n# Install libraries\narduino-cli lib install ArduinoJson\ngit clone https://github.com/QuickSpot/walter-arduino.git ~/Arduino/libraries/WalterModem\n```\n\n### Compile\n\n```bash\narduino-cli compile \\\n  --board esp32:esp32:dpt_walter \\\n  --build-property \"build.extra_flags=-DBOARD_HAS_PSRAM\" \\\n  ~/Arduino/walter_c2/walter_c2.ino\n```\n\n### Flash\n\n```bash\n# Via arduino-cli\narduino-cli upload -p /dev/ttyACM1 --board esp32:esp32:dpt_walter ~/Arduino/walter_c2/\n\n# Or via esptool directly\nesptool.py --port /dev/ttyACM1 write_flash 0x0 walter_c2.ino.bin\n```\n\n### Arduino IDE Settings (if using IDE)\n\n| Setting | Value |\n|---------|-------|\n| Board | DPTechnics Walter |\n| CPU Frequency | 240MHz |\n| Core Debug Level | Debug |\n| USB DFU On Boot | Disabled |\n| Erase All Flash Before Upload | Enabled |\n| Flash Mode | QIO 80MHz |\n| Flash Size | 16MB (128Mb) |\n| Partition Scheme | 16M Flash (2MB APP/12.5MB FATFS) |\n| PSRAM | QSPI PSRAM |\n| Upload Mode | UART0 / Hardware CDC |\n| Upload Speed | 921600 |\n| USB Mode | Hardware CDC and JTAG |\n\n## Configuration\n\nEdit the following `#define` values at the top of `walter_c2.ino`:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `MQTT_HOST` | `broker.emqx.io` | C2 MQTT broker address |\n| `MQTT_PORT` | `1883` | MQTT broker port |\n| `CELLULAR_APN` | `\"\"` (auto) | Carrier APN (empty = auto-detect) |\n| `RADIO_TECH` | `WALTER_MODEM_RAT_LTEM` | LTE-M or NB-IoT |\n| `TELEMETRY_INTERVAL_MS` | `60000` | Telemetry publish interval |\n| `GNSS_FIX_TIMEOUT_MS` | `120000` | GNSS fix timeout |\n\nAdd/edit entries in the `knownNetworks[]` array to sync WiFi credentials from the host.\n\n## Cellular / SIM Requirements\n\nWalter's Sequans GM02SP requires **LTE-M (Cat-M1)** or **NB-IoT (Cat-NB1/NB2)** provisioning. Standard phone SIMs will **not** work — you need an IoT/M2M SIM.\n\n### Recommended SIM Providers\n\n| Provider | Notes |\n|----------|-------|\n| **Hologram.io** | eUICC, multi-carrier (AT\u0026T + T-Mobile in US), $0.50/MB, developer API |\n| **Soracom** | Air SIM, global coverage, built-in relay services |\n| **Twilio Super SIM** | Multi-carrier, API-driven |\n\n### Current SIM Status\n\nThe board shipped with an unknown SIM. LTE-M registration fails (`+CEREG: 0`). 6× Hologram Hyper eUICC IoT SIMs have been ordered. Once activated, update `CELLULAR_APN` if needed (Hologram typically auto-provisions).\n\n## Operational Use Cases (Authorized Engagements)\n\n### 1. Out-of-Band C2 Drop Box\n\nPhysically place Walter on the target network perimeter. WiFi connects to target infrastructure (if credentials known), LTE-M provides covert backhaul. Commands flow via MQTT — invisible to target network monitoring.\n\n### 2. WiFi Reconnaissance\n\nDeploy Walter in proximity to the target. `wifi scan` enumerates all nearby APs with signal strength, enabling positioning mapping and target identification.\n\n### 3. GNSS Logging\n\nWalter's GNSS provides precise positioning. Useful for wardriving/mapping operations, geotagging findings, and tracking device movement.\n\n### 4. Cellular Relay\n\nWhen the host cyberdeck has no WiFi, Walter provides LTE-M uplink for out-of-band operator communication.\n\n## File Structure\n\n```\nwarlock-walter/\n├── README.md                  # This file\n├── walter_c2/\n│   └── walter_c2.ino          # Main firmware\n├── docs/\n│   ├── HARDWARE.md            # Hardware details, pin maps, antenna specs\n│   ├── PROTOCOL.md            # MQTT protocol, message formats, crypto roadmap\n│   └── OPERATIONS.md          # Deployment guides for engagement scenarios\n├── tools/\n│   ├── walter-monitor.py      # Host-side MQTT monitor/CLI for C2\n│   └── wifi-sync.sh           # Sync known networks from NetworkManager\n└── LICENSE                    # TBD\n```\n\n## Roadmap\n\n- [ ] **MQTT over TLS (MQTTS)** — encrypt C2 channel\n- [ ] **Shared-key HMAC auth** — authenticate MQTT messages\n- [ ] **WiFi evil twin / rogue AP** — active WiFi attacks\n- [ ] **WiFi deauth** — targeted deauthentication\n- [ ] **BLE beacon scanning** — device enumeration\n- [ ] **Deep sleep mode** — field endurance (weeks/months)\n- [ ] **OTA firmware updates** — remote patching via LTE\n- [ ] **Data staging** — local buffering when LTE unavailable\n- [ ] **Host-side C2 dashboard** — Python TUI for multi-Walter fleet\n\n## Security Notes\n\n- WiFi credentials are stored in plaintext in firmware flash. For production, use NVS encryption or a secrets manager.\n- MQTT is currently unencrypted (port 1883). Use MQTTS (8883) with TLS for operational security.\n- The Sequans modem supports TLS — the WalterModem library has `socketConfigSecure()` for encrypted sockets.\n- GNSS position data is sensitive — scrub from logs when not needed.\n\n## Acknowledgments\n\n- **DPTechnics BV** (Belgium) — Walter hardware design and open-source libraries\n- **Espressif Systems** — ESP32-S3 platform\n- **Sequans Communications** — Monarch 2 GM02SP modem\n- **QuickSpot** — Arduino/ESP-IDF/MicroPython libraries and documentation\n\n## License\n\nFirmware: Based on QuickSpot/walter-arduino (DPTechnics 5-clause license).\nWarlock extensions: TBD (operator's choice).\n\n---\n\n*For authorized red team, security research, and defensive use only.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevtodayjason%2Fwarlock-walter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdevtodayjason%2Fwarlock-walter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevtodayjason%2Fwarlock-walter/lists"}