TL;DR

  • WaveDigger는 BSSID와 LTE·5G NR 네트워크 매개변수로 Wi-Fi 액세스 포인트와 기지국의 대략적인 위치를 찾는 웹 앱임.
  • Next.js, TypeScript, deck.gl 기반의 대화형 지도에서 검색 결과를 시각화함.
  • BSSID 형식 자동 정리·검증, 셀 타워 검색, 검색 기록, 반응형 디자인을 제공함.
  • Apple의 실제 WLOC API를 사용하며, apple-corelocation-experiments 팀의 조사와 프로토콜 버퍼 정의를 토대로 구현함.
  • Node.js 24+와 npm이 필요하며, 라이선스는 GNU Affero General Public License v3.0(AGPL-3.0)임.

WaveDigger

  • 무선 신호를 분석해 실제 위치를 찾는 도구임.
  • BSSID(MAC 주소)로 Wi-Fi 액세스 포인트를 찾고, 네트워크 매개변수로 LTE 및 5G NR 기지국을 찾음.
  • 대화형 지도 시각화에 Next.js, TypeScript, deck.gl을 사용함.
  • 호스팅 버전: https://wavedigger.networksurvey.app

기능

  • BSSID 검색: BSSID를 입력해 대략적인 위치 검색
  • 입력 검증: BSSID 입력의 자동 정리 및 검증
  • 지원 형식: AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF, AABBCCDDEEFF
  • 기지국 검색: LTE 기지국의 MCC, MNC, TAC, Cell ID 또는 5G NR 기지국의 MCC, MNC, TAC, NCI 검색
  • NR 검색은 대상 셀과 같은 클러스터에 있는 주변 NR 셀을 함께 반환함.
  • 대화형 지도: deck.gl 기반 지도에서 검색 결과 시각화
  • 검색 기록: 최근 검색을 기록해 빠르게 다시 접근
  • 반응형 디자인: 데스크톱 및 모바일 기기에서 작동

감사의 말

  • 이 프로젝트는 apple-corelocation-experiments 팀의 작업 없이는 실현될 수 없음.
  • WaveDigger는 Apple 위치 서비스 API에 관한 해당 팀의 조사와 리버스 엔지니어링을 기반으로 구축됨.
  • 구체적으로 다음 자료와 연구를 사용함.
  • Apple WLOC API의 프로토콜 버퍼 정의
  • API 엔드포인트와 요청·응답 형식 문서
  • 좌표 인코딩과 API 동작에 관한 이해
  • 유효한 요청에 필요한 초기 바이트 접두부
  • 문서화되지 않은 Apple 위치 서비스의 동작을 이해하고 기록한 해당 팀의 작업 덕분에 WaveDigger와 같은 프로젝트가 가능함.
  • Apple 위치 서비스를 다루는 원본 연구와 추가 도구를 확인할 수 있도록 해당 팀의 저장소를 살펴볼 것을 권장함.

시작하기

사전 요구 사항

  • Node.js 24 이상 및 npm

설치

  • 의존성 설치: npm install
  • 지도 타일을 개선하려면 Mapbox 토큰을 선택적으로 추가할 수 있음.
  • Mapbox에서 토큰을 발급받아 .env.local에 NEXT_PUBLIC_MAPBOX_TOKEN=your_token_here로 추가

개발 서버 실행

기술 세부 정보

아키텍처

  • 프런트엔드: Next.js 15 및 TypeScript
  • 지도 시각화: deck.gl 및 react-map-gl
  • 스타일링: Tailwind CSS
  • API: Next.js API 라우트

실제 Apple WLOC API

  • 애플리케이션은 BSSID 위치를 조회하기 위해 Apple의 실제 WLOC API를 사용함.
  • 구현은 apple-corelocation-experiments 프로젝트의 조사와 프로토콜 버퍼 정의를 기반으로 함.
  • API 구현 세부 사항은 다음과 같음.
  • Apple 서버와의 통신에 프로토콜 버퍼 사용
  • 요청 전송 주소: https://gs-loc.apple.com/clls/wloc
  • 좌표 변환 처리: Apple은 소수점 이하 8자리를 사용하는 int64 형식 사용
  • 기본 및 중국 지역 엔드포인트 지원

실제 BSSID로 테스트

  • 실제 Wi-Fi BSSID(MAC 주소)를 라우터나 액세스 포인트에서 확인
  • 지원되는 형식 중 하나로 입력
  • Apple 데이터베이스에 위치 정보가 있으면 앱이 데이터베이스를 조회해 위치를 표시함.
  • 모든 BSSID가 Apple 데이터베이스에 등록된 것은 아니며, 새로 배치된 액세스 포인트나 비공개 액세스 포인트에는 위치 데이터가 없을 수 있음.

기능 로드맵

  • 결과 내보내기: 검색 결과를 JSON/CSV로 다운로드
  • TAC 클러스터 보기: 특정 Cell ID나 NCI 없이 TAC 내 모든 기지국 탐색

라이선스

  • WaveDigger는 GNU Affero General Public License v3.0에 따라 라이선스가 부여됨.
  • 이 소프트웨어의 수정 버전을 네트워크 서비스로 실행하는 경우, AGPL에 따라 해당 서비스 사용자에게 수정된 소스 코드를 제공해야 함.