ZeroTrace Companion
Device Library
The persistent known-device catalog — every device ever seen across all sessions, with merged identity across MAC randomisation.
The library is the long-running memory of the AirLeak workspace. Every device observed across every session feeds the library. The library is what lets Companion answer "have I seen this device before?" — across days, weeks, months of intermittent capture.
It is the central feature that distinguishes Companion from a generic packet capture tool.
What the library stores
For each known device:
| Field | What it stores |
|---|---|
| Identity kind | What underlying signal we use to match this device across sessions (Apple Continuity model, BLE name pattern, AirTag ID, fingerprint) |
| Primary MAC | The most-recent MAC observed for this device |
| Alt MACs | Every other MAC the device has used (MAC randomisation history) |
| Vendor | OUI-derived vendor when stable across sessions |
| Apple model | Apple Continuity model when applicable |
| BLE name | Friendly BLE name when advertised |
| Probed SSIDs | Every Wi-Fi network this device has ever asked for (across all sessions) |
| Class history | Behavioural classifications observed over time |
| Sessions seen in | The list of sessions where this device appeared, with per-session observation counts |
| First-seen / last-seen (across all time) | When this device first appeared in any session and when it was last seen |
This composite picture is what makes the library powerful. A user's phone may appear with a different MAC every session, but the library merges them all behind a single identity.
How merging works
Devices merge into a single library entry when one of these matches across sessions:
- Apple Continuity model identifier — Apple devices broadcast model strings (iPhone 14 Pro, AirPods Max, etc.) that change far more slowly than their MAC.
- AirTag identifier — Apple AirTags broadcast a stable identifier rotated on a long cycle.
- BLE name pattern — devices that broadcast a custom name (often deliberately) match across MAC changes.
- Behavioural fingerprint — for advanced cases, observed behaviour patterns (probe-request sequence, advertising interval, capability bits) form a fingerprint.
The merging is conservative — Companion errs toward "two separate library entries that might be the same device" over "one merged entry that incorrectly combines two different devices."
For the cases where merging fails, manual merge is available — pick two library entries, click Merge.
The library is most useful for surveillance-detection and persistent-presence work. "Has this device been around the office before?" is one query the library answers in seconds; without it, you'd be cross-referencing multiple sessions by hand.
The library view
The library view is a sortable / filterable table:
| Column | What it shows |
|---|---|
| Identity | Best-available identifier (Apple model, BLE name, MAC) |
| Vendor | OUI-derived |
| First seen | First-ever observation across any session |
| Last seen | Most-recent observation |
| Session count | How many sessions this device has appeared in |
| MAC count | How many distinct MACs this device has used |
| SSID count | How many distinct probed SSIDs |
Click any row for the per-device detail.
Per-device detail
The detail view shows the device's full history:
- Identity provenance — what signals merged the device's MACs into one entry.
- MAC history — every MAC observed, with first-seen and last-seen dates.
- SSID history — every Wi-Fi network this device has probed for, with first / last seen.
- Class observations — every behavioural classification, with confidence.
- Sessions — every session this device appeared in, with per-session observation count and a click-through to the session.
The SSID history is particularly informative — it accumulates across sessions, often building a "social network" picture of the user behind the device (their home, their work, their gym, the cafés they frequent).
Filtering and search
The library supports:
- Free-text search — across MAC, name, SSIDs probed, vendor.
- Filter by Apple model — every iPhone, every AirPod, every MacBook.
- Filter by vendor — every Samsung, every Sony, every Bose.
- Filter by SSID match — find every device that has probed for a specific network.
- Date range — devices first seen / last seen in a given window.
The SSID-match filter is one of the most useful: paste an SSID and find every device in your library that has ever asked for that network.
Manual entries
You can mark a library entry with a friendly name ("Alice's iPhone", "Bob's AirPods Pro", "office printer"). Friendly names appear in the live view, the devices view, the alerts, and exports — making subsequent investigations dramatically easier to read.
Pinning and tagging
Library entries can be:
- Pinned to the live workspace's watch list (always visible in current sessions).
- Tagged with arbitrary tags ("known-good", "suspicious", "follow-up").
- Hidden from default views (for noise reduction).
Library size and management
Practical limits:
- The library is paged from disk — memory usage stays bounded even with millions of historical observations.
- Per-device fields cap at sensible limits (max alt MACs, max probed SSIDs, max class history) to prevent unbounded growth from extreme outliers.
- The full library is stored under your application data directory as JSON.
For very long-running deployments, you can purge the library or archive an old library and start fresh. Settings → AirLeak → Library has the controls.
Privacy
The library is the most identity-rich data the AirLeak workspace produces. A few principles:
- Local only. The library never leaves your machine unless you export it.
- No friendly names by default. You assign them deliberately; nothing is auto-named with PII.
- Merging is observable. The detail view shows you exactly which signals merged which MACs — no hidden assumptions.
For sensitive deployments, treat the library file as you would treat any PII-bearing log — encrypt the disk, control access, and consider purging after the operational need ends.