# 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)