Initial aether32 school lab bench tool

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-01 21:34:33 -07:00
commit 7bf6abccfc
41 changed files with 4494 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,289 @@
+# aether32
+
+**aether32** is a school-lab bench tool built on **ESP32-S3**: a USB HID keyboard dongle with an onboard WiFi access point and a phone-friendly web UI. Plug it into a lab PC, control diagnostics from your phone, and pull inventory reports **without an SD card** — scan results are stored on **LittleFS** flash and downloaded over WiFi.
+
+Made by Dr Jones.
+
+---
+
+## Authorized use
+
+Use only on machines you own or are explicitly authorized to administer (school IT, lab maintenance, help-desk with permission). This tool automates keystrokes and temporarily joins the target to the dongle’s WiFi to upload diagnostics. **Do not use on student or staff machines without policy approval.** The authors are not responsible for misuse.
+
+---
+
+## What it does (today)
+
+| Capability | Description |
+|------------|-------------|
+| **USB HID** | Types commands, shortcuts, and multi-line scripts on the target as a keyboard |
+| **WiFi AP + web UI** | ESP32 hosts `aether32` WiFi; you browse `192.168.4.1` from a phone |
+| **Lab Scan** | Target joins AP, POSTs hostname/network/disk/AV/uptime/etc. to flash; you download a report |
+| **Saved buttons** | Up to 40 custom one-tap commands stored in flash |
+| **Auto-Run** | Optional plug-in delay, shell open, command, and/or automatic Lab Scan |
+| **No removable media** | SD/USB-MSC stack is **not** built (`storage/` excluded in `platformio.ini`) |
+
+---
+
+## Hardware requirements
+
+- **Any ESP32-S3** board with native USB (HID). Default env: `esp32-s3-devkitm-1`
+- **16 MB flash** recommended (see `platformio.ini`); LittleFS partition for results + config
+- **No microSD card** required or supported in this build
+- Optional: NeoPixel/RGB LED (status feedback on plug / auto-run / typing)
+
+---
+
+## Build and flash
+
+1. Install [PlatformIO](https://platformio.org/) (VS Code extension or CLI).
+2. Open the `aether32` folder as the project root.
+3. Adjust `platformio.ini` if your board differs (`board = ...`, USB mode flags).
+4. Build and upload (first flash also formats LittleFS as configured):
+
+```bash
+cd aether32
+pio run -t upload
+```
+
+Monitor serial (optional): `pio device monitor -b 115200`
+
+**Note:** Do not expect SD-card features from older docs — `build_src_filter` excludes `components/storage/`.
+
+---
+
+## WiFi and web authentication
+
+| Setting | Value |
+|---------|--------|
+| AP SSID | `aether32` |
+| AP password | `aether32-admin` |
+| Web URL | `http://192.168.4.1/` |
+| HTTP Basic Auth | user `drjones` / password `aether32-admin` |
+
+The phone must join the **`aether32`** network to use the UI. Most authenticated routes require HTTP Basic Auth; see API table below.
+
+---
+
+## Data flow (Lab Scan)
+
+```text
+Phone ──WiFi──► ESP32 AP (192.168.4.1)
+                    ▲
+                    │ POST /api/upload?name=<file>  (no auth; AP-local only)
+                    │
+Target PC ◄──USB HID── ESP32 types script:
+    1. Open hidden PowerShell / Terminal (OS-specific)
+    2. Add WLAN profile & connect to aether32
+    3. Run diagnostics; HTTP POST each artifact to ESP32
+    4. Screenshot → screen.png
+    5. exit
+
+Phone ◄── GET /api/download, /api/download/bundle ── reads LittleFS /results/*
+```
+
+**Operator checklist:** desktop **unlocked**, user session active, allow **~25–40 s** after starting Lab Scan for uploads. Target briefly uses WiFi on the dongle AP (may disconnect from school WiFi during upload).
+
+---
+
+## Web UI tabs
+
+Mobile-oriented single-page app (dark theme).
+
+### My Buttons
+
+- Grid of saved commands (up to **40**), stored in flash (`/btns.dat`)
+- Tap to run: opens shell (Win+R, CMD, PowerShell, or Elevated CMD) and types the command
+- Color tiles are **UI-only** (picker index); not persisted server-side
+
+### + Builder
+
+- Create buttons: label, shell type, command text, key delay (5–200 ms)
+- Manage / delete saved buttons
+
+### Tricks
+
+One-shot HID actions (no flash storage):
+
+- **Launch apps:** Calculator, Notepad, CMD, PowerShell, Elevated CMD, Task Manager, Settings, Control Panel, File Explorer
+- **Window control:** Show desktop, minimize all, lock, close window, Alt+Tab (+ spam), Win snap arrows, screenshot shortcut, F5
+- **Keyboard:** Caps Lock, Ctrl+A/C/V/Z/S, zoom in/out, spam Enter/Esc
+- **Recon (opens CMD):** `ver`, `ipconfig`, `whoami`, `tree C:\`
+- **Party / demo:** fake error, ASCII art, telnet Star Wars, fake BSOD line, flip screen, Google/YouTube
+
+### Shell
+
+- **Run command:** shell selector + arbitrary command
+- **Type raw text:** into active window; optional Notepad first, Enter after, delay
+
+### Collect
+
+- **Lab Scan** — full Windows-oriented inventory (see artifacts); retries with OS auto-detect profile if needed
+- **Live status** — phase, last upload, file count, OS, hostname (polls `/api/status` every 2 s)
+- **Quick lab fixes (Windows):** Flush DNS, Device Manager, Disk Management, clear `%TEMP%` (elevated)
+- **Advanced scan:** auto-detect profile, Windows-only profile, screenshot only, IP config, `systeminfo`
+- **Download:** bundled `labscan_<hostname>.txt`, `screen.png`, per-file view/download
+- **Collected files** — browser for everything in `/results/`
+
+### Auto-Run
+
+Stored in flash (`/cfg.dat`):
+
+- **Enable Auto-Run** — after USB plug-in delay, open shell and optionally type a command
+- **Lab Scan on plug-in** — after delay (+ extra 4 s if auto-run enabled), run `collect_lab_scan()` automatically
+- **Delay** — 500 ms–12 s (default 3.5 s) after USB enumerate
+- **Shell** — elevated CMD (default), CMD, PowerShell, or Win+R only
+- **Optional command** — typed after shell opens
+- LED: orange on connect, red while firing, green when done
+
+### Tools
+
+- **Clear HID traces** — elevated cleanup under `C:\Windows\Temp\temp*`
+- **Restart dongle** — reboot ESP32 (WiFi AP restarts)
+
+---
+
+## Lab Scan artifacts
+
+Files are written under LittleFS **`/results/`** (plain text unless noted).
+
+### Full Lab Scan (Windows profile)
+
+| File | Contents |
+|------|----------|
+| `os.txt` | `windows` |
+| `hostname.txt` | hostname + whoami |
+| `network_macs.txt` | `getmac /v` |
+| `network_full.txt` | `ipconfig /all` |
+| `arp.txt` | ARP table |
+| `routes.txt` | `route print` |
+| `netstat.txt` | `netstat -an` |
+| `collected_at.txt` | ISO timestamp |
+| `disk_space.txt` | PSDrives + logical disk sizes |
+| `logged_in_user.txt` | whoami + `query user` |
+| `uptime.txt` | last boot + uptime |
+| `av_status.txt` | Defender status or Security Center AV |
+| `os_version.txt` | `Get-ComputerInfo` + OS version |
+| `ram.txt` | physical RAM total (GB) |
+| `gateway_dns.txt` | default route + DNS servers |
+| `screen.png` | primary display screenshot |
+
+### macOS / Linux Lab Scan
+
+Same logical set where applicable (`os.txt` = `macos` or `linux`), using `ifconfig`/`ip`, `df`, `sw_vers` or `/etc/os-release`, `screencapture` / `scrot`, etc. Scripts no-op if `uname` does not match.
+
+### Lighter “profile” collect (Advanced Scan)
+
+Subset: `os.txt`, `hostname.txt`, network files, `collected_at.txt`, `screen.png` (no disk/AV/uptime extras unless full Lab Scan).
+
+### Optional individual collects (API via `collect_<id>`)
+
+May be triggered from firmware (`collect_dispatch`) — not all exposed in UI:
+
+`disk_space`, `logged_in_user`, `uptime`, `av_status`, `os_version`, `ram`, `gateway_dns`, `sysinfo` → `sysinfo.txt`, `network` → `network_full.txt`, `arp`, `netstat`, `routes`, `hostname`, `users` → `whoami.txt`, `processes` → `processes.txt`, `screenshot`, `profile_auto` / `profile_windows` / `profile_macos` / `profile_linux`, `lab_scan`
+
+Bundled download (`/api/download/bundle`) merges: `os.txt`, `hostname.txt`, `collected_at.txt`, `network_macs.txt`, `network_full.txt`, `arp.txt`, `routes.txt`, `netstat.txt`, `sysinfo.txt`, `processes.txt` (skips missing files).
+
+---
+
+## API summary
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| GET | `/` | Yes | Main web UI (HTML SPA) |
+| POST | `/run` | Yes | Run shell command (`cmd`, `shell`, `delay`) |
+| POST | `/type` | Yes | Type text (`text`, `delay`, `enter`, `notepad`) |
+| POST | `/trick` | Yes | HID trick or `collect_*` (`id`) |
+| POST | `/restart` | Yes | Reboot ESP32 |
+| POST | `/clear_trace` | Yes | HID temp cleanup on target |
+| GET | `/api/buttons` | Yes | List saved buttons (JSON) |
+| POST | `/api/buttons` | Yes | Add button |
+| POST | `/api/buttons/delete` | Yes | Delete by index (`id`) |
+| POST | `/api/upload` | **No** | Target uploads body (`?name=filename`, max ~250 KB) |
+| GET | `/api/results` | Yes | List result files |
+| GET | `/api/file?path=/results/<name>` | Yes | Read text result |
+| GET | `/api/profile` | Yes | OS, hostname, file list |
+| GET | `/api/status` | Yes | Scan phase, uploads, counts |
+| GET | `/api/download?path=/results/<name>` | Yes | Download file |
+| GET | `/api/download/bundle` | Yes | Combined text report |
+| GET/POST | `/api/config` | Yes | Auto-run / lab-scan-on-plug settings |
+
+---
+
+## Limitations
+
+- **Target needs WiFi** (built-in or USB) for Lab Scan uploads; machine joins dongle AP briefly
+- **Unlocked session** required; timing depends on boot/login speed (increase Auto-Run delay on slow PCs)
+- **OS-specific:** full Lab Scan UI path is Windows-first; Mac/Linux use terminal scripts with best-effort tools (`nmcli`, `scrot`, etc.)
+- **Network disruption:** while connected to `aether32`, the PC may drop school WiFi
+- **HID constraints:** UAC dialogs, focus stealing, non-US keyboards, and VM/USB policies can break typing
+- **Flash size:** large screenshots + many scans fill LittleFS; clear old results or reflash filesystem if needed
+- **Concurrent requests:** heavy parallel web traffic can stress the soft AP stack
+- **Legacy code:** old browser-exfil / SD-MSC paths are not in this firmware build
+
+---
+
+## Tested configuration
+
+- Board: ESP32-S3-DevKitM-1 (and similar S3 USB boards)
+- Framework: PlatformIO, Arduino-ESP32
+- Targets: Windows 10/11 (primary), macOS/Linux (partial Lab Scan)
+
+---
+
+## Planned features (roadmap)
+
+School-lab IT focus — diagnostic and inventory only (no credential harvesting).
+
+### Reliability
+
+1. **Upload acknowledgment & retry** — target retries failed POSTs until ESP32 confirms each file
+2. **STA mode + school WiFi** — ESP32 joins lab VLAN so PCs never leave corporate SSID during scan
+3. **Upload progress WebSocket/SSE** — phone sees per-file receive status in real time
+4. **Pre-flight connectivity check** — HID script verifies `192.168.4.1` reachable before typing long payloads
+5. **Graceful scan cancel** — stop in-progress collect from phone without reboot
+
+### Inventory & reporting
+
+6. **Asset tag / seat / room fields** — operator enters metadata; embedded in report filename and bundle
+7. **CSV export of all scans** — append-only log on flash for semester audits
+8. **Scan history timeline** — list past hostnames/timestamps on device; tap to re-download
+9. **Compare to golden baseline** — diff installed software/services vs. a reference machine JSON
+10. **Missing-software checklist** — flag absent apps (Chrome, Office, lab license tools) from baseline
+
+### Fleet helpers
+
+11. **Batch mode queue** — arm next N machines; auto-clear results between seats
+12. **QR code on dongle** — sticker opens captive URL + WiFi join hints for substitutes
+13. **Hostname dedup warning** — alert if scan overwrites an existing result without confirm
+14. **Scheduled plug-in profile** — weekday vs. exam-week auto-run presets
+
+### Push to PC (authorized fixes)
+
+15. **Deploy script from flash** — store `.ps1`/`.bat` on ESP32; push to `%TEMP%` and execute from phone
+16. **Typed macro sequences** — multi-step “fix printer” / “rejoin domain” without full shell scripts
+17. **Software install helper** — silent install switches for approved MSI/EXE paths (IT-provided list only)
+18. **Registry-free network reset** — documented keystroke sequence for winsock reset (with confirm)
+
+### UX
+
+19. **Light/dark theme toggle** — outdoor lab visibility
+20. **Improved mobile layout** — larger tap targets, offline-friendly cached UI shell
+21. **Pin favorites tab** — default to Collect or My Buttons per tech preference
+22. **Button color persisted** — store color index in `/btns.dat` with each command
+
+### Security appropriate for schools
+
+23. **Role-separated HTTP auth** — read-only student tech vs. admin PIN for destructive actions
+24. **Audit log on device** — who ran which trick/collect (phone session id + timestamp)
+25. **Explicit “diagnostics only” build flag** — compile-time removal of prank tricks for production lab kits
+26. **Result encryption at rest** — optional passphrase for downloads if dongle is lost
+27. **Auto-wipe results after download** — reduce data left on flash between classes
+
+---
+
+## Credits
+
+- ESP32 Arduino USB HID stack
+- Lab workflow and firmware: Dr Jones
+- Historical references (not used in current no-SD build): [HackBrowserData](https://github.com/moonD4rk/HackBrowserData), [esp32-sdcard-msc](https://github.com/atomic14/esp32-sdcard-msc)