290 lines
13 KiB
Markdown
290 lines
13 KiB
Markdown
# 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)
|