What Linkside processes¶
Linkside looks at one client's Wi-Fi link: the frames a sensor next to it hears, and what Mist knows about it. This page lists what the sensor and the app take in, from where, what they keep and where it goes, of the client measured and of others nearby. It is written for whoever answers for that data.
No payload¶
What the client sends and receives is never passed on. The radio hands every frame on the channel to the Pi over USB; linkside-cap filters and cuts each frame there, in the kernel and once more before it writes, and nothing longer leaves the Pi:
- a data frame leaves as its MAC header and the 8 bytes of its CCMP or GCMP header: addresses, sequence numbers and flags, no byte of the payload. On an open network, unencrypted, it ends after the LLC/SNAP header, which names the protocol (IPv4, IPv6, ARP) and nothing of the packet;
- EAP ends after its type (PEAP, TTLS, TLS): no certificate, no TLS, no inner identity. Only the EAP-Response/Identity stays whole: the outer identity, which the client sends in the clear;
- management frames, control frames and the 4-way handshake (EAPOL-Key) stay whole: they are the link's own signaling. A 4-way handshake lets the passphrase of a WPA2-Personal network be guessed offline, as it does in a capture by anyone within range; with SAE (WPA3-Personal) and 802.1X it does not.
The app holds no key and decrypts nothing. The rules per frame type are in linkside-cap; the export applies them once more.
The Pi writes no frame to its disk: linkside-cap writes to its SSH channel to the Mac, over the Ethernet cable. The Pi has no gateway and no other network (a passive sensor): the Mac is the only place the frames reach. On the Mac, tshark decodes them from a pipe, without a temporary file.
What the sensor captures¶
The sensor's radios listen on the client's channel and on its most likely roam target, each with a filter on the client's addresses and its AP's:
| Capture | Takes |
|---|---|
| Discovery, finding the client | The client's frames; the beacons, probe responses and FILS Discovery of every AP heard |
| Focus, the session itself | The client's frames and the reference client's; the management and control frames of the client's AP, to every station on its BSS; every CTS and ACK to that AP |
| Reconnect, for a client known by its MLD address | The focus, and every station's authentication and (re)association requests to the AP |
| Context scan | Beacons, probe responses and FILS Discovery |
Of the client measured, that is its addresses (the one it uses on the air, with private addresses the one per network, its link addresses and its MLD address), its capabilities from its (re)association requests, the SSIDs its probe requests ask for, its outer EAP identity, and the timing, rates, signal and acknowledgments of its frames.
Of others nearby:
- the addresses of other stations, as the receiver of the AP's frames (probe responses, authentication and association responses, deauthentications, action frames, Block Acks, RTSs) and of every AP's probe responses, without a frame of their data;
- in a reconnect capture, their authentication and (re)association requests to the AP, whole;
- every network heard, with its SSID: a phone's hotspot can carry its owner's name;
- the reference client: one of the operator's own devices, beside the client on the same AP.
What the app reads from Mist¶
With the operator's token, over HTTPS to the Mist API of the org's region and nowhere else:
| Request | What comes back | What for |
|---|---|---|
The token itself (self) |
Its owner's name and e-mail, and its privileges | Whose token it is and what it may read |
| The org's sites | Their names and IDs | New Session: the site |
| The client search on the site, by hostname, username or MAC address | Per client its MAC address, hostname, username, IP address, AP, SSID, band, protocol and manufacturer | New Session: choosing the client |
| The site's connected clients, for a part of a MAC address | The same fields for every client on the site, at most 1000, asked again 30 s later at the earliest | New Session: what the site's search cannot match |
| The client's stats, about every 30 s | Mist's record of the client: signal, SNR, rates, counters, AP, BSSID, channel, hostname and Mist's other fields | The verdict and the screens |
| The client's events of the last 15 minutes, on every poll | Mist's events with their codes, latencies and text | The verdict and the Timeline |
| The site's APs and their RRM neighbors | Names, MAC addresses, radios, channels | The roam target and the path |
A request names the site and, for the stats and the events, the client's MAC address in its path. The app sends Mist nothing else: no frame, no verdict, no report.
What the app reads of the Mac¶
In New Session and while the radios capture: every 2 s whether the Mac's Wi-Fi is on and its channel, its address on the air, whether AWDL is up and the byte counters of the Wi-Fi interface (how much, not what); every 10 s at most whether Bluetooth is on (the controller's state from System Information, nothing of paired devices). They drive the warnings that the Mac's own radios disturb the measurement (the Mac is a transmitter) and are kept nowhere.
What it keeps¶
Every live session records into the recording folder of Settings, a folder per session named by the date and the client's hostname from Mist, or its MAC address where Mist has none or the address was typed in. A recording is ticket data: how long it stays and who may see it follow the rules for ticket data, and it stays until the operator removes it; the app removes none.
| File | Holds |
|---|---|
capA.pcap, capB.pcap |
Each radio's frames as the sensor cut them: everything the sensor captures, the outer identity whole among it |
capA.status, capB.status |
linkside-cap's start line and counts |
session.json |
The client's and the reference client's addresses, the capture filters with them and the BSSIDs, the channels tuned, the SSID of the client's network, the operator's label, the sensor's SSH name, the clock model and the outcome |
mist.json |
Mist's values per poll and the client's events with their codes and latencies, the AP's MAC address and the BSSID; no hostname, username, IP address or event text |
The export is written only on request, where the operator saves it (File > Export Report and Capture…):
report.md, for the ticket: the client's MAC, link and MLD addresses, the reference client's address, the label, the BSSIDs and SSIDs heard, and a hash of the outer identity (the first 8 bytes of its SHA-256, without a salt: an identity guessed can be checked against it). The report of a live session also names the client by its hostname and username, the AP by its name, and the site, from Mist;capture.pcapng: the recording's frames, cut again by the same rules, the outer identity whole among them.
Settings keep the sensor's SSH name, the tshark path, Mist's API URL, org ID and site, the recording folder and the reference client's address; the Mist token is in the Keychain. Nothing else is written: Mist's hostnames, usernames, IP addresses, search results and event texts, and the readings of the Mac, stay in memory and are gone when the window closes.
A recording that becomes test data in the repository comes from own devices only and is anonymized first: its MAC addresses, SSIDs and EAP realms replaced, the user part of the outer identity too, and the frames of other devices removed (anonymize).
Where it goes¶
- Sensor to Mac: over the Ethernet cable, SSH on an IPv6 link-local address.
- Mac to Mist: the requests above.
- Nowhere else: no telemetry, no update check, no service of Linkside's own.