wavedigger README

The project's README from github.com/christianrowlands/wavedigger. As one markdown file: README.md.

WaveDigger

Dig into wireless signals to discover their physical locations. WaveDigger helps you find Wi-Fi access points by their BSSID (MAC address) and cell towers (LTE and 5G NR) by their network parameters. Built with Next.js, TypeScript, and deck.gl for interactive map visualization.

A hosted version can be found at https://wavedigger.networksurvey.app.

WaveDigger Screenshot

Features

Acknowledgments

🙏 This project would not be possible without the incredible work done by the apple-corelocation-experiments team.

WaveDigger is built upon their research and reverse engineering of Apple's location services API. Specifically, we use:

Their work in understanding and documenting Apple's undocumented location services has made it possible for projects like WaveDigger to exist. Please check out their repository for the original research and additional tools for working with Apple's location services.

Getting Started

Prerequisites

Installation

  1. Install dependencies:
npm install
  1. (Optional) Add a Mapbox token for enhanced map tiles:
    • Get a token from Mapbox
    • Add it to .env.local:
    NEXT_PUBLIC_MAPBOX_TOKEN=your_token_here
    

Running the Development Server

npm run dev

Open http://localhost:3000 to view the application.

Technical Details

Architecture

Real Apple WLOC API

The application uses Apple's real WLOC API to query BSSID locations. This implementation is based on the research and protobuf definitions from the apple-corelocation-experiments project.

The API implementation:

Testing with Real BSSIDs

To test the app:

  1. Find a real Wi-Fi BSSID (MAC address) from your router or access point
  2. Enter it in any supported format
  3. The app will query Apple's database and show the location if found

Note: Not all BSSIDs are in Apple's database. Newly deployed or private access points may not have location data.

Features Roadmap

License

WaveDigger is licensed under the GNU Affero General Public License v3.0. If you run a modified version of this software as a network service, the AGPL requires you to make your modified source code available to users of that service.

wavedigger (christianrowlands/wavedigger)

Searching Database…

Что это?WaveDigger — веб-инструмент, который определяет физическое местоположение точек доступа Wi-Fi по их BSSID (MAC-адресу), а вышек LTE/5G NR — по сетевым параметрам, используя API сервисов геолокации Apple.
Это отдельное приложение или оно обращается к собственной базе Apple?Это самостоятельно размещаемое веб-приложение на Next.js, которое под капотом запрашивает настоящий WLOC API Apple, используя реверс-инженерные определения protobuf для отправки валидных запросов и декодирования ответов.
Как это запустить?Установите зависимости Node.js через npm, при желании добавьте токен Mapbox в .env.local для более качественных плиток карты, затем запустите dev-сервер Next.js.
Нужны ли заранее Node.js и аккаунт Mapbox?Нужны Node.js 24+ и npm; токен Mapbox необязателен и лишь улучшает отрисовку плиток карты.
Вернёт ли каждый введённый BSSID реальное местоположение?Нет — база Apple покрывает не все точки доступа, поэтому недавно развёрнутые или частные роутеры часто не дают результата.
Есть ли размещённая версия, которую можно использовать без самостоятельного запуска?Да, в README упоминается, что размещённая версия существует, хотя документированный путь с полными шагами настройки — это self-hosting.
Есть ли подвох с лицензией AGPL, если я разверну свою изменённую копию?Да — AGPL-3.0 требует, чтобы при запуске изменённой версии как сетевого сервиса вы публиковали её изменённый исходный код её пользователям.
Какие поиски помимо BSSID он поддерживает?Он также поддерживает поиск вышек LTE по MCC/MNC/TAC/Cell ID и вышек 5G NR по MCC/MNC/TAC/NCI, причём поиск по NR возвращает и соседние соты того же кластера.
Как показываются результаты?Результаты наносятся на интерактивную карту на базе deck.gl, а приложение хранит историю поисков для быстрого возврата к недавним запросам.
На чьих исследованиях это построено?Он построен на работе по реверс-инжинирингу проекта apple-corelocation-experiments, который задокументировал недокументированный WLOC API Apple, форматы protobuf и кодирование координат.
В каких форматах можно вводить BSSID?Поле ввода принимает AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF или AABBCCDDEEFF с автоматическим форматированием и валидацией.
Size
3.6 MB
Stars
271
Updated
CommitOct 07
Age
1y
Commits · 90 Days