A privacy-first, zero-cloud network monitoring CLI + Web Dashboard for small offices, homelab and security research.
面向小型办公室、Homelab 与安全研究的隐私优先、零云端依赖的网络监控 CLI 与 Web 仪表盘。
WifiMap is a self-hosted, privacy-first network observability tool that turns any workstation (macOS / Linux / Windows) into a passive sensor for a small office or homelab LAN (~40 devices). It continuously discovers devices through ping sweep + ARP + mDNS + BLE, stores everything in a local SQLite database, and exposes the data through a rich Typer CLI and a local FastAPI Web Dashboard.
No cloud. No telemetry. No external dependencies. Your data never leaves the LAN.
- 🔍 See every device the moment it joins the network — wired, wireless, IoT, BLE beacons, even AirTags.
- 🛡️ Audit your own LAN with built-in nmap port scanning and a default-credential probe (9 vendor families).
- 🕒 Spot anomalies with
(weekday × hour)baselines — get notified when an unexpected device shows up at 3 AM. - 🔒 Automate physical security — auto-lock your Mac when your phone leaves the office, auto-check-in when it returns.
- 🥷 Stay invisible — fully passive mode (ARP + mDNS listen only, no ICMP).
- 🧠 Smart device fingerprinting — IEEE OUI vendor DB + mDNS service hints + hostname keywords + user tag feedback loop (>95% accuracy).
- 📡 BLE-aware — detects AirTag-style trackers, persistent strangers, and supports a GATT Lab for advanced experiments.
WifiMap 是一款自托管、隐私优先的网络可观测性工具，可将任意一台工作站（macOS / Linux / Windows）变成小型办公室或 Homelab 局域网（约 40 台设备规模）的被动感知节点。它通过 ping 扫描 + ARP + mDNS + BLE 持续发现设备，将所有数据存入本地 SQLite，并通过功能丰富的 Typer CLI 和本地 FastAPI Web 仪表盘呈现。
无云端、无遥测、无外部依赖，所有数据永不离开你的 LAN。
- 🔍 看见每一台设备 — 有线、无线、IoT、BLE 信标，甚至 AirTag，加入网络的瞬间即可被识别。
- 🛡️ 审计自己的局域网 — 内置 nmap 端口扫描和 9 大厂商默认凭据探测。
- 🕒 发现异常行为 — 按「星期 × 小时」学习基线，凌晨 3 点出现陌生设备立即告警。
- 🔒 自动化物理安全 — 手机离开办公室自动锁屏 Mac、回到办公室自动签到。
- 🥷 隐身模式 — 完全被动扫描（仅监听 ARP + mDNS，不发送 ICMP）。
- 🧠 智能设备指纹 — IEEE OUI 厂商库 + mDNS 服务提示 + 主机名关键字 + 用户标签反馈闭环，识别准确率 >95%。
- 📡 蓝牙感知 — 检测 AirTag 类追踪器、长期驻留陌生设备，并支持高级 GATT 实验室功能。
| Category · 类别 | Feature · 特性 | Description · 说明 |
|---|---|---|
| 🔭 Discovery 发现 | LAN Scan | Ping sweep + arp -a + mDNS / Zeroconf listener |
| BLE Scan | Bleak-based passive Bluetooth Low Energy scanning | |
| iBeacon Decode | Apple iBeacon / Eddystone payload parsing | |
| 📊 Observability 可观测 | Heartbeat (F1) | Time-series presence curve per device |
| Census (F2) | Device-type breakdown + vendor top-N | |
| New Devices (F3) | Recently-joined device alert feed | |
| Zombies (O) | Always-on, untagged devices needing review | |
| Anomaly Detection | (weekday, hour) baseline learning |
|
| 🛡️ Security 安全 | Port Audit | nmap-driven scan with delta history |
| Default-Credential Probe | HTTP Basic Auth check against 9 vendor families | |
| AirTag-Style Tracker Alert | Persistent unknown-BLE-MAC detection | |
| 👤 Presence 在场感知 | Phone Check-In | Auto sign-in when your phone hits the LAN |
| Auto Screen Lock | Lock the workstation when your phone leaves | |
| 🌐 Interfaces 接口 | Web Dashboard | FastAPI + Jinja2 + HTMX + Plotly (14 pages, 18 APIs) |
| Rich CLI | Typer + Rich, 20+ commands across 6 groups | |
| Interactive Menu | REPL-style menu for non-technical users | |
| 🔔 Notifications 通知 | Webhook | Slack / Feishu / DingTalk on new device / high-severity finding |
| 🥷 Privacy 隐私 | Stealth Mode | Pure-passive (no ICMP), broadcast-listen only |
| Random-MAC Detection | Auto-flags iOS / Android private-address MACs | |
| ⚙️ Operations 运维 | Cross-platform Daemon | macOS launchd / Linux systemd / Windows Task Scheduler |
| One-Click Install | install-mac.sh / install-linux.sh / install-windows.ps1 |
|
| Backup / Restore | tar.gz export of SQLite DB + config | |
| Self-Diagnostic | wifimap doctor runs 9 environment checks |
flowchart TB
subgraph LAN["🏢 Office LAN · 办公室局域网"]
D1[📱 iPhone]
D2[💻 MacBook]
D3[🖨️ Printer]
D4[📹 IP Camera]
D5[📡 IoT / Router]
D6[🏷️ BLE Beacon]
end
subgraph Host["🖥️ Workstation · 工作站 (macOS / Linux / Windows)"]
direction TB
subgraph Agents["⏱️ Background Agents · 后台代理"]
A1[scanner · 60s<br/>ping + ARP + mDNS]
A2[presence · 10s<br/>phone check]
A3[ble-scanner · 5min]
A4[enrich · weekly<br/>reverse DNS]
A5[oui-refresh · monthly]
end
subgraph Storage["💾 Local Storage · 本地存储"]
DB[(SQLite WAL<br/>devices / sightings<br/>audit / ble)]
CFG[config.yaml]
OUI[oui.txt · IEEE]
end
subgraph Interface["🖼️ User Interface · 用户界面"]
CLI[Typer CLI<br/>20+ commands]
WEB[FastAPI Dashboard<br/>:8765]
end
subgraph Logic["🧠 Logic Layer · 业务逻辑层"]
CLASS[Classifier<br/>设备分类]
ANO[Anomaly<br/>异常检测]
AUD[Audit<br/>安全审计]
ALERT[BLE Alert<br/>追踪告警]
end
end
LAN -.->|broadcast| A1
LAN -.->|BLE adv| A3
Agents --> DB
DB --> Logic
Logic --> Interface
CFG --> Agents
OUI --> Logic
Interface -.->|webhook| EXT[🔔 Slack / Feishu / DingTalk]
Agents -.->|lock/notify| Host
graph LR
CLI[cli/] --> DB[db.py]
CLI --> SC[scanner.py]
CLI --> CFG[config.py]
SC --> DB
SC --> OUI[oui.py]
SC --> CLASS[classifier.py]
SC --> PLAT[platform/]
DB --> HB[heartbeat.py]
DB --> CEN[census.py]
DB --> NEW[newdev.py]
DB --> ZOM[zombies.py]
DB --> ANO[anomaly.py]
DB --> AUD[audit/]
DB --> BLE[ble.py]
BLE --> BA[ble_alert.py]
BLE --> BL[ble_lab.py]
HB --> WEB[web/app.py]
CEN --> WEB
NEW --> WEB
AUD --> WEB
BA --> WEB
PLAT --> MAC[_macos.py]
PLAT --> LIN[_linux.py]
PLAT --> WIN[_windows.py]
sequenceDiagram
participant LAN as 🏢 LAN Devices
participant SC as 🛰️ Scanner Agent
participant DB as 💾 SQLite
participant CL as 🧠 Classifier
participant UI as 🖼️ CLI / Web
Note over SC: every 60s · 每 60 秒
SC->>LAN: ping sweep (optional)
SC->>LAN: read ARP cache
LAN-->>SC: mDNS broadcast
SC->>CL: raw observation
CL->>CL: OUI + mDNS + hostname<br/>→ device_type
CL->>DB: upsert devices + sightings
Note over UI: on demand · 按需查询
UI->>DB: aggregate(since)
DB-->>UI: heartbeat / census / new / zombies
UI->>UI: Rich table / Plotly chart
git clone https://github.com/Akxan/WifiMap.git && cd WifiMap
./scripts/install-mac.shgit clone https://github.com/Akxan/WifiMap.git && cd WifiMap
./scripts/install-linux.shgit clone https://github.com/Akxan/WifiMap.git; cd WifiMap
.\scripts\install-windows.ps1💡 Installer handles:
uvtoolchain ·nmap(optional) · background daemon registration · OUI database download · first scan. See INSTALL.md for manual / air-gapped setups.
# Core · 核心
wifimap # Interactive menu · 交互菜单
wifimap setup # First-time wizard · 首次配置向导
wifimap status # Scanner status & DB size · 扫描器状态
wifimap doctor # 9-step self-diagnostic · 9 项自检
wifimap pause / resume # Toggle all background agents
# Observe · 观察
wifimap dashboard # Full overview · 总览
wifimap heartbeat # Time-series presence curve · 心跳曲线
wifimap census # Device-type & vendor breakdown · 硬件普查
wifimap new # Recently-joined devices · 新设备
wifimap zombies # Always-on untagged devices · 僵尸设备
wifimap inspect <ip|mac> # Deep-dive on one device · 深度查看
wifimap find <query> # Search devices · 搜索
# Security · 安全
wifimap audit # Port scan + default-cred probe · 安全审计
wifimap audit-history # Diff against previous audit · 历史对比
wifimap anomaly # Outlier devices vs baseline · 异常检测
# BLE · 蓝牙
wifimap ble-scan # Passive BLE scan · 被动 BLE 扫描
# Web
wifimap web # Launch dashboard → http://127.0.0.1:8765
# Ops · 运维
wifimap export # tar.gz backup · 备份
wifimap import <file> # Restore · 恢复
wifimap webhook-test # Test Slack/Feishu/DingTalk · 测试通知| Layer · 层 | Technology · 技术 |
|---|---|
| Language | Python 3.11+ (PEP 604 syntax, from __future__ import annotations) |
| CLI | Typer + Rich |
| Web | FastAPI + Jinja2 + HTMX + Plotly |
| Storage | SQLite (WAL mode, stdlib sqlite3) |
| Networking | Zeroconf · python-nmap · stdlib subprocess |
| BLE | Bleak (cross-platform BLE) |
| Config | PyYAML + dataclasses |
| Daemon | launchd (macOS) · systemd (Linux) · Task Scheduler (Windows) |
| Packaging | hatchling · uv |
| Testing | pytest · pytest-cov · pytest-mock · httpx |
WifiMap/
├── src/wifimap/
│ ├── cli/ # Typer CLI (6 command groups · 6 大命令分组)
│ ├── web/ # FastAPI app + Jinja templates
│ ├── platform/ # macOS / Linux / Windows adapters
│ ├── audit/ # nmap port scan + credential probe
│ ├── reports/ # Plotly + Rich rendering
│ ├── launchd/ # macOS plist templates
│ ├── db.py # SQLite schema + CRUD facade
│ ├── scanner.py # ping + ARP + mDNS scanner
│ ├── classifier.py # device-type inference
│ ├── heartbeat.py # F1 — presence over time
│ ├── census.py # F2 — hardware census
│ ├── newdev.py # F3 — new device feed
│ ├── zombies.py # O — always-on devices
│ ├── presence.py # M — phone check-in / auto-lock
│ ├── anomaly.py # baseline & outlier detection
│ ├── ble.py # BLE scanner core
│ ├── ble_alert.py # AirTag-style tracker alerts
│ └── ble_lab.py # GATT experiments lab
├── tests/ # 33 test files · pytest
├── scripts/ # cross-platform install / uninstall
├── docs/specs/ # full design doc (620 lines)
├── data/oui.txt # IEEE OUI vendor DB (~6.5 MB)
└── pyproject.toml
# Setup · 安装
uv sync # install all deps including dev
uv run wifimap doctor # verify environment
# Test · 测试
uv run pytest # run full suite (33 files)
uv run pytest --cov=wifimap # with coverage report
# Run · 调试
uv run wifimap scan # manual one-shot scan
uv run wifimap web # launch dashboard- ✅ Phase 0 — Core scanner + SQLite
- ✅ Phase 1 — Heartbeat / Census / New devices
- ✅ Phase 2 — Security audit + anomaly detection
- ✅ Phase 3 — Web dashboard + cross-platform daemon
- ✅ Phase 4 — BLE scanning + AirTag alerts + GATT Lab
- 🚧 Phase 5 — Multi-host federation (planned)
- 🚧 Phase 6 — Plugin / webhook system v2 (planned)
See CHANGELOG.md for detailed release history.
Issues and PRs welcome! Please run uv run pytest and uv run wifimap doctor before submitting.
欢迎提交 Issue 与 PR！提交前请运行 uv run pytest 和 uv run wifimap doctor 验证。
MIT License © 2026 Akxan
lan-scanner · network-monitoring · passive-scan · arp-scanner · mdns-discovery · ble-scanner · airtag-detection · device-fingerprinting · office-network · homelab · self-hosted · privacy-first · fastapi · typer · python · cli · sqlite · network-audit · nmap · macos · linux · windows · zeroconf · iot-discovery · presence-detection
局域网扫描 · 办公网络监控 · 被动扫描 · 蓝牙追踪检测 · 设备指纹识别 · 自托管 · 隐私保护 · 网络审计 · 家庭实验室