Sparrow-WiFi

Sparrow-WiFi는 Linux용 2.4GHz 및 5GHz WiFi 및 Bluetooth 스펙트럼 인식 도구입니다. WiFi 스캐닝, Bluetooth Low Energy 및 Classic 탐지, 소프트웨어 정의 무선 스펙트럼 분석(HackRF, Ubertooth), GPS 추적, FAA RemoteID 드론 탐지, 드론/로버 탑재 원격 운영, 그리고 ECS 8.17 인덱싱을 Elasticsearch 또는 OpenSearch에 통합하는 단일 플랫폼입니다. 전체가 Python 3로 작성되었습니다.

이 프로젝트는 독립적으로 또는 함께 작동하는 네 가지 구성 요소를 포함합니다:

Sparrow Agent와 Sparrow DroneID는 JSON REST API를 노출하여 다른 애플리케이션이 스캔 결과를 조회하고, 스캔을 트리거하고, 드론 탐지 정보를 가져오고, 무선/드론 인식을 자체 워크플로에 통합할 수 있도록 합니다. Elastic Bridge는 에이전트의 REST API를 사용하고 ECS 8.17 문서를 번들 Kibana 대시보드와 함께 전송합니다.

새로운 기능 (2026년 4월)

이번 릴리스는 이전 버전에 비해 세 가지 중요한 개선 사항을 포함합니다:

• Sparrow Agent: 단일-비행 WiFi 스캔 병합. 여러 HTTP 클라이언트(DroneID 앱, Elasticsearch 브리지, GUI)가 동시에 /wireless/networks/<iface>에 접근할 때, 에이전트는 이전에 중복된 N개의 iw scan 호출을 시작하여 인터페이스별 잠금에서 직렬화되어 스캔 지연 시간이 클라이언트 수만큼 곱해졌습니다. 이제 첫 번째 요청이 실제로 스캔하는 "리더"가 되며, 동시 요청은 threading.Event에서 대기하고 리더의 결과를 공유합니다. 또한 잠금 생성 TOCTOU 수정 및 인터페이스별 잠금에 대한 예외 안전성을 포함합니다.
• Sparrow DroneID — WiFi(ASTM F3411 NAN, 비콘 공급업체 IE, DJI 독점 DroneID 프로토콜) 및 Bluetooth LE(BT4/BT5 Legacy advertising)를 통한 FAA RemoteID 탐지를 위한 새로운 웹 기반 애플리케이션입니다. 지오존 오버레이, Slack 통합을 포함한 다중 상태 알림, KML 내보내기, Cursor-on-Target 출력, Elasticsearch / OpenSearch로의 선택적 ECS 8.17 인덱싱(사용자 정의 droneid.* 네임스페이스 포함) 및 다중 장치 반응형 웹 UI를 포함합니다. 아래 Sparrow DroneID 섹션을 참조하십시오.
• 현대화된 Elasticsearch / OpenSearch 브리지 — sparrow-elastic.py 브리지가 ECS 8.17 문서를 생성하도록 재작성되었으며(이전 ECS 1.5), 이제 Elasticsearch 8.x 및 OpenSearch 2.x를 모두 지원하고, ILM/ISM 수명 주기 정책 및 롤오버 쓰기 별칭이 포함된 컴포저블 인덱스 템플릿을 자동으로 부트스트랩하며, OUI 공급업체 보강 및 규칙 기반 장치 분류(선택적 Fingerbank 핑거프린팅 포함)를 수행하고, 4개의 번들 Kibana 대시보드와 6개의 레거시 보존 시각화를 제공합니다. 레거시 ECS 1.5 브리지는 legacy/sparrow-elastic.py에 보존되어 있습니다. Elasticsearch / OpenSearch 통합을 참조하십시오.

Sparrow-WiFi (데스크톱 GUI)

원래 Sparrow 애플리케이션은 inSSIDer 및 LinSSID와 같은 도구를 대체하는 포괄적인 GUI 기반 솔루션을 제공하며, 기본 스캐닝을 훨씬 넘어서는 기능을 갖추고 있습니다:

• WiFi 스캐닝 — 2.4GHz 및 5GHz SSID 탐지, 신호 강도, 채널 사용률
• 소스 추적 — 높은 샘플링 속도와 텔레메트리 윈도우를 사용하여 WiFi 및 Bluetooth 소스를 찾는 헌트 모드
• 스펙트럼 분석 — Ubertooth One 또는 HackRF One을 통한 실시간 2.4/5GHz 스펙트럼 오버레이
• Bluetooth — BLE 광고 스캐닝, iBeacon 탐지/광고, 클래식 + LE를 위한 Ubertooth 무차별 모드
• 원격 에이전트 — 분산 스캐닝, 드론/로버 탑재 운영 및 Raspberry Pi 배포를 위한 헤드리스 에이전트(sparrowwifiagent.py)
• GPS 통합 — gpsd, 정적 좌표 또는 MAVLink (드론 GPS)
• 매핑 — GPS 트랙이 포함된 스캔 결과의 Google Maps / OpenStreetMap 시각화
• 가져오기/내보내기 — CSV, JSON 및 원시 iw scan 출력
• Elasticsearch / OpenSearch — ILM/ISM 수명 주기 관리, 장치 분류, 선택적 Fingerbank 핑거프린팅 및 번들 Kibana 대시보드가 포함된 WiFi 및 Bluetooth 스캔 데이터의 ECS 8.17 호환 인덱싱
• Falcon 플러그인 — 침투 테스트를 위한 Aircrack-ng 통합 (모니터 모드, 숨겨진 SSID 탐지, deauth, WEP/WPA 캡처)

스크린샷

Sparrow DroneID (웹 애플리케이션)

FAA 의무 원격 식별(RemoteID) 브로드캐스트를 디코딩하는 독립형 웹 기반 드론 탐지 및 추적 시스템입니다. Python HTTP 서버로 실행되며 네트워크상의 모든 장치에서 접근 가능한 브라우저 기반 UI를 제공합니다.

기능

• WiFi 캡처 — ASTM F3411 NAN 액션 프레임, 비콘 공급업체 IE 및 DJI 독점 DroneID 디코딩
• Bluetooth LE 캡처 — ASTM F3411 BT4/BT5 Legacy 광고 디코딩(UUID 0xFFFA)
• 실시간 지도 — 쿼드콥터 아이콘, 방향 표시기, 운용자 위치 마커 및 드론-운용자 라인이 있는 Leaflet 기반 지도
• 한눈에 보는 라벨 — 지도상의 각 드론 아이콘 아래에 운용자 ID 및 지상 고도(AGL) 표시
• 세부 팝업 — 드론 클릭 시 일련번호, 등록 ID, 운용자 ID, 유형, 속도, 방향, 고도, 수신자로부터의 방위/거리, BVLOS 상태 확인
• 알림 시스템 — 새로운 드론, 고도 위반, 속도 위반 및 신호 손실에 대한 구성 가능한 알림, 오디오 톤, 시각 토스트, Slack 웹훅 알림 및 일반 외부 알림 수집 API로의 선택적 bearer-token JSON POST 포함 (아래 API 기반 알림 참조)
• 알림 확인 — 세 가지 상태 워크플로(활성/확인됨/해결됨)와 운용자 ID, 모든 연결된 장치에서 공유
• 공항 지오존 — 주변 공항(OurAirports 데이터) 및 FAA 금지/제한 공역 다각형 자동 다운로드 및 표시, 오프라인 작동을 위해 로컬에 캐시됨
• GPS — gpsd 통합 또는 구성 가능한 정적 좌표
• 기록 및 재생 — SQLite 기반 탐지 기록, 타임라인 재생 및 KML 내보내기
• Cursor-on-Target (CoT) — SA 통합을 위한 멀티캐스트 CoT 출력
• 다중 장치 — 웹 UI가 데스크톱, 태블릿 및 휴대폰에서 동시에 작동
• 미터법 / 야드파운드법 — UI 및 알림 전반에 걸친 전체 단위 선호도 지원

웹 UI는 시작되면 http://localhost:8097에서 실행됩니다. 설정은 아래 설치를 참조하고, 프로그래밍 방식 액세스는 API 참조를 참조하십시오.

API 기반 알림

Slack 웹훅 외에도 Sparrow DroneID는 각 트리거된 알림을 일반 외부 알림 수집 엔드포인트에 POST할 수 있습니다. 이 채널은 기본적으로 비활성화되어 있습니다. 설정 → 알림 → API 기반 알림에서 구성하십시오:

• 활성화 — 켜기/끄기 토글
• API 엔드포인트 루트 — 경로 접두사를 포함한 전체 루트 URL, 예: http://MY_API_HOST:PORT/API_ROOT
• 도메인 — 수신 API가 알림을 라우팅하는 데 사용하는 불투명 테넌트 문자열
• Bearer 토큰 — Authorization: Bearer ... 헤더로 전송됨, 저장되면 UI에서 마스킹됨
• TLS 확인 — 자체 서명 또는 사설 CA 엔드포인트의 경우 체크 해제
• 인증 테스트 — 수신자의 확인 엔드포인트를 호출하고 명확한 통과/실패를 보고
• 테스트 메시지 보내기 — 합성 알림(rule.category: "test", 일련번호 TEST-0000)을 POST하여 실제 드론을 기다리지 않고 수신자를 종단간 테스트할 수 있음

엔드포인트 계약

Sparrow DroneID는 구성된 루트 URL에 대해 두 가지 호출을 수행합니다:

두 호출 모두 Authorization: Bearer <token> 및 Content-Type: application/json 헤더를 전송합니다.

페이로드 형태```json

{ "domain": "", "alert": { "message": "", "observer": { "name": "<operator_name or 'Sparrow DroneID'>", "type": "drone-sensor", "geo": {"location": {"lat": 0.0, "lon": 0.0}} }, "rule": {"name": "", "category": "drone_detection"}, "event": { "severity": 40, "category": "network", "action": "new_drone" }, "labels": { "serial": "", "vendor": "", "ua_type": "", "alert_type": "new_drone | altitude_max | speed_max | signal_lost" }, "source": {"geo": {"location": {"lat": 0.0, "lon": 0.0}}}, "details": { "operator_id": "...", "registration_id": "...", "self_id_text": "...", "mac_address": "...", "protocol": "...", "rssi": -68, "range_m": 1234.5, "bearing_deg": 215.0, "bearing_cardinal": "SW", "speed_mps": 5.2, "direction_deg": 240.0, "altitude_m_agl": 42.0, "detail": "..." } } }

`observer.geo.location`는 수신기에 GPS 고정이 있을 때 포함되며, `source.geo.location`는 드론이 위치를 브로드캐스트할 때 포함됩니다. 심각도는 ECS 규칙을 따릅니다(낮을수록 더 긴급함): 경고(`new_drone`, `altitude_max`, `speed_max`)는 `40`, 정보성 이벤트(`signal_lost`)는 `70`입니다. 친구 태그가 지정된 드론은 운영자 측의 "친구 드론에 대한 알림" 토글이 꺼져 있을 때 알림을 발생시키지 않으므로 이 엔드포인트에도 도달하지 않습니다.

**테스트 메시지 보내기** 버튼으로 전송되는 합성 테스트 경보는 `rule.category: "test"`, `event.action: "test"`, `event.severity: 70`, 직렬 `TEST-0000`을 사용하여 수신기가 이를 인식하고 운영 대시보드에서 제외할 수 있도록 합니다.

---

## 시스템 요구 사항

| 요구 사항 | Sparrow-WiFi (GUI) | Sparrow DroneID (웹) |
|-------------|-------------------|----------------------|
| **OS** | Ubuntu 20.04+, Kali 2020.3+, Debian 11+ | Ubuntu 20.04+, Kali, Debian 11+, Raspberry Pi OS |
| **Python** | 3.8+ | 3.8+ |
| **Root** | 필요 (iw 스캔) | 필요 (모니터 모드, BLE) |
| **WiFi 어댑터** | `iw` 지원 어댑터 | 모니터 모드 지원(예: rtl8812au, Intel AX200) |
| **블루투스** | 선택 사항 (hci 어댑터, Ubertooth) | 선택 사항 (RemoteID용 BLE 지원 어댑터) |
| **GPS** | 선택 사항 (gpsd) | 선택 사항 (gpsd 또는 고정 좌표) |
| **디스플레이** | X11/Wayland 데스크탑 | 헤드리스 가능 (모든 기기에서 웹 브라우저) |

---

## 설치

### Sparrow-WiFi (데스크탑 GUI)```bash
git clone https://github.com/ghostop14/sparrow-wifi
cd sparrow-wifi

시스템 패키지 (Ubuntu 22.04+ / Debian 12+ / Kali rolling):```bash sudo apt install python3-pip python3-pyqt5 python3-pyqt5.qtchart
gpsd gpsd-clients python3-tk python3-setuptools

> **Kali 사용자:** PyQt5, PyQtChart, aircrack-ng(Falcon 플러그인 용)는 일반적으로 사전 설치되어 있습니다. 대부분 `gpsd`, `gpsd-clients` 및 아래 Python 의존성만 필요합니다.

Python 의존성 — 다음 중 하나를 선택하세요:

**옵션 A: `--break-system-packages`를 사용한 시스템 전체 설치** — 가장 간단하며, GUI/에이전트가 (루트 소유 스크립트로) 실행되는 방식에 적합합니다:```bash
# Modern systems (Ubuntu 24.04+, Kali rolling 2023+, Debian 12+) require this
# flag because Python is marked externally-managed (PEP 668). Sparrow runs as
# root anyway, so system-wide install is consistent with how it executes.
sudo pip3 install --break-system-packages -r requirements.txt

옵션 B: 가상 환경 — 격리되어 있고, 시스템 pip 경고가 없으며, 일부 운영자가 선호합니다:```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

Run with sudo using the venv interpreter:

sudo venv/bin/python3 ./sparrow-wifi.py

어느 쪽이든 run:```bash
sudo ./sparrow-wifi.py

Sparrow DroneID (웹 애플리케이션)```bash

cd sparrow-droneid

System tools — tcpdump for WiFi monitor mode, bluez for BLE RemoteID

sudo apt install tcpdump bluez

Python dependencies — pick one of:

sudo pip3 install --break-system-packages -r sparrow_droneid/requirements.txt

or:

python3 -m venv venv && source venv/bin/activate && pip install -r sparrow_droneid/requirements.txt

Run (either entry point works):

sudo python3 sparrow_droneid/app.py

or: sudo python3 -m sparrow_droneid

브라우저에서 `http://localhost:8097`을 여세요. 설정에서 모니터 인터페이스와 GPS를 구성한 다음, 시작을 클릭하세요.

### Elasticsearch / OpenSearch Bridge (선택 사항)```bash
sudo pip3 install --break-system-packages -r requirements-elastic.txt
# or via venv as above

아래 Elasticsearch / OpenSearch 통합을 참조하세요.

WiFi 어댑터 참고 사항

대부분의 WiFi 어댑터는 기본 스캔에 작동합니다. Sparrow-WiFi는 여러 인터페이스 열거 백엔드(iw, iwconfig, nmcli)를 지원하므로 iw가 설치되지 않은 시스템(예: NetworkManager만 있는 RHEL/Fedora)에서도 작동합니다.

모니터 모드(Sparrow DroneID 및 Falcon 플러그인 필요)의 경우 어댑터 및 드라이버 지원이 다양합니다.

• 추천: Alfa AWUS036ACH (rtl8812au), Alfa AWUS036AXML (mt7921au)
• 잘 작동: Intel AX200/AX210 (iwlwifi) 스캔용; 모니터 모드 프레임 전달은 펌웨어 버전에 따라 다름
• 먼저 테스트: iw phy <phy> info | grep monitor 또는 iwconfig <iface>로 기능 확인

Sparrow DroneID의 경우 어댑터가 모니터 모드에서 원시 802.11 프레임을 전달해야 합니다. 일부 Intel 어댑터는 모니터 모드를 지원한다고 보고하지만 펌웨어 수준에서 프레임을 자동으로 삭제합니다. 애플리케이션이 이를 감지하고 경고합니다.

Bluetooth

Sparrow-WiFi는 여러 Bluetooth 스캔 모드를 지원합니다:

표준 내장 또는 USB Bluetooth 어댑터는 BLE 광고 스캔 및 RemoteID 드론 감지에 충분합니다. bluetoothctl scan on으로 어댑터를 테스트하십시오.

Classic 및 BLE 장치를 모두 완전히 프로미스큐어스하게 검색하려면 /opt/bluetooth/blue_hydra에 설치된 Ubertooth One 및 Blue Hydra가 필요합니다. 이는 선택 사항이며 기본 BLE 또는 RemoteID 스캔에는 필요하지 않습니다.

스펙트럼 분석

WiFi 채널 보기 위의 실시간 스펙트럼 오버레이:

Ubertooth One

• 2.4 GHz 전용, 1 MHz 해상도
• 테스트: ubertooth-specan-ui

HackRF One

• 2.4 GHz (0.5 MHz 해상도) 및 5 GHz (2 MHz 해상도)
• 한 번에 하나의 대역; Ubertooth와 결합하여 동시 이중 대역 사용
• 적절한 이중 대역 안테나를 사용하십시오(표준 HackRF 안테나는 1 GHz까지만 정격)
• 참고: 대부분의 WiFi 안테나는 RP-SMA에서 SMA 어댑터 필요
• 테스트: hackrf_sweep

GPS

두 애플리케이션 모두 gpsd를 사용합니다. 빠른 설정:```bash

Install

sudo apt install gpsd gpsd-clients

Test with a USB GPS receiver

sudo gpsd -D 2 -N /dev/ttyUSB0

Verify

xgps # or: cgps -s

프로덕션 환경에서는 `/etc/default/gpsd`를 기기 경로로 구성하고 서비스를 재시작하십시오.

Sparrow DroneID는 또한 GPS 수신기 없이 고정 사이트 설치를 위해 (설정에서 구성 가능한) 고정 좌표를 지원합니다.

---

## 원격 에이전트 및 API 통합

Sparrow 에이전트 (`sparrowwifiagent.py`)는 헤드리스 HTTP 서버로, Sparrow의 WiFi 및 블루투스 스캐닝 기능 전체를 JSON 기반 REST API로 노출합니다. 이것이 Sparrow-WiFi GUI가 원격 센서와 통신하는 방식이지만, API는 모든 애플리케이션이 사용할 수 있도록 공개되어 있습니다.

**사용 사례:**
- Raspberry Pi, 드론 또는 로버에 배포하여 원격/모바일 스캐닝 수행
- WiFi 및 블루투스 상황 인식을 자체 애플리케이션에 통합
- 스캔 데이터를 SIEM, 대시보드 또는 알림 파이프라인에 공급
- 스크립트로 스캐닝 자동화 (curl/Python 등을 사용하여 스캔 트리거, 결과 가져오기)

Sparrow DroneID는 자체 REST API도 있습니다 ([API 참조](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md)), 드론 탐지, 알림 관리, 지오존 및 시스템 구성에 대한 프로그래매틱 액세스를 제공합니다.

### 에이전트 실행```bash
sudo ./sparrowwifiagent.py

기본적으로 8020 포트에서 수신합니다. 주요 옵션:

전체 목록은 --help를 참조하세요.

예제 API 호출```bash

List wireless interfaces the agent can scan

curl http://sensor:8020/wireless/interfaces

Trigger a WiFi scan and pull results (multiple concurrent callers

get coalesced into a single iw scan; first caller is the leader)

curl http://sensor:8020/wireless/networks/wlan0

Filter to specific frequencies

curl "http://sensor:8020/wireless/networks/wlan0?frequencies=2412,2437,2462"

Query GPS status

curl http://sensor:8020/gps/status

Start a Bluetooth Low Energy advertisement scan

curl http://sensor:8020/bluetooth/discoverystarta

Pull current BT discovery results

curl http://sensor:8020/bluetooth/discoverystatus

Sparrow DroneID에 대한 자세한 내용은 전용 [API 참조](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md)를 확인하세요.

> **프로덕션 참고:** 에이전트는 기본적으로 모든 인터페이스에서 수신 대기합니다. 신뢰할 수 있는 네트워크 외부에 배포하는 경우, `--allowedips`를 사용하여 호출자를 제한하거나, TLS와 함께 리버스 프록시 뒤에서 실행하거나, 개인 인터페이스에만 바인딩하세요.

---

## Falcon / Aircrack-ng 플러그인

고급 무선 침투 테스트 통합. 다음 기능을 클릭 한 번으로 사용할 수 있습니다:

- airodump-ng를 통한 숨겨진 SSID 검색
- 클라이언트 스테이션 열거 (연결된 AP, 프로브된 SSID)
- 대상 및 브로드캐스트 비인증
- WEP IV 캡처
- 자동 해시 추출이 포함된 WPA 핸드셰이크 캡처 (JTR `wpapcap2john` 필요)

### 사전 요구 사항```bash
# Kali users: aircrack-ng + JTR are usually pre-installed.
# Ubuntu / Debian / Raspberry Pi OS:
sudo apt install aircrack-ng john

airmon-ng, airodump-ng, wpapcap2john이 설치 후 PATH에 있는지 확인하십시오.

면책 조항

능동적 침투 테스트는 법적 규제의 대상입니다. 이러한 도구를 사용하기 전에 적절한 승인을 받는 것은 사용자의 책임입니다.

Elasticsearch / OpenSearch 통합

sparrow_elastic 패키지는 Sparrow WiFi 에이전트를 폴링하고 WiFi 및 Bluetooth 관찰을 Elasticsearch 8.x 또는 OpenSearch 2.x에 대량 인덱싱하는 ECS 8.17 브리지를 제공합니다. 이 패키지는 구성 가능한 인덱스 템플릿, ILM/ISM 수명 주기 정책 및 롤오버 쓰기 별칭을 자동으로 부트스트랩합니다. 또한 OUI 공급업체 보강 및 규칙 기반 장치 분류(선택적 Fingerbank 핑거프린팅 포함)를 수행하고 사전 구축된 Kibana 대시보드를 제공합니다.

빠른 시작```bash

1. Start the remote agent (it provides scan data via HTTP)

sudo ./sparrowwifiagent.py

2. Install bridge dependencies

sudo pip3 install --break-system-packages -r requirements-elastic.txt

3. Run the bridge

./sparrow-elastic.py --elasticserver http://user:pass@host:9200 --wifiinterface wlan1

4. (Optional) Import the bundled Kibana dashboards

python3 install_dashboards.py --kibana-url http://kibana:5601
--username elastic --password ''

> **자격 증명 위생:** `--elasticserver`에 `user:pass@`를 포함하는 것은 편리하지만 URL이 `ps`, `journalctl` 및 셸 히스토리에 노출됩니다. 프로덕션에서는 `--username`/`--password` 플래그, 환경 변수(`SPARROW_ES_USERNAME`, `SPARROW_ES_PASSWORD`) 또는 포함된 systemd 유닛 예제의 `EnvironmentFile=` 패턴을 사용하세요.

### 브리지가 제공하는 것

- **5개의 Kibana 대시보드** — 상황 인식(Situational Awareness), 생활 패턴(Pattern of Life), 새 장치 탐지(New Device Detection), 스펙트럼 계획(Spectrum Planning, SSID × 채널 신호 강도 히트맵 포함), 블루투스 상황 인식(Bluetooth Situational Awareness, 진정한 새 장치 Vega 패널 및 예상 거리 근접 테이블 포함)
- **6개의 레거시 보존 시각화** — 원본 `Sparrow*` 시각화의 필드 이름 변경 복제본으로, 기존 작업 방식이 계속 작동하도록 함
- **장치 분류기** — 드론 컨트롤러(DJI/Autel/Skydio/Parrot/Yuneec), BT 장치 클래스, GAP 외형, Apple Continuity 하위 유형, OUI 벤더 휴리스틱을 포함하는 64개 규칙 시드 테이블
- **참조 데이터 갱신** — 번들된 Wireshark `manuf`, BT SIG 회사 ID, 서비스 UUID, GAP 외형 값, Apple Continuity 하위 유형 테이블, 30/90일 자체 갱신 백그라운드 스레드 포함
- **사전 호환성 검사** — 레거시 ECS 1.5 인덱스에 쓰기를 거부하고, 데이터를 조용히 손상시키는 대신 명확한 수정 단계를 출력

전체 운영자 문서(엔진 선택, 인증 모드, 대시보드 가져오기, 참조 데이터, 전체 CLI 참조)는 [sparrow_elastic/README.md](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow_elastic/README.md)를 참조하세요.

샘플 구성 파일은 리포지토리 루트와 `init.d_scripts/`에 있습니다:

- `sparrow-elastic.conf.example` — 모든 지원 키가 포함된 INI 스타일 구성
- `sparrow-elastic.env.example` — systemd 배포용 셸 형식 환경 파일
- `init.d_scripts/sparrow-elastic.service.example` — systemd 유닛 템플릿

### 레거시 ECS 1.5 브리지에서 마이그레이션

2026년 이전 브리지는 `--wifiindex` / `--btindex`를 통해 운영자 이름의 인덱스에 ECS 1.5 문서를 작성했습니다. 새 브리지는 롤오버 관리 쓰기 별칭(기본값 `sparrow-wifi` / `sparrow-bt`)에 ECS 8.17 문서를 작성합니다.

**레거시 스크립트는 `legacy/sparrow-elastic.py`에 보존되어** 있으며, 해당 `.txt` 템플릿 및 ILM 정책 파일도 함께 보존됩니다. 실행하려면 여전히 레거시 환경(수동 템플릿 + ILM 설정)이 필요합니다.

**플래그 변경 사항 (하위 호환성 있음):**

| 레거시 플래그         | 새 플래그           | 참고 사항                                                  |
|---------------------|--------------------|--------------------------------------------------------|
| `--wifiindex NAME`  | `--wifi-alias NAME`| 레거시 철자가 더 이상 사용되지 않는 별칭으로 여전히 허용됨.  |
| `--btindex NAME`    | `--bt-alias NAME`  | 레거시 철자가 더 이상 사용되지 않는 별칭으로 여전히 허용됨.  |
| `--dont-create-indices` | 변경 없음       | 부트스트랩을 건너뜁니다.                                       |
| `--elasticserver`, `--sparrowagent`, `--sparrowport`, `--wifiinterface`, `--scandelay` | 변경 없음 | |

레거시 호출 예시:```bash
./sparrow-elastic.py --elasticserver=http://user:pass@host:9200 \
                     --wifiinterface=wlan1 \
                     --wifiindex=sparrowwifi-home \
                     --btindex=sparrowbt-home

여전히 구문 분석 및 실행이 가능하지만 — 브리지는 이제 ECS 8.17 스키마 마커를 포함하지 않는 매핑을 가진 기존 인덱스에 쓰기를 거부하며, 세 가지 해결 옵션(다른 별칭 사용, 초기화 후 재부트스트랩, 또는 레거시 브리지 실행)과 함께 종료됩니다. 새로 설치하는 경우 --wifiindex / --btindex를 제거하고 새로운 기본값을 사용하면 됩니다.

드론/로버 운용

원격 에이전트는 드론이나 로버에 장착된 라즈베리 파이에 배포하여 모바일 무선 조사에 사용할 수 있습니다. MAVLink를 통한 GPS 통합 기능이 있는 Solo 3DR 드론에서 테스트되었습니다.

자동 녹화```bash

On the Pi: auto-start, pull drone GPS, record to local files

sudo python3 ./sparrowwifiagent.py --userpileds --sendannounce --mavlinkgps 3dr --recordinterface wlan0

LED 표시등 (Raspberry Pi):
1. 둘 다 꺼짐 — 초기화 중
2. 빨간색 깜빡임 — GPS 감지, 동기화되지 않음
3. 빨간색 계속 켜짐 — GPS 동기화됨
4. 초록색 계속 켜짐 — 에이전트 준비, 요청 처리 중

녹화 기록은 Sparrow-WiFi GUI의 에이전트 관리 인터페이스를 통해 검색할 수 있습니다.

### Pi 설정 참고사항

- Raspberry Pi OS (Bookworm 이상)와 Python 3.8+ 사용
- 내장 WiFi를 비활성화하여 USB 어댑터로 5 GHz 스캔을 활성화: Bookworm 이상에서는 `/boot/firmware/config.txt`에 `dtoverlay=disable-wifi` 추가, 이전 버전에서는 `/boot/config.txt`에 추가
- 필수 구성 요소 설치: `sudo pip3 install --break-system-packages -r requirements.txt` (또는 [설치](#installation) 섹션의 venv 사용)

---

## 프로젝트 구조```
sparrow-wifi/
  sparrow-wifi.py            # Desktop GUI entry point
  sparrowwifiagent.py        # Headless remote agent
  sparrow-elastic.py         # Elasticsearch / OpenSearch bridge (ECS 8.17)
  install_dashboards.py      # One-shot Kibana dashboard installer
  requirements.txt           # Python dependencies (GUI)
  requirements-elastic.txt   # Python dependencies (Elasticsearch bridge)
  wirelessengine.py          # WiFi scan engine (iw)
  sparrowbluetooth.py        # Bluetooth scan engine
  sparrowhackrf.py           # HackRF spectrum engine
  sparrowmap.py              # Map generation
  plugins/                   # Falcon and other plugins
  sparrow_elastic/           # ES/OS bridge package
    *.py                     # Client abstraction, document builder, classifier...
    templates/               # Composable index templates (ES + OS variants)
    policies/                # ILM (ES) and ISM (OS) lifecycle policy JSON
    dashboards/              # Kibana NDJSON: 5 dashboards + legacy-preserved
    data/                    # Bundled reference data (manuf, BT SIG, classifier rules)
    README.md                # Full bridge operator documentation
  legacy/                    # Pre-2026 ECS 1.5 bridge, frozen for reference
    sparrow-elastic.py       # Legacy bridge (still runnable)
    sparrow_elastic_*.txt    # Legacy index templates and ILM policy
  sparrow-droneid/           # DroneID web application
    sparrow_droneid/
      app.py                 # Entry point (sudo python3 app.py)
      __main__.py            # Allows: sudo python3 -m sparrow_droneid
      requirements.txt       # Python dependencies (DroneID)
      backend/               # API server, capture engine, database
      frontend/              # HTML, JS, CSS (served by backend)
    sparrow_drone_id_api.md  # REST API reference

라이선스

이 프로젝트는 저장소에 포함된 이용 약관에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.