216 lines
11 KiB
Markdown
216 lines
11 KiB
Markdown
# Recon Mark VII Parity — Design Spec
|
||
|
||
- **Date:** 2026-08-11
|
||
- **Status:** Approved
|
||
- **Owner:** WiFi Pineapple Pager expansion project
|
||
- **Applies to:** `payload/user/general/pager-webui/www/` (front-end) and
|
||
`payload/user/general/pager-webui/server.py` (one backend change)
|
||
|
||
## 1. Goal
|
||
|
||
Rework the Pager WebUI Recon section so it looks and behaves as close as
|
||
possible to the stock Hak5 WiFi Pineapple (Mark VII) UI's Recon at
|
||
`http://172.16.42.1:1471/#/Recon`, using only data the Pager backend already
|
||
exposes plus one small optional-body change to `POST /api/recon/start`.
|
||
|
||
Source of truth for the Mark VII layout: the Angular bundle
|
||
`main.ce5a318adf590e170f6d.js` (captured 2026-08-11, cached at
|
||
`%TEMP%\opencode\oldui_main.js`). The scanning component (`app-scanning-view`)
|
||
template, component CSS, and Chart.js configs were extracted from it.
|
||
|
||
## 2. Mark VII Reference (extracted from bundle)
|
||
|
||
### Scanning page (`/Recon`, tab "Scanning")
|
||
|
||
```
|
||
div.recon-title-card-container (flex, wrap, justify: space-between, gap 10px)
|
||
div.recon-title-card-latest-overview
|
||
mat-card (height: 200px)
|
||
mat-card-title "Wireless Landscape" (font-size 20px)
|
||
mat-card-content > div > div.recon-wifidata-chart-container
|
||
canvas#landscapeChart (doughnut)
|
||
div.recon-center-text > span.recon-no-data " No wireless landscape data is available yet. "
|
||
div.recon-title-card-latest-overview "Channel Distribution" → canvas#channelChart (bar)
|
||
div.recon-title-card-latest-overview
|
||
mat-card (height: 200px)
|
||
mat-card-title > a.recon-card-title-link [routerLink /Recon/handshakes] " Handshakes "
|
||
content: <span font-size:32px><b>{totalHandshakes}</b></span>
|
||
<span color:grey>Handshakes Captured</span>
|
||
<mat-slide-toggle>Automatically Collect Any Handshakes</mat-slide-toggle>
|
||
div.recon-title-card-latest-overview
|
||
mat-card (height: 200px)
|
||
mat-card-title "Previous Scans"
|
||
content: mat-form-field (width 100%) > mat-label "Previous Scan" + mat-select
|
||
button[mat-icon-button] mat-icon "file_download"
|
||
button[mat-icon-button] mat-icon "delete"
|
||
|
||
mat-card (scan bar)
|
||
mat-card-content > div (height 48px, flex align-center)
|
||
mat-slide-toggle "Scan" (reconToggleState → startRecon/stopRecon)
|
||
div (margin-left 20px) mat-select (width 100px) scan_time
|
||
options: 30 Seconds/1 Minute/2 Minutes/5 Minutes/10 Minutes/Continuous
|
||
div (margin-left 20px) mat-select band (0 = 2.4GHz, 1 = 5GHz, 2 = 5GHz-DFS)
|
||
span[fxFlex] spacer
|
||
button[mat-icon-button] mat-icon "settings" (opens settings sidebar)
|
||
|
||
div (position: relative; min-height: 500px)
|
||
div.recon-scan-results-card
|
||
mat-card
|
||
mat-card-content
|
||
div (48px row) [AP table header: search mat-form-field "Search" + mat-paginator]
|
||
mat-table APs columns: SSID, MAC, Clients, OUI, Sec, WPS, MFP, Chan, Sign, FirstSeen, LastSeen
|
||
mat-card-content [Clients table: search + mat-paginator]
|
||
mat-table Clients columns: Client MAC, Signal, Channel, First seen, Last seen
|
||
```
|
||
|
||
Charts (from `generateLandscapeChart` / `generateChannelChart`):
|
||
- Landscape: `type:"doughnut"`, labels `["Access Points","Clients","Unassociated"]`,
|
||
backgroundColor `["#2ecc71","#2980b9","#8e44ad","#e74c3c"]`, `legend:{position:"bottom"}`.
|
||
- Channel: `type:"bar"`, one bar per channel sorted ascending, no legend, each bar
|
||
a color from a 64-color array, `yAxes:[{ticks:{reverse:!1,stepSize:1,min:0}}]`.
|
||
|
||
Component CSS (key rules, light theme):
|
||
- `.recon-title-card-container{display:flex;width:100%;flex-wrap:wrap;justify-content:space-between}`
|
||
- `.recon-title-card-latest-overview{flex:1;margin-bottom:1em}`
|
||
- `.recon-title-card-title{font-size:20px;margin-bottom:15px;display:flex;align-items:center}`
|
||
- `.recon-card-title-link{color:inherit;text-decoration:none}` `:hover{text-decoration:underline}`
|
||
- `.recon-title-card-content{display:flex;justify-content:center;align-items:center;height:70%}`
|
||
- `.recon-no-data{font-style:italic;color:#787878;display:flex;justify-content:center}`
|
||
- `.recon-scan-results-card{width:100%}`
|
||
- table rows cursor pointer; `.recon-table-row-active{background-color:#eaeaea}`
|
||
- dark: `.recon-table-row-active-dark{background-color:#565656}`
|
||
|
||
Tabs: Recon has exactly two tabs — `[Scanning → /Recon]`, `[Handshakes → /Recon/handshakes]`. No Events tab.
|
||
|
||
### Handshakes page (`/Recon/handshakes`)
|
||
Card "Captured WPA Handshakes" (title flex, settings icon button at right),
|
||
`table-container` with `mat-table`: columns `BSSID, Client, Source, Type, Captured,
|
||
Message 1, Message 2, Message 3, Message 4, Beacon Frame, [action]`. Rows show
|
||
M1–M4 check/close/missing glyphs. Delete + download per row.
|
||
|
||
## 3. Design (Pager)
|
||
|
||
### 3.1 Tabs
|
||
`RECON_TABS` becomes two entries: **Scanning** (`#/recon`) and **Handshakes**
|
||
(`#/recon/handshakes`). Remove `views.recon_events`, the `#/recon/events`
|
||
route in `app.js`, and the old `views.recon_events` definition. Backend
|
||
`GET /api/recon/events` is left untouched.
|
||
|
||
### 3.2 Scanning view layout (`views.recon`)
|
||
Mark VII structure implemented with vanilla JS `h()` helpers and existing
|
||
`PagerAPI` endpoints. State per scan: `GET /api/recon/scans` → list;
|
||
`GET /api/recon/scans/{id}` → detail `{scan, aps[], clients[], handshakes[]}`.
|
||
|
||
- **Title cards row** (`.recon-title-card-container`, 200px cards):
|
||
1. **Wireless Landscape** — `MiniChart.doughnut` with legend; segments
|
||
`[Access Points, Clients, Unassociated]` = `[aps.length, clients.length, 0]`,
|
||
colors `#2ecc71 / #2980b9 / #8e44ad`; placeholder text when no data.
|
||
2. **Channel Distribution** — `MiniChart.bar`; per-channel counts from
|
||
detail APs (unknown channel grouped as `?`), Mark VII 64-color palette,
|
||
no legend, Y step 1.
|
||
3. **Handshakes Captured** — 32px bold count = selected scan handshakes
|
||
length; grey "Handshakes Captured" subtitle; "Automatically Collect Any
|
||
Handshakes" slide toggle wired to `GET/POST /api/pineap/settings`
|
||
(`collect_handshakes`); card title links to `#/recon/handshakes`.
|
||
4. **Previous Scans** — "Previous Scan" select (newest first, `Scan #id — time`
|
||
labels), `file_download` icon button → existing
|
||
`/api/recon/scans/{id}/download/json`, `delete` icon button → existing
|
||
`DELETE /api/recon/scans/{id}` (confirm dialog), refresh via poll.
|
||
- **Scan bar card** (48px row): "Scan" slide toggle (`POST /api/recon/start|stop`),
|
||
Duration select (30 Seconds / 1 Min / 2 Min / 5 Min / 10 Min / Continuous),
|
||
spacer, `settings` icon button → settings sidebar. No Band select (Pager
|
||
cannot single-band scan). Duration persisted in `localStorage`
|
||
(`pw_scan_duration`) and sent on start.
|
||
- **Results area** (`min-height:500px`), one card per table, each with a
|
||
Material-look "Search" field (client-side filter) and a paginator
|
||
(10/25/50/100, first/last/prev/next buttons, "1–10 of N" range label):
|
||
- **Access Points** — columns SSID, BSSID, Channel, Signal, Encryption,
|
||
Hidden; row click selects the AP (highlight) — no focus sidebar (backend
|
||
has no scan-AP deauth/capture APIs).
|
||
- **Clients** — columns MAC, Signal, Frequency, Packets.
|
||
- **Settings sidebar**: fixed right panel (top 64px, width 270px, shadow,
|
||
close button). Section "Access Points": Show SSID/MAC/Channel/Signal/
|
||
Encryption/Hidden toggles. Section "Clients": Show MAC/Signal/Frequency/
|
||
Packets toggles. Persisted as JSON in `localStorage` key `pw_recon_cols`.
|
||
- **Polling**: refresh scans/detail every 10s while the view is mounted
|
||
(destroy clears interval), same as today's behaviour (interval bumped from
|
||
15s → 10s to keep charts/table fresh).
|
||
|
||
### 3.3 Handshakes view (`views.recon_handshakes`)
|
||
Restyle to Mark VII look: card title "Captured WPA Handshakes" with a
|
||
`settings` icon button (non-functional on Pager; omitted or rendered as a
|
||
disabled hint — render it, clicking shows a toast "Settings not available on
|
||
Pager"). Table `File / Type / Size / Modified` plus per-row `Download` and
|
||
`Delete` actions (existing `/api/pineap/handshakes` endpoints + `/api/loot/zip`
|
||
for "Download all"). Keep existing zip/archive actions row.
|
||
|
||
### 3.4 Charts (`js/chart.js`)
|
||
- `MiniChart.doughnut(canvas, segments, { legend: true, height })` — redraw as
|
||
a true doughnut (inner hole via `arc` ring) and draw a legend row beneath
|
||
(color dot + label) when `legend` is set.
|
||
- `MiniChart.bar(canvas, items, opts)` — items `{label, value, color}`; draws
|
||
Y gridlines, bars from baseline, X labels, `maxY = ceil(max/1)`; Mark VII
|
||
palette cycles through `items[].color`.
|
||
- Keep existing `MiniChart.draw` (line) for the dashboard unchanged.
|
||
|
||
### 3.5 Icons (`js/icons.js`)
|
||
Add to `PineappleIcons`: `refresh`, `file_download`, `delete`, `settings`,
|
||
`search`, `first_page`, `last_page`, `chevron_left`, `chevron_right`
|
||
(Material Design path data; `wifi`/`extension`/`receipt` already present).
|
||
|
||
### 3.6 CSS (`css/app.css`)
|
||
Add Mark VII recon styles (light + `html.dark`): `.recon-title-card-container`,
|
||
`.recon-title-card`, `.recon-title-card-title`, `.recon-card-title-link`,
|
||
`.recon-title-card-content`, `.recon-no-data`, `.recon-chart-box`,
|
||
`.recon-scan-bar`, `.recon-scan-bar .sel`, `.recon-search`,
|
||
`.recon-paginator`, `.recon-settings-sidebar`, `.recon-settings-section`,
|
||
`.recon-settings-toggle`, `.recon-settings-close`, `.recon-row-selected`.
|
||
Card background follows `--surface`; title cards get the existing elevation
|
||
shadow; dark overrides via `html.dark`.
|
||
|
||
### 3.7 Backend (`server.py`)
|
||
`h_recon_start(ctx)` forwards an optional `scan_time` from the request body to
|
||
the daemon:
|
||
|
||
```python
|
||
def h_recon_start(ctx):
|
||
body = {}
|
||
scan_time = (getattr(ctx, 'body', None) or {}).get('scan_time')
|
||
if scan_time is not None:
|
||
body['scan_time'] = int(scan_time)
|
||
status, data = daemon_sock_call('POST', '/api/pineap/log/recon/start', body=body)
|
||
...
|
||
```
|
||
|
||
Default remains `{}` when no `scan_time` is sent, so the current behaviour is
|
||
unchanged. (Whether the Pager daemon honours `scan_time` is up to the daemon;
|
||
the UI persists and sends it either way.)
|
||
|
||
### 3.8 Routing (`js/app.js`)
|
||
Remove `'#/recon/events': 'recon_events'` from the `routes` map. No other
|
||
route changes.
|
||
|
||
## 4. Data flow
|
||
Unchanged API surface (except optional `scan_time` on recon start). The view
|
||
loads scans, auto-selects the newest, fetches the detail, renders charts +
|
||
tables, and re-fetches on a 10s interval. Search/pagination/column settings
|
||
are client-side state (`localStorage` keys `pw_scan_duration`, `pw_recon_cols`).
|
||
|
||
## 5. Testing
|
||
- Python: extend `tests/test_recon.py` `DaemonSockTest` with a case asserting
|
||
`h_recon_start` forwards `{'scan_time': 60}` when present and `{}` otherwise
|
||
(existing socket tests must stay green).
|
||
- Front-end: manual on-device smoke pass — every element of the scanning page,
|
||
tabs (2), scan start/stop, duration persistence, auto-handshake toggle,
|
||
previous-scan select + download + delete, table search/pagination, column
|
||
settings sidebar + persistence, handshakes page, dark theme, keyboard
|
||
shortcut `r`.
|
||
- Deploy via `scripts/deploy.ps1`; `curl` the served JS/CSS assets for 200.
|
||
|
||
## 6. Out of scope
|
||
- AP/client "focus" sidebars (deauth/capture/clone) — no backend support.
|
||
- 2D/3D cartography graph view — no AP↔client association data.
|
||
- Chart.js dependency — hand-rolled canvas rendering with identical palettes.
|
||
- Events tab, band select, "highlight active devices" aux settings.
|
||
- Backend removal of `/api/recon/events`.
|