← Back

Getting Started

Last updated: September 30, 2026

TraceWaves runs in your browser at tracewaves.app. It works signed out and offline. Everything you capture is stored on your device first. Signing in adds sync between your devices.

1. Scanning Wi-Fi From the Browser

Browsers can't scan Wi-Fi on their own, so TraceWaves uses a small local scan agent. It's a single Python script with no dependencies. It listens only on 127.0.0.1:7273, is never reachable from the network, and needs no admin rights.

  1. Download it: 
    curl -fsSLO https://tracewaves.app/tracewaves-agent.py
  2. Install it to start automatically when you log in: 
    python3 tracewaves-agent.py --install
    On Windows, use py instead of python3. To run it just once without installing, leave off --install.
  3. Open Discover in the app and choose Check Again. It shows Agent connected when it can reach the agent.

Check the agent with python3 tracewaves-agent.py --status and remove it with python3 tracewaves-agent.py --uninstall.

No agent? Use Import on Discover to paste or upload the output of your operating system's own scan command (netsh wlan show networks mode=bssid on Windows, nmcli -f ALL dev wifi list on Linux), or a CSV or JSON file. Import works in every browser.

2. Bluetooth

Bluetooth discovery uses Web Bluetooth, which is available in Chrome and Edge. Safari and Firefox don't support it, so the app hides Bluetooth controls there and explains why.

3. Reading Risk Grades

Each access point gets a score from 0 to 100 and a grade:

  • A 85–100 · B 70–84 · C 55–69 · D 40–54 · F 0–39

The score weighs encryption, WPS, Protected Management Frames, Wi-Fi generation and known CVEs. Some findings cap the grade no matter how good everything else is:

  • Open or WEP networks are always F.
  • WPA (TKIP-era) networks are at best D.
  • A matched CVE on CISA's Known Exploited Vulnerabilities list caps the grade at D.

CVE data comes from the NIST National Vulnerability Database and is refreshed daily. The CISA KEV list is also refreshed daily. Vendor names come from the IEEE registry of hardware address prefixes, refreshed weekly.

4. Verify

Verify tests the connection you're on right now. A browser can only test the network it's connected to. It runs three checks against TraceWaves itself, with no third-party test sites:

  • App Server: loads a fresh copy of a small file, bypassing caches, to prove the server is reachable.
  • API Health: asks the TraceWaves API whether it's healthy.
  • Round-Trip Time: the median of several requests.

5. The Journal

Journal entries record what you observed, with optional GPS, tags, severity and notes. Each entry stores a SHA-256 hash of its observation. The server recomputes that hash, so later changes to the observation can be detected.

6. Signing In and Sync

Sign in from Settings with Google, Microsoft or GitHub. Once you're signed in, journal entries sync automatically. Sync runs when you sign in, when you come back online, when you return to the tab, every minute, and right after you save. Settings shows sync status, how many changes are waiting to upload, and a Sync Now button.

  • Offline edits are kept and uploaded later. If the same entry changed in two places, an edit that hasn't uploaded yet wins. Otherwise the most recent change wins.
  • Signing out uploads pending changes first, then offers to remove TraceWaves data from the device. Use this on shared computers.
  • Today only journal entries sync. Scan sessions and device lists stay on the device where you captured them.

7. Your Account and Data

  • Delete Account in Settings permanently deletes your account and everything synced to the server.
  • Clear All Local Data in Settings removes what's stored in this browser.
  • See the Privacy Policy for what's stored and where, and the Acceptable Use Policy for authorized use.

8. Platforms

The web app at tracewaves.app is available now. Native apps for macOS, iOS and Windows are in development and not yet in the app stores.

9. Getting Help

Stuck, or found a bug? Contact us and we'll reply by email. Security issues go through the same form with the topic Security; see the Security Policy.