release: Mark VIII 1.0
This commit is contained in:
c4ch3c4d3
@@ -0,0 +1,176 @@
|
||||
# Pineapple UI Clone — Design Spec
|
||||
|
||||
- **Date:** 2026-08-11
|
||||
- **Status:** Approved (pending written-spec review)
|
||||
- **Owner:** Hak5 WiFi Pineapple Pager expansion project
|
||||
- **Supercedes look of:** `www/` assets shipped in `2026-08-10-pager-webui-design.md`
|
||||
|
||||
## 1. Goal
|
||||
|
||||
Restyle the Pager WebUI (`http://172.16.52.1:8080/`) to be a faithful clone of
|
||||
the stock Hak5 WiFi Pineapple UI (`http://172.16.42.1:1471/`), so an operator
|
||||
used to one interface can use the other without re-learning navigation,
|
||||
terminology, or interaction patterns.
|
||||
|
||||
Scope is **cosmetic + navigation only**, plus one small read-only backend
|
||||
endpoint (`GET /api/pineap/aps`, §3.5). Auth/session mechanics and the payload
|
||||
packaging pipeline are unchanged.
|
||||
|
||||
Verified on-device (2026-08-11): the Pager's Go daemon on `:1471` exposes only
|
||||
`api_ping`, `login`, payload-portal, loot, and WS endpoints — it has **no**
|
||||
`/api/pineap/*` surface. All PineAP/Recon/Logging/Settings endpoints in the
|
||||
current `server.py` are implemented by pager-webui itself via `hak5cmd`,
|
||||
`uci`, `iwinfo`, and `recon.db`. (Note: the old UI at `172.16.42.1:1471` and
|
||||
the new Pager at `172.16.52.1` are separate devices.)
|
||||
|
||||
## 2. Research Basis (live UIs, captured 2026-08-11)
|
||||
|
||||
### Old UI (:1471) — stock Angular 8 / Angular Material SPA
|
||||
- Hash routes: `#/Login`, `#/Setup`, `#/Dashboard`, `#/Campaigns`
|
||||
(`/reports`), `#/Recon` (`/handshakes`), `#/PineAP` (`/open`, `/clients`,
|
||||
`/filtering`, `/enterprise`, `/aps`, `/impersonation`), `#/Settings`
|
||||
(`/networking`, `/wifi`, `/developer`, `/advanced`, `/led`, `/help`),
|
||||
`#/Logging` (`/system`), `#/Modules`.
|
||||
- **Login:** full-screen flat gray `#9c9c9c`; centered white elevated card
|
||||
(`mat-elevation-z20`): "WiFi Pineapple" `h2`, pineapple logo PNG (148px),
|
||||
Username + Password fields, raised "Login" button (spinner while busy),
|
||||
inline red error text; Cloud C2 error variant.
|
||||
- **Shell:** 64px toolbar (`#424242`, Material `mat-toolbar`) with logo + "WiFi
|
||||
Pineapple"; content offset `margin-left: 90px`; icon rail sidenav
|
||||
(`min-width:60px`, `#f3f3f3`; dark `#3a3a3a`, hover `#a9a9a9` / dark
|
||||
`#545454`): **Dashboard, Campaigns, PineAP ("PineAP Suite"), Recon, Logging,
|
||||
Modules ("Modules & Packages"), Settings**; active entry `border-right:3px
|
||||
solid #1976d2`; entry dividers; bottom "Open Menu" chevron toggles expanded
|
||||
rail; module entries are drag-reorderable (out of scope). Content background
|
||||
`#fafafa`; Roboto/Helvetica/sans-serif font stack.
|
||||
- **Views use horizontal `mat-tab` navigation with a blue ink bar** for each
|
||||
multi-page section (PineAP, Recon, Logging, Settings, Campaigns).
|
||||
- **Dashboard:** status cards (Clients, Handshakes Captured, Disk Usage, …) +
|
||||
Chart.js line chart (clients over time) + "Connected Clients" table
|
||||
(Deauthenticate) + "Captured WPA Handshakes" table.
|
||||
- **Extras:** keyboard shortcuts (`D`/`C`/`R`/`P`/`M`, Backquote = terminal),
|
||||
light/dark theme (stored in `localStorage`), notification center, corner
|
||||
"flash indicator" toasts, ASCII pineapple `(='.'=)`.
|
||||
- **Auth:** `POST /api/login` `{username, password}` → `{token}`; stored in
|
||||
`localStorage` `<base>_authToken` + `AUTH_<ServerId>` cookie; device password
|
||||
for user `root`.
|
||||
|
||||
### New UI (:8080) — vanilla JS SPA (current source of truth)
|
||||
- GitHub-dark theme (`#0d1117` bg, `#161b22` panels, teal `#00d4aa` accent,
|
||||
Segoe UI); password-only login; flat text rail (Dashboard, PineAP, Recon,
|
||||
Handshakes, Payloads, Logs, Settings); single-page sections; bottom-docked
|
||||
xterm panel; WS live updates + 5s polling fallback; bottom-right toasts.
|
||||
- Backend: pure-socket HTTP/JSON/WS on `0.0.0.0:8080` (device
|
||||
`python3-light`); auth via `AUTH_<serverid>` HttpOnly cookie validated
|
||||
against the daemon; terminal connects directly to daemon WS on `:1471`.
|
||||
|
||||
### Feature mapping (old IA → current Pager capabilities)
|
||||
| Old tab | Clone behaviour |
|
||||
|---|---|
|
||||
| Dashboard | status cards + Chart.js chart + Connected Clients + Handshakes tables |
|
||||
| Campaigns | visible tab, single "not supported on the Pager" empty-state card |
|
||||
| PineAP → Open | PineAP settings toggles (mimic/advertise/probes/handshakes/random MAC/WiGLE) + bands |
|
||||
| PineAP → Clients | connected clients + kick |
|
||||
| PineAP → Filtering | client (MAC) + SSID allow/deny/off filters |
|
||||
| PineAP → APs | **new read-only endpoint** `GET /api/pineap/aps`: `iwinfo <mon-iface> scan` table (BSSID/SSID/Channel/Signal/Encryption) |
|
||||
| PineAP → Impersonation | SSID pool add/clear + Start/Stop/Collect |
|
||||
| PineAP → Enterprise | **omitted** (not supported on Pager) |
|
||||
| Recon → Overview | scans list + new/stop/refresh + scan detail |
|
||||
| Recon → Handshakes | loot files: download zip / archive / delete |
|
||||
| Logging → Overview | system + PineAP logs |
|
||||
| Logging → System | system log with level filter (Error/Warning/Informational) |
|
||||
| Modules & Packages | payload portal (search + list + Install/Remove) |
|
||||
| Settings | general info, hostname, NTP, password, WebUI prefs (poll interval, theme) |
|
||||
|
||||
## 3. Design
|
||||
|
||||
### 3.1 Architecture
|
||||
No build step; same vanilla-JS file layout. New/vendored files under `www/`:
|
||||
|
||||
- `assets/logo.png` + favicon — copied from old UI `assets/icons/logo.png`.
|
||||
- `js/chart.min.js` — vendored Chart.js from old UI (no CDN on device).
|
||||
- `js/icons.js` — inline SVG icon set lifted from the old Angular bundle
|
||||
(dashboard grid, campaigns, pineap, recon, logging, modules, settings,
|
||||
chevron).
|
||||
- `js/themes.css` or CSS custom properties — light/dark token sets.
|
||||
- `css/app.css` — rewritten around Material light tokens.
|
||||
- `js/views.js` — restructured to old IA with sub-views + `mat-tab`-style bars.
|
||||
- `js/app.js` — routing (incl. sub-routes), keyboard shortcuts, theme toggle,
|
||||
terminal wiring, flash-style toasts.
|
||||
- `index.html` — old-style shell markup (login card, toolbar, icon rail,
|
||||
content, terminal panel).
|
||||
|
||||
Roboto: vendor `.woff2` from the device if present (`:1471/assets/` fonts);
|
||||
otherwise the existing `Roboto, Helvetica Neue, sans-serif` stack falls back to
|
||||
system fonts.
|
||||
|
||||
### 3.2 Design tokens (light default, dark optional)
|
||||
- Light: content `#fafafa`; cards `#fff` with subtle elevation/shadow; toolbar
|
||||
+ rail `#424242`; rail hover `#a9a9a9`; active border `#1976d2`; primary
|
||||
`#1976d2` / `#1e88e5`; danger `#d32f2f`; ok `#7cb342`; warn `#f9a825`; text
|
||||
`#212121` / muted `#686868`; ink bar + focus `#1976d2`.
|
||||
- Dark (mirrors old theme): rail `#3a3a3a`, hover `#545454`, surfaces `#303030`,
|
||||
cards `#424242`.
|
||||
- Theme selected via `<html class="dark">` driven by `localStorage`; toggle in
|
||||
Settings (and honored on all pages).
|
||||
|
||||
### 3.3 Shell
|
||||
- **Toolbar (64px, `#424242`):** logo + "WiFi Pineapple" brand (left); right:
|
||||
muted live status "BAT % · CLIENTS n", Terminal button.
|
||||
- **Icon rail (60px):** 7 entries, 24px inline SVG + label (label hidden while
|
||||
collapsed, `title` tooltip shown), dividers between groups, active = 3px blue
|
||||
right border. Bottom "Open Menu" chevron expands to ~200px with labels;
|
||||
state persisted in `localStorage` (mirrors old `sideNavState`).
|
||||
- **Content (`#fafafa`):** page header + horizontal tab bar (where applicable)
|
||||
+ white cards; existing `.section`/`.tbl`/`.badge`/`.row`/`.toggle` classes
|
||||
restyled to the light theme.
|
||||
- **Terminal:** stays bottom-docked (new behaviour) but restyled to the old
|
||||
look; kept docked intentionally (matches current Pager UX and spec v1).
|
||||
- **Toasts:** corner "flash indicator" style (old look), same API.
|
||||
|
||||
### 3.4 Login
|
||||
Password-only (per user decision; username fixed `root`). Full-screen gray
|
||||
`#9c9c9c`; centered white elevated card: logo, "WiFi Pineapple" `h2`, single
|
||||
Password field (placeholder "Password"), raised primary Login button with busy
|
||||
spinner, inline red error text on failure. Posts to the existing `/api/login`
|
||||
endpoint via `PagerAPI.login('root', pw)` — **no backend change**.
|
||||
|
||||
### 3.5 Views (per mapping table)
|
||||
Each multi-page section renders a `mat-tab`-style horizontal bar (blue ink
|
||||
bar) with tab items; deep-linkable via hash routes `#/pineap/clients` etc.
|
||||
Placeholder Campaigns uses the old empty-state card.
|
||||
|
||||
**PineAP → APs** requires one new backend route. Add to `server.py`:
|
||||
`GET /api/pineap/aps` → runs `iwinfo <iface> scan` over the monitor interfaces
|
||||
listed by `/api/status` and returns rows `{bssid, ssid, channel, signal,
|
||||
encryption}` (read-only, no root action, same exposure class as the existing
|
||||
`/api/status`). A unit test covers the parser with a canned `iwinfo` capture.
|
||||
|
||||
### 3.6 Data flow
|
||||
Unchanged: `PagerAPI` (fetch wrapper), `Live` WS + 5s poll fallback, `Live.onTick`
|
||||
drives the dashboard chart's rolling series (e.g. last 60 samples of clients +
|
||||
handshakes). Theme and rail state live in `localStorage`. The single new route
|
||||
is `GET /api/pineap/aps` (§3.5).
|
||||
|
||||
### 3.7 Error handling
|
||||
Unchanged: failed API calls surface via toasts; login failure shows inline red
|
||||
text; WS down → poll fallback (existing logic untouched).
|
||||
|
||||
## 4. Testing
|
||||
|
||||
- Manual on-device smoke pass per spec v1 §8: every page in background and
|
||||
foreground modes, login/logout, terminal I/O, reboot persistence.
|
||||
- Visual parity checklist: login card, toolbar, rail expand/collapse + active
|
||||
indicator, each tab bar, table/card styling, dark theme.
|
||||
- Asset checks: `logo.png`, favicon, `chart.min.js`, Roboto (if vendored) all
|
||||
serve from `:8080`; verify with `curl`.
|
||||
- Existing Python `unittest` suite (API-level) must remain green; add a test for
|
||||
the new `iwinfo` scan parser.
|
||||
- Deploy via `scripts/deploy.ps1` (existing pipeline); payload zip must include
|
||||
the new/vendored assets.
|
||||
|
||||
## 5. Out of scope
|
||||
|
||||
- Campaigns functionality, Cloud C2, Enterprise SSIDs, LED/Network/Developer
|
||||
Settings sub-pages, module drag-reorder, notification center, `:1471`
|
||||
takeover.
|
||||
Reference in New Issue
Block a user