Starchorus 0.2.0-dev.1 (development build)

A development build of the 0.2 branch, published as a pre-release for trying out. The stable release is 0.1.1; this build is not in the Hak5 payload library and will not be sent there.

Two things are new and both are off by default: a passive Bluetooth LE window (Settings > Bluetooth) and a Traffic read (Settings > Traffic). Neither transmits anything. Both have passed the project's own regression and self-tests, but their cost and behaviour on the Pager itself have not been measured yet; that is what the 0.2 work does next. Treat them as a preview.

What is in it

• Bluetooth, opt-in. A passive LE scan of six seconds per refresh, read back from the controller's own traffic: a window counts only when the monitor shows the scan was set passive before the first report. The page draws what it hears as small triangles by signal, folds rotating addresses by company and signal ring, and hides them with key 4 or the BT button. The Overview gains a Bluetooth screen.
• Traffic, opt-in. Channel activity from the AP service's own channel counters as a relative share per frequency (whiskers in the channel bar, text bars on the Bands screen), and a cue on stations from the frames heard per second.
• PMF derived. An access point's detail reads 'PMF: yes (derived)' where its class guarantees it, 'PMF: unknown' otherwise.
• 2D zoom. The 2D sky zooms out to half size; on a desktop the zoom and reset buttons show in 2D as well.
• Named probes. Probe requests are worded as named ones throughout, because the data cannot say that a station sent a wildcard.
• Large text. The masthead and the source panel keep their shape under a browser's minimum font size and a wide fallback face, as an in-car browser showed.
• Fixes. Hidden networks judged by the newest beacon row; labels near the edge of the sky kept inside it; SAE plus PSK counted as transition; the keyboard help scrolls on short windows; a 2D zoom no longer leaks into the 3D bubble counters.
• Checks. The passivity check denies the Bluetooth stack by tool name and the firmware's other outward commands by prefix, and reads for command names built at run time. The device probe answers the Bluetooth questions from sysfs alone.
• Contract 3. Two new settings keys reach the collector through the environment; a new payload with an old collector would otherwise show 'Bluetooth: ON' and get nothing.

Installing

The archive unpacks to one directory, starchorus/, with the same seven files as 0.1.1. Install it the same way as 0.1.1 (the README inside says how); the payload copies the files into /root/loot/starchorus on its first run and notes a version skew against an older installation. To go back, install the 0.1.1 archive again.

Checksums

See SHA256SUMS next to the archive.

Starchorus 0.1.1

Most of what changed in 0.1.1 is the page showing less. A Pager on a desk heard one nearby device that changed its address every forty-odd seconds, and 0.1.0 drew it faithfully: a couple of hundred satellites at the same signal strength, a private Milky Way across the middle of the sky. The data was correct and the picture was wrong. A visualiser earns its keep by knowing the difference, so a device like that is now one cloud, named for what it is, and a key shows or hides the addresses behind it for anyone who wants to count them.

The same instinct runs through the rest. When a phone walked out of the Pager's Wi-Fi the chip said 'Stale', which blamed the capture for the page's own deafness; it now says 'Offline' when the Pager cannot be reached and keeps 'Stale' for a Pager that answers with an old capture. On a phone the panels used to sit on top of the sky; the sky now has the whole screen and the panels live in a sheet you pull up when you want them. The Pager's own menu has two rows at rest, Start and Settings, and a QR code that opens the page on your phone, on the view that a menu which needs explaining has too much in it. The Overview on the small screen used to redraw itself every few seconds and listen for keys only in between; it now draws when asked and then waits, so a press is never lost.

Underneath, the collector does about a quarter less work per cycle on the Pager's one core, the Overview on the small screen runs one jq pass per screen where it ran seventeen, and the page polls in step with the collector instead of every five seconds. The version number is 0.1.1 because nothing you knew how to do is different. What has gone is the part you had to put up with.

What changed

Added

• Pager menu: 'Starchorus: Stopped' offers 'Start' and 'Settings', and 'Starchorus: Running' offers 'Overview', 'Open on Phone', 'Stop' and 'Settings', worked out afresh at every draw from the processes themselves.
• 'Open on Phone' shows the page's address as a QR code, and 'Start Web Page' takes its place while the page server is not up.
• Phone layout: the sky keeps the screen under a narrow status bar, and the controls move into a bottom sheet with three heights: a peek, half and full.
• On a phone held on its side, the status bar and the sheet form a column on the left, and every edge keeps clear of the device's safe areas.
• Hide panels (key U, at any screen size) leaves the sky alone with a small status pill that brings the panels back.
• Random clouds: free randomised addresses heard in one signal band, in bursts that recur at a steady period, are drawn as one cloud with its count, and its detail gives the period and lists the addresses. A period counts only when it stands clear of what unrelated bursts in that band would give by chance, so two devices of different periods at one signal are two clouds, and bands whose periods match are merged; a band is judged on its newest 1,500 bursts.
• A cloud whose bursts keep no one rhythm (a rhythm share below 0.6) is mixed: its detail reads 'no one rhythm' in place of a period, and the page words it 'possibly one or more nearby devices' where it would say 'probably one nearby device'.
• Random (key X, ?random=cloud|show|hide) cycles between clouds, the addresses one by one, and hidden; the legend reads 'n randomised MAC · k in m clouds', and the randomised and cloud counts also appear in the statistics and the inventory.
• The Overview counts clouds by the same rule, capture by capture, in its summary ('Clients 247 free (245 random, 1 cloud)') and shows each one as a single line on the Stations screen.
• The Overview shows 'No new scan for …' in red, on every screen, when the collector has not written a capture for more than three of its intervals.
• A setting that an environment variable fixes shows '(locked)' in Settings, and its row opens a note instead of changing.
• Page query parameters ?phone=1|0, ?panels=0|1 and ?random=cloud|show|hide.
• The page's favicon is inline, so the page still fetches nothing but starchorus.json.
• The payload compares the version and the new # Contract: header of the installed collector and Overview with its own, and says so once in a dialogue when they differ.
• The collector's log says when the vendor cache grows and, once per episode, why a merge into it did not happen.
• The opt-in STARCHORUS_SOURCE=pineap reads the AP service's own recon list with one bounded read-only command, RECON DEVICES (with STARCHORUS_PINEAP_CALLS=full, RECON APS and RECON DEVICES unbounded); it is experimental and not cheaper on the Pager than the database path, which stays the default.
• New environment variables for the collector: STARCHORUS_TMPDIR (where the work copy of recon.db lives, /tmp by default), STARCHORUS_SKIP_UNCHANGED (0 turns the skipping of unchanged cycles off) and STARCHORUS_PINEAP_CALLS (recent or full, for the pineap source only).

Changed

• The Pager menu is shorter: 'Start' and 'Stop' ask nothing, and the rows Dashboard, Services, Options, Status and Exit are gone.
• Settings rows flip in place ('Web Page: ON'), a change made while Starchorus runs is applied when you leave Settings (except 'Web Page', which takes effect at once), and only 'Reset to Defaults' asks first.
• The 'Refresh' and 'Show Last' lists have no 'Other' row. They offer 10 s, 30 s, 1 min and 2 min, and 2 min, 10 min, 1 h, 6 h and 'All (may be slow)'; other values go through payload.sh set.
• Every menu title and row is in Title Case, as in the Pager's own settings.
• Own radios, opening the Overview after 'Start' and switching the collector off are no longer settings: they remain the environment variables STARCHORUS_OWN, STARCHORUS_DASHBOARD and STARCHORUS_COLLECTOR, and an old line for them in settings.conf is skipped.
• 'Start' keeps its spinner up until the first scan since that 'Start' has been written (up to 20 seconds) and then opens the Overview on its summary; key B in the Overview goes up one level, from a screen to the list of screens and from the list to the menu.
• The Overview's first line is 'Overview'. It draws a screen and then waits for a key with no time limit, and never redraws by itself: key A draws the screen again, key B goes up one level (a screen, then the list of the seven screens, then the menu), Left and Right step through the screens, and Up and Down are ignored. 'Reading...' shows while a scan is read, each screen ends with the time of its scan ('Last scan 12:04:31 (42 s ago)') and the keys ('A: Refresh B: Back'), and it reads 'Waiting for the first scan.' until the first scan after 'Start'.
• The page turns 'Stale' when no new capture has come for twice the interval the file announces plus 15 seconds (at least 30 seconds), where it used to count six polls.
• The page says 'Offline' (WarGames 'Link down', Whitehall 'No link') where it said 'Stale' when the Pager has not answered the last three polls by then, as when a phone leaves its Wi-Fi; 'Stale' stays for a Pager that answers with an old capture.
• The page polls in step with the collector, shortly before the next capture is due and then every 2 seconds until it arrives, about three requests per 30-second capture where it made six.
• The replay banner counts captures, not polls, and the signal-over-time axis follows the observed spacing of the captures.
• The page keeps the history of a vanished station for 300 seconds of capture time instead of 60 polls, and an announced interval is capped at 600 seconds.
• The Random switch starts on 'clouds', so a busy sky shows fewer single dots than before.
• The CSV export gains a trailing cloud column. With clouds present, the JSON export gains a clouds array, a station in a cloud carries cloud, and station_counts adds randomised and in_clouds; the SITREP lists the stations outside clouds.
• The collector works on a copy of recon.db in RAM instead of on flash, and reads it with one sqlite3 process per cycle instead of four to seven.
• The collector skips a cycle whose database has not changed since the last full pass, and republishes that pass with a new generated.
• A collector cycle takes 265 to 266 ticks of 10 ms of the Pager's CPU where 0.1.0 took 369 to 376, about 28 per cent less, measured one straight after the other on the same data (29 access points, about 299 stations, vendor cache warm).
• A new vendor prefix costs about half a second where it cost about 14 s, because the OUI file is split once by first octet and a lookup reads only the files it needs. The split is made when the collector first starts with the new version (about 8 to 10 s of CPU; 512 files, 2.2 MB, under cap/oui-index beside starchorus.json), so the first capture after an upgrade comes later than usual.
• The security label is decoded from the encryption bits in one walk that stops at the highest bit set, instead of a separate test for each possible bit.
• The Overview runs one jq process per screen and reuses the result while the capture is unchanged, so a screen costs CPU (1.8 s for the summary) only when it is drawn on a new capture and nothing while the Overview waits for a key (0.1.0: 4.6 s every 4 s). A scan that takes jq more than 20 seconds to read ends as 'This scan took over 20 s to read.' with the hint 'Try Settings > Show Last: 1 h.'.
• The collector, the page server and the Overview, as the payload starts them, run at nice 19, so that the Pager's own services come first.
• The netcat page server sends the page with Cache-Control: max-age=60 and starchorus.json with no-store, where both used to be no-store.
• tools/install.sh reads the six files back and compares them byte for byte, and no longer counts the Pager's missing cksum as a warning.
• Documentation: the netcat server is described as the normal page server on an updated Pager, and the Quick Start, the installation guide and the payload's READMEs go through the payload.
• Documentation:...

Starchorus 0.1.0

Starchorus 0.1.0: the first release.

Starchorus is a strictly passive Wi-Fi observation tool for the Hak5 WiFi Pineapple Pager: it
receives and never transmits. A POSIX shell collector on the Pager reads what is on the air anyway
and writes starchorus.json. A self-contained HTML page draws the radio environment from it as a
slowly turning night sky: the device at the centre, access points as stars (distance = signal
strength), clients as satellites, band as colour, encryption as a ring.

Included

• starchorus-collect.sh: the collector (POSIX/BusyBox, read-only)
• starchorus.html: the visualisation, a single file with no external dependencies, with a demo mode
• starchorus-display.sh: an overview on the Pager's own display
• starchorus-serve.sh: a small fallback server
• library/user/reconnaissance/starchorus/: the payload, with its menu and settings
• INSTALL.md: step-by-step installation on macOS, Linux and Windows

The page is served on the Pager's management address only (USB-C and management Wi-Fi) by default.
Checked on a Pager with firmware 24.10.1.

Licence: GPL-3.0-or-later. The embedded font is under the SIL Open Font License 1.1.

_{Hak5, WiFi Pineapple and WiFi Pineapple Pager are trademarks of Hak5 LLC. Starchorus is an independent project and is not affiliated with, sponsored or endorsed by Hak5.}