# AirWitness — detailed field guide Start with the [AirWitness overview](README.md) for a tour and current availability. This guide keeps the detailed Windows workflows and collection limits close at hand. The macOS preview shares the workspace and analysis tools, with the platform differences below. A source feature is not a promise that an older installed beta already contains it. ## macOS preview: setup and differences The active Mac target is Apple Silicon (M1 and later), not Intel. Native testing has used an M1 MacBook Air; that is the test machine, not a restriction to that model. The build targets macOS 14 or later, but the full OS/hardware range has not been independently accepted. macOS is in private testing, with no public Mac package promised by this guide. Linux and Android remain deferred. - **Wi-Fi identity:** allow AirWitness in System Settings → Privacy & Security → Location Services. macOS otherwise withholds network names and BSSIDs. Local Network permission may also be needed for probes and local services. Missing permission is reported rather than filled with guessed measurements. - **Native observations:** CoreWLAN supplies association, nearby-network and signal data, including measured noise/SNR when available. Apple does not expose every Windows metric. Windows event-log connection stories, Windows WLAN reports, MAC override and the spoofed-MAC DHCP/renew tools are not Mac features. AirWitness supplies a separate macOS Wi-Fi report. - **Connections:** the Mac control path supports open and personal/password-protected networks. Enterprise 802.1X profile setup is not implemented on Mac; configure those networks through macOS or your administrator. Association/disconnection hardware acceptance is separate from provider/unit tests. - **Capture:** the built-in tcpdump can collect an ordinary managed-interface .pcap without installing Wireshark. Use **Enable packet capture…** for one administrator approval. This adds capture access through the access_bpf group and a startup task at /Library/LaunchDaemons/net.airwitness.capture-access.plist so it survives a restart. **Disable packet capture** removes only AirWitness's additions. The app then captures as your ordinary account; a denied prompt leaves capture unavailable. - **Analysis:** install Wireshark (which includes tshark) for protocol analysis. AirWitness discovers tshark inside Wireshark.app. Capturing a file and analysing it are separate capabilities. This is not over-the-air monitor-mode capture, radio injection or a promise of support for a particular USB Wi-Fi adapter. - **Passphrases:** Windows-protected saved Wi-Fi/handshake passphrases are not portable to Mac. The Mac path does not persist those passphrases or use Keychain for them; enter them again when needed. FOX Relay's Keychain support is a different product feature. - **Servers:** shared Syslog/TFTP behavior has native Mac test coverage. Privileged DHCP, low-port permissions and transfers from physical client devices need their own validation; do not infer hardware acceptance from a passing automated suite. - **Updates and data:** Mac replacement is manual for now; follow the instructions with the invited test build. Data defaults to ~/Library/Application Support/AirWitnessData. A signed Avalonia license must include macOS; one file can include Windows and Mac. Offline loading remains available. The Mac and Windows private betas are intended to move in step. Signing/notarization machinery and a version label are not evidence that a Mac package has been published or accepted. ## Getting started 1. Install the Windows beta using its supplied installer. Import your signed **AirWitness Avalonia** license when prompted. A Legacy WinForms license does not automatically grant Avalonia access. 2. Create or open a project, enter the ticket/site context and technician, and add a session for the work you are doing. 3. Choose a workflow for the complaint, or use Wi-Fi Monitor for wireless observations. 4. Inspect findings alongside the measurements and detailed evidence. Attach relevant captures, logs and notes to the session. 5. Save the project before sharing it. Export reports when the recipient only needs a readable result. Most work does not need administrator rights. Windows report generation, adapter MAC changes and some capture/DHCP operations can require elevation. Packet capture needs a separately installed compatible Wireshark/tshark and capture driver. Monitor mode additionally needs genuine adapter and driver support. ## Projects and notes - Create, open, save and save-as `.awproj` projects containing sessions and their artifacts. - Add, select and rename sessions so separate visits or test conditions retain their own notes and evidence. - Record identity/context and Markdown notes; format text, find/replace, insert links and add file or image attachments. - Annotate supported images and export the resulting image or notes. - Set reusable note defaults and export artifacts for use outside AirWitness. - Import readable Legacy data without replacing the original installation. A project is an **unencrypted ZIP archive**. Notes autosave/workspace recovery does not replace saving the portable project. Captures, reports and attachments may contain sensitive network data; review them before sharing. Protected saved passphrases are tied to the Windows user and are not portable credentials. ## Workflows The workflow picker offers guest outage, slow network, portal login, DNS health, WLAN 802.1X/RADIUS, VPN MTU/MSS and multihomed conflict investigations. Each runs the existing collection recipe and produces findings, raw command/probe evidence and reports. Depending on the recipe and settings, collection includes interface configuration, routes, ARP, DNS, ping/path diagnostics, Windows event evidence, optional capture, HTTP download or iperf testing. Targets identify the investigation context; they do **not** bind every operating-system-routed probe to a selected adapter. Capture and throughput tests generate traffic. Review the chosen workflow, target settings and capture options before running it. Captive-portal testing and existing-profile connect/disconnect actions affect the current Windows connection. ## Wi-Fi Monitor The sampling interval is beside **Start monitoring**, defaults to **2 seconds**, and accepts 1–60 seconds. Stop monitoring before changing it. **More options** is immediately below the Association, Signal and Speed cards. **Nearby networks** shows all observed BSSIDs in sortable columns. Search SSID/BSSID/vendor and filter by band, channel, security or minimum RSSI. These filters affect only the table; they never remove evidence from a snapshot. Blank SSIDs are labeled Hidden SSID; BSSIDs remain distinct. Double-click a row for the quality-factor breakdown. On **Charts**, hover a signal bar for its details. Right-click to pin its card, select text or use **Copy details**, then paste into Scratch Pad. While pinned, other bars do not open cards. Right-click outside the card/pinned bar to release it. Pins follow BSSID updates and label readings from a signal no longer observed. ### Before/After snapshots On the **Snapshots** tab, stop monitoring, enter a name such as Before and location/change notes, then choose **Take snapshot** or **Sample for 30 seconds**. Keep the laptop in the same place, make the AP/WLAN changes separately, then take After. Native scan completion determines actual spacing; OS scan caches can repeat observations. Actual timestamps and all available observations are retained. Choose Before and After to compare aligned channel charts, observed BSSID changes, median/minimum/maximum readings and available sample counts. Measurements include RSSI, SNR, channel utilization, channel width, station count and minimum rate where available. Saved quality scores retain their factor evidence and data coverage. Missing values stay unavailable; fewer WLANs do not automatically mean stronger RSSI or proven airtime improvement. AP grouping uses exact inventory BSSID mappings only; unknown/conflicting AP identities are not guessed from similar MACs. Snapshots save automatically in `snapshots` beneath the configured Wi-Fi capture folder. Export `.awsnapshot` files or a `.awcompare` pair to reopen later; both are versioned compressed JSON containing data rather than screenshot images. Export HTML for an offline customer report with vector charts. Data files and reports contain network identifiers and notes and are not encrypted. Snapshot exports require a new filename; retain earlier captures rather than overwriting them. Snapshots are independent of project attachments; exporting a comparison does not automatically attach it to a project. - Select an adapter and inspect nearby BSSIDs, SSIDs, RSSI, channel, band, security and advertised capabilities. - Enter a target SSID and passphrase to connect to a protected network. Advanced connection options cover enterprise authentication and supported MAC workflows. - Capture a network sample or retain interval-based samples; pause/resume/stop, save/import evidence, compare a baseline and export JSON or tables. - Inspect channel and signal charts, findings, the experience rating and its factor breakdown. - Correlate supported Ruckus logs with captured observations and create offline HTML reports. - Read Windows WLAN reports and authentication stories when their data sources are available. Some current Windows collection/connection paths use the primary wireless adapter. The CLI rejects an adapter mismatch before those operations. Continuous desktop collection retains its legacy DHCP escalation behavior; headless sampling defaults that disruptive release/renew step off unless explicitly enabled. ### Understanding ratings The wireless experience index combines signal (25), SNR (20), airtime (20), PHY (20) and band (15). Available factors are normalized when a measurement is missing. Detailed evidence records measurements, weights and reasoning so an expert can challenge the interpretation. The broader health score combines six diagnostic categories with weights 20/20/20/15/15/10. These scores summarize the available evidence; they are not a throughput guarantee or an application experience certification. Missing, sparse or default-valued collector data can limit a score's meaning. Compare the measurements and collection conditions behind a change such as 72 to 89. ## Packet Capture - Discover compatible tools/interfaces, select a managed capture interface, choose a filter/preset and collect a bounded capture. - Analyze an existing packet file, inspect protocol totals, findings, narrative/timeline and handshake observations. - Remember target SSIDs and MAC patterns; saved passphrases use current-user protected storage where available. - Open a capture in Wireshark from the desktop. Headless mode returns a launch descriptor instead of opening a window. - Search the offline capture/display/tshark reference examples. Examples are reference text, not executed commands. The current standalone live path is a **managed-interface capture**, not a live raw 802.11 monitor provider. Imported raw captures can contain EAPOL and management-frame evidence. Expert monitor catalog targets such as channel hopping, spectral/IQ capture and injection are not implemented merely because they appear in a capability list. For WPA2, a known SSID/passphrase can validate supported handshake MICs. WPA3 SAE recognition does not verify a passphrase or decrypt traffic. Handshake observations aggregate by client across the file; they are not yet grouped into independently correlated replay/attempt sequences. Seeing M1 proves it was observed by the capture device, **not** that the Chromecast received it: the analyzer does not correlate ACKs to establish receipt. Missing M2 can also reflect channel coverage or capture loss. ## Server tools Services start on demand and stop through their own controls. Configure folders in Settings; panels display the configured paths. TFTP/SFTP folders cannot be filesystem roots, and read-only access defaults on. Stop a running service before changing its served folder or access policy. - **TFTP:** octet-mode transfers with sender allow-list and read-only policy; received files and transfer activity remain available after Stop. TFTP has no authentication or encryption. - **Syslog:** UDP and TCP collection, saved disk log, bounded live messages and local vendor/event analysis. Displaying a local address does not itself restrict listener binding. - **iperf3:** server/client testing with duration, port, UDP and reverse options; output records what the external process reported. Starting a process is not proof that it is listening successfully. - **SFTP:** password-authenticated service rooted to one chosen folder, with read-only access and connection events. Its ten-minute idle timeout disconnects idle clients; it does not stop the listener. Connection events are not a complete file-transfer audit log. - **DHCP:** explicitly selected local IPv4 interface, ranges, exclusions, reservations, lease timers, client filters and custom ASCII/hex options. Validate before starting. Test on an isolated segment: clients retain assigned addresses until their leases expire after the service stops. The desktop reminds you after ten minutes and offers Stop or a configurable 5–60-minute reminder. The CLI requires explicit sender consent (`allowList` or `allowAll`) for TFTP/Syslog, and exposes DHCP reminders as status/snooze tasks rather than a modal window. Host shutdown stops its owned services. ## Dashboard, settings and updates The Dashboard brings session findings, health scores and diagnostic narrative together. Settings control folders/access policy, appearance and diagnostic targets. License status and update availability use the Avalonia entitlement, separately from Legacy. Only published authorized builds appear in the update catalog. The beta desktop records crashes locally and sends queued reports to the beta portal when available; no license is required. Help → Crash reports shows their status and offers Send now. Offline reports stay queued. Reports without verified license attribution are labeled anonymous. Headless `crash.list` inspects them; `crash.send` is an explicit submission, never a side effect of listing tasks. Data normally lives under `%LOCALAPPDATA%\AirWitnessData`; the default projects location is under Documents\AirWitness\Projects. Folder settings can change these locations. Keep a copy of your saved project archives when migrating machines. ## Automation and platform limits Use AirWitness CLI for JSON task discovery, one-shot operations, or a persistent headless host. It uses the same collection, analysis, project and service implementations without opening desktop windows. Beta license enforcement remains in place. Tasks that need an unavailable platform provider or a GUI-only installation step report that explicitly. The exhaustive function inventory, platform assessment and automation coverage distinguish working operations, presentation equivalents and unsupported targets. Hardware, driver, permission and physical-device validation still determine what can be collected on each machine. ## Appearance Open Options / Appearance to choose a theme. Preview the colors, then Save to apply them immediately and remember the choice. The current AirWitness Slate remains the default. Light and Follow system remain available, alongside classic AirWitness Blue, Steel Night, Field Slate, High Contrast, Nord, Catppuccin Latte and Catppuccin Mocha. Themes work offline; Nord and Catppuccin license notices ship in Notices/Themes. These are AirWitness adaptations of the upstream palettes. ### Scratch Pad Choose **Report a bug** beside **Scratch Pad** in the main menu to open the beta bug-report form in your default browser. Sign in to your beta account if prompted. Choose **Scratch Pad** in the main menu for quick local notes independent of the current project. It starts with one tab; use **+** to add up to five. Right-click a tab label to rename it. Names and text save automatically after a brief pause and restore next time. **Dock / Float** moves the same notes into a separate window; **Always on top** applies to the floating window. Smaller main windows use floating notes to preserve workspace room. **Hide** keeps your notes. Clearing a tab asks first. Notes are saved locally as plain text in `scratch-pad.json` in the application data folder; they are not automatically included in project evidence or reports. ### AP inventory and connected access point Wi-Fi Monitor's **Connected access point / inventory** section can import a CSV list, match the sampled connected BSSID to its AP name/site/location, and flag conflicting identities. An optional site filter narrows matches. Base/management MAC, radio MAC and BSSID remain separate; no inferred MAC relationships are enabled yet. Use one BSSID per CSV row. Supported columns include `Site,Name,Serial,Model,BaseMac,RadioMac,Bssid,Ssid,Band,Location,Floor`. Common aliases include AP Name, Device Name, MAC Address (management only), AP BSSID and Venue. Export first when editing: preserve `Id` so reimport updates that record. Imports merge rather than deleting omitted rows; export to a new filename. **Export observed BSSIDs** produces an inventory worksheet from the latest sample. Unknown entries have blank base/radio MACs and `Evidence=Observed`; they do not count as identified APs. Fill in a verified identity and explicitly change Evidence to Inventory before importing it as an AP mapping. Source and timestamp remain in the export. A MAC match is an inventory match, not authentication of the access point. Vendor-specific presets and reverse derivation are still pending validation. --- © 2026 Tom Hardy. All rights reserved.