WiFiSense

轻量级 WiFi 信号智能分析与环境感知引擎
Lightweight WiFi Signal Intelligent Analysis & Environment Awareness Engine

简体中文 | 繁體中文 | English

简体中文

🎉 项目介绍

WiFiSense 是一款轻量级的 WiFi 信号智能分析与环境感知引擎 CLI 工具，专为开发者、网络工程师和安全研究人员打造。

核心价值：

🔍 一键洞察 -- 通过简单的命令行操作，即可获取 WiFi 环境的全方位分析结果
🧠 智能感知 -- 不仅仅是扫描，更能理解环境变化、推断人员存在、追踪设备动态
🪶 极致轻量 -- 零外部依赖，纯 Python 标准库实现，即装即用

解决的痛点：

现有 WiFi 分析工具要么过于笨重（如 Wireshark），要么依赖大量第三方库
缺乏将 WiFi 信号数据转化为环境感知信息的能力
跨平台兼容性差，不同操作系统需要不同工具
隐私担忧 -- 大多数工具会收集和上传数据

差异化亮点：

🚫 零依赖 -- 无需安装任何第三方包，pip install 即可使用
🔒 隐私优先 -- 所有数据在本地处理，不上传任何信息
🌍 跨平台 -- 完美支持 Linux、macOS、Windows
🛡️ 优雅降级 -- 无系统权限时自动切换为模拟扫描器，确保功能可演示

✨ 核心特性

📡 WiFi 信号扫描采集 -- 跨平台扫描，自动检测网络接口，无权限时自动降级为模拟扫描器
📊 信号强度分析 -- RSSI 统计、信道拥挤度分析、安全性评估、信噪比（SNR）估算
🧬 环境指纹生成 -- 基于 BSSID 集合 + 信号特征哈希，支持环境比对和自定义标注
📍 设备追踪 -- 设备出现/消失检测、信号变化追踪、历史记录管理
👤 存在检测 -- 基于 WiFi 设备变化推断人员存在、活动级别评估、人数估算
🗺️ 信号热力图 -- 终端 ASCII 热力图 + HTML 可视化导出，直观展示信号分布
📈 历史趋势分析 -- 信号变化趋势、异常检测、环境稳定性评分
📝 多格式报告导出 -- 支持 JSON / CSV / HTML / Markdown 四种格式

🚀 快速开始

环境要求

Python 3.8+ （支持 3.8、3.9、3.10、3.11、3.12）
无需安装任何第三方依赖

安装步骤

# 方式一：从 PyPI 安装（推荐）
pip install git+https://github.com/gitstq/WiFiSense.git

# 方式二：从源码安装
git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install .

运行命令

# 扫描 WiFi 网络
wifisense scan

# 分析扫描结果
wifisense analyze -f data.json

# 生成信号热力图
wifisense heatmap -f data.json

# 生成环境指纹
wifisense fingerprint --label "MyOffice"

# 存在检测
wifisense presence -f data.json

# 生成分析报告
wifisense report -f data.json

📖 详细使用指南

`wifisense scan` -- WiFi 信号扫描

扫描周围 WiFi 网络并采集信号数据。

# 基本扫描（自动选择接口，默认 5 秒）
wifisense scan

# 指定接口和持续时间，保存结果
wifisense scan -i wlan0 -d 10 -o scan_data.json

# 禁用模拟降级（无权限时直接报错）
wifisense scan --no-mock

参数	说明	默认值
`-i, --interface`	网络接口名称	`auto`
`-d, --duration`	扫描持续时间（秒）	`5`
`-o, --output`	结果输出文件路径（JSON）	-
`--no-mock`	禁用模拟扫描器降级	`false`

使用场景： 网络环境调研、信号覆盖评估、日常网络监控。

`wifisense analyze` -- 信号强度分析

对扫描结果进行深度分析，包括 RSSI 统计、信道分布、安全性评估等。

# 分析扫描数据
wifisense analyze -f scan_data.json

# 分析并保存结果
wifisense analyze -f scan_data.json -o analysis.json

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`-o, --output`	分析结果输出路径	-

使用场景： 网络优化、信道选择建议、安全审计。

`wifisense fingerprint` -- 环境指纹生成

基于 WiFi 信号特征生成环境唯一指纹，支持环境识别与比对。

# 生成带标签的环境指纹
wifisense fingerprint -f scan_data.json --label "MyOffice"

# 生成指纹并与已知指纹比对
wifisense fingerprint -f scan_data.json --label "Home" --compare

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`--label`	环境标签名称	`""`
`--compare`	与已知指纹进行比对	`false`

使用场景： 室内定位、环境识别、多地点管理。

`wifisense track` -- 设备追踪

追踪 WiFi 设备的出现、消失和信号变化。

# 追踪设备变化
wifisense track -f scan_data.json

# 指定数据存储目录
wifisense track -f scan_data.json -d ./tracker_data

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`-d, --data-dir`	追踪数据存储目录	-

使用场景： 设备监控、网络资产管理、异常设备检测。

`wifisense presence` -- 存在检测

基于 WiFi 设备信号变化推断人员存在状态和活动级别。

# 检测当前环境的人员存在情况
wifisense presence -f scan_data.json

# 指定数据存储目录（用于历史对比）
wifisense presence -f scan_data.json -d ./presence_data

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`-d, --data-dir`	存在检测数据存储目录	-

使用场景： 智能家居联动、办公室占用检测、安防辅助。

`wifisense heatmap` -- 信号热力图

生成 WiFi 信号强度热力图，支持终端 ASCII 和 HTML 两种输出格式。

# 终端 ASCII 热力图
wifisense heatmap -f scan_data.json

# 导出 HTML 热力图
wifisense heatmap -f scan_data.json -o heatmap.html --format html

# 按 SSID 过滤
wifisense heatmap -f scan_data.json --filter-ssid "MyWiFi"

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`-o, --output`	输出文件路径	`heatmap.html`
`--format`	输出格式（`terminal` / `html`）	`terminal`
`--filter-ssid`	按 SSID 过滤（部分匹配）	-
`--filter-bssid`	按 BSSID 过滤（部分匹配）	-

使用场景： 信号覆盖可视化、AP 部署规划、网络优化报告。

`wifisense trends` -- 历史趋势分析

分析 WiFi 信号的历史变化趋势，检测异常波动。

# 添加当前扫描数据并分析趋势
wifisense trends -f scan_data.json

# 指定数据目录并保存结果
wifisense trends -f scan_data.json -d ./trend_data -o trends.json

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	-
`-d, --data-dir`	趋势数据存储目录	-
`-o, --output`	趋势分析结果输出路径	-

使用场景： 长期网络监控、信号稳定性评估、异常事件回溯。

`wifisense report` -- 多格式报告导出

将扫描和分析结果导出为多种格式的报告。

# 导出 JSON 报告
wifisense report -f scan_data.json -o report.json --format json

# 导出 HTML 报告
wifisense report -f scan_data.json -o report.html --format html

# 导出 CSV 报告
wifisense report -f scan_data.json -o report.csv --format csv

# 导出 Markdown 报告（含原始数据）
wifisense report -f scan_data.json -o report.md --format markdown --include-raw

参数	说明	默认值
`-f, --file`	扫描结果 JSON 文件路径	必填
`-o, --output`	报告输出文件路径	`report.json`
`--format`	报告格式（`json` / `csv` / `html` / `markdown`）	`json`
`--include-raw`	在报告中包含原始扫描数据	`false`

使用场景： 报告生成、数据归档、与其他系统集成。

💡 设计思路与迭代规划

设计理念

零依赖哲学 -- 使用纯 Python 标准库实现所有功能，避免依赖地狱，确保在任何 Python 环境中都能稳定运行
隐私至上 -- 所有数据处理完全在本地完成，不发送任何网络请求，不收集任何用户信息
优雅降级 -- 当系统权限不足时，自动切换到模拟扫描器模式，确保工具在任何环境下都能正常演示和学习
模块化架构 -- 每个功能模块独立解耦，便于单独使用、测试和扩展

技术选型原因

决策	原因
纯标准库	消除依赖管理复杂度，提升安装成功率和运行稳定性
CLI 工具形态	开发者友好，易于集成到脚本和 CI/CD 流水线
JSON 数据格式	通用、可读、易于与其他工具和语言交互
MIT 协议	最大化开放性，鼓励社区参与和商业使用

后续迭代计划

v1.1 -- 添加实时监控模式（wifisense monitor）
v1.2 -- 支持 GPS 坐标记录，实现信号地图绘制
v1.3 -- 添加 Web Dashboard 可视化界面
v2.0 -- 引入插件系统，支持自定义分析模块
v2.1 -- 添加机器学习异常检测模型

📦 安装与部署指南

从源码安装（开发模式）

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

系统权限说明

平台	扫描要求	备注
Linux	需要 root 权限或 `CAP_NET_RAW` 能力	可使用 `sudo wifisense scan`
macOS	需要授权定位服务	首次运行会弹出系统授权对话框
Windows	需要管理员权限	右键"以管理员身份运行"终端

提示： 如果没有相应权限，WiFiSense 会自动降级为模拟扫描器，生成模拟数据用于功能演示。

配置文件

WiFiSense 支持通过配置文件自定义行为，配置文件路径：~/.wifisense/config.json

🤝 贡献指南

我们欢迎并感谢所有形式的贡献！无论是提交 Bug、改进文档，还是贡献代码。

贡献步骤

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add some amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

开发环境搭建

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

# 运行测试
python -m pytest tests/

代码规范

遵循 PEP 8 编码规范
所有公共函数必须包含 docstring
提交前确保所有测试通过

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 WiFiSense Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

繁體中文

🎉 專案介紹

WiFiSense 是一款輕量級的 WiFi 訊號智慧分析與環境感知引擎 CLI 工具，專為開發者、網路工程師和安全研究人員打造。

核心價值：

🔍 一鍵洞察 -- 透過簡單的命令列操作，即可取得 WiFi 環境的全方位分析結果
🧠 智慧感知 -- 不僅僅是掃描，更能理解環境變化、推斷人員存在、追蹤設備動態
🪶 極致輕量 -- 零外部依賴，純 Python 標準函式庫實作，即裝即用

解決的痛點：

現有 WiFi 分析工具要麼過於笨重（如 Wireshark），要麼依賴大量第三方函式庫
缺乏將 WiFi 訊號資料轉化為環境感知資訊的能力
跨平台相容性差，不同作業系統需要不同工具
隱私擔憂 -- 大多數工具會收集和上傳資料

差異化亮點：

🚫 零依賴 -- 無需安裝任何第三方套件，pip install 即可使用
🔒 隱私優先 -- 所有資料在本地處理，不上傳任何資訊
🌍 跨平台 -- 完美支援 Linux、macOS、Windows
🛡️ 優雅降級 -- 無系統權限時自動切換為模擬掃描器，確保功能可展示

✨ 核心特性

📡 WiFi 訊號掃描採集 -- 跨平台掃描，自動偵測網路介面，無權限時自動降級為模擬掃描器
📊 訊號強度分析 -- RSSI 統計、頻道擁擠度分析、安全性評估、訊噪比（SNR）估算
🧬 環境指紋生成 -- 基於 BSSID 集合 + 訊號特徵雜湊，支援環境比對和自訂標註
📍 設備追蹤 -- 設備出現/消失偵測、訊號變化追蹤、歷史記錄管理
👤 存在偵測 -- 基於 WiFi 設備變化推斷人員存在、活動級別評估、人數估算
🗺️ 訊號熱力圖 -- 終端 ASCII 熱力圖 + HTML 視覺化匯出，直觀展示訊號分佈
📈 歷史趨勢分析 -- 訊號變化趨勢、異常偵測、環境穩定性評分
📝 多格式報告匯出 -- 支援 JSON / CSV / HTML / Markdown 四種格式

🚀 快速開始

環境要求

Python 3.8+ （支援 3.8、3.9、3.10、3.11、3.12）
無需安裝任何第三方依賴

安裝步驟

# 方式一：從 PyPI 安裝（推薦）
pip install git+https://github.com/gitstq/WiFiSense.git

# 方式二：從原始碼安裝
git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install .

執行命令

# 掃描 WiFi 網路
wifisense scan

# 分析掃描結果
wifisense analyze -f data.json

# 生成訊號熱力圖
wifisense heatmap -f data.json

# 生成環境指紋
wifisense fingerprint --label "MyOffice"

# 存在偵測
wifisense presence -f data.json

# 生成分析報告
wifisense report -f data.json

📖 詳細使用指南

`wifisense scan` -- WiFi 訊號掃描

掃描周圍 WiFi 網路並採集訊號資料。

# 基本掃描（自動選擇介面，預設 5 秒）
wifisense scan

# 指定介面和持續時間，儲存結果
wifisense scan -i wlan0 -d 10 -o scan_data.json

# 停用模擬降級（無權限時直接報錯）
wifisense scan --no-mock

參數	說明	預設值
`-i, --interface`	網路介面名稱	`auto`
`-d, --duration`	掃描持續時間（秒）	`5`
`-o, --output`	結果輸出檔案路徑（JSON）	-
`--no-mock`	停用模擬掃描器降級	`false`

使用場景： 網路環境調研、訊號覆蓋評估、日常網路監控。

`wifisense analyze` -- 訊號強度分析

對掃描結果進行深度分析，包括 RSSI 統計、頻道分佈、安全性評估等。

# 分析掃描資料
wifisense analyze -f scan_data.json

# 分析並儲存結果
wifisense analyze -f scan_data.json -o analysis.json

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`-o, --output`	分析結果輸出路徑	-

使用場景： 網路最佳化、頻道選擇建議、安全稽核。

`wifisense fingerprint` -- 環境指紋生成

基於 WiFi 訊號特徵生成環境唯一指紋，支援環境識別與比對。

# 生成帶標籤的環境指紋
wifisense fingerprint -f scan_data.json --label "MyOffice"

# 生成指紋並與已知指紋比對
wifisense fingerprint -f scan_data.json --label "Home" --compare

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`--label`	環境標籤名稱	`""`
`--compare`	與已知指紋進行比對	`false`

使用場景： 室內定位、環境識別、多地點管理。

`wifisense track` -- 設備追蹤

追蹤 WiFi 設備的出現、消失和訊號變化。

# 追蹤設備變化
wifisense track -f scan_data.json

# 指定資料儲存目錄
wifisense track -f scan_data.json -d ./tracker_data

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`-d, --data-dir`	追蹤資料儲存目錄	-

使用場景： 設備監控、網路資產管理、異常設備偵測。

`wifisense presence` -- 存在偵測

基於 WiFi 設備訊號變化推斷人員存在狀態和活動級別。

# 偵測當前環境的人員存在情況
wifisense presence -f scan_data.json

# 指定資料儲存目錄（用於歷史對比）
wifisense presence -f scan_data.json -d ./presence_data

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`-d, --data-dir`	存在偵測資料儲存目錄	-

使用場景： 智慧家庭聯動、辦公室佔用偵測、安防輔助。

`wifisense heatmap` -- 訊號熱力圖

生成 WiFi 訊號強度熱力圖，支援終端 ASCII 和 HTML 兩種輸出格式。

# 終端 ASCII 熱力圖
wifisense heatmap -f scan_data.json

# 匯出 HTML 熱力圖
wifisense heatmap -f scan_data.json -o heatmap.html --format html

# 按 SSID 過濾
wifisense heatmap -f scan_data.json --filter-ssid "MyWiFi"

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`-o, --output`	輸出檔案路徑	`heatmap.html`
`--format`	輸出格式（`terminal` / `html`）	`terminal`
`--filter-ssid`	按 SSID 過濾（部分比對）	-
`--filter-bssid`	按 BSSID 過濾（部分比對）	-

使用場景： 訊號覆蓋視覺化、AP 部署規劃、網路最佳化報告。

`wifisense trends` -- 歷史趨勢分析

分析 WiFi 訊號的歷史變化趨勢，偵測異常波動。

# 加入當前掃描資料並分析趨勢
wifisense trends -f scan_data.json

# 指定資料目錄並儲存結果
wifisense trends -f scan_data.json -d ./trend_data -o trends.json

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	-
`-d, --data-dir`	趨勢資料儲存目錄	-
`-o, --output`	趨勢分析結果輸出路徑	-

使用場景： 長期網路監控、訊號穩定性評估、異常事件回溯。

`wifisense report` -- 多格式報告匯出

將掃描和分析結果匯出為多種格式的報告。

# 匯出 JSON 報告
wifisense report -f scan_data.json -o report.json --format json

# 匯出 HTML 報告
wifisense report -f scan_data.json -o report.html --format html

# 匯出 CSV 報告
wifisense report -f scan_data.json -o report.csv --format csv

# 匯出 Markdown 報告（含原始資料）
wifisense report -f scan_data.json -o report.md --format markdown --include-raw

參數	說明	預設值
`-f, --file`	掃描結果 JSON 檔案路徑	必填
`-o, --output`	報告輸出檔案路徑	`report.json`
`--format`	報告格式（`json` / `csv` / `html` / `markdown`）	`json`
`--include-raw`	在報告中包含原始掃描資料	`false`

使用場景： 報告生成、資料歸檔、與其他系統整合。

💡 設計思路與迭代規劃

設計理念

零依賴哲學 -- 使用純 Python 標準函式庫實作所有功能，避免依賴地獄，確保在任何 Python 環境中都能穩定運行
隱私至上 -- 所有資料處理完全在本地完成，不發送任何網路請求，不收集任何使用者資訊
優雅降級 -- 當系統權限不足時，自動切換到模擬掃描器模式，確保工具在任何環境下都能正常展示和學習
模組化架構 -- 每個功能模組獨立解耦，便於單獨使用、測試和擴展

技術選型原因

決策	原因
純標準函式庫	消除依賴管理複雜度，提升安裝成功率和運行穩定性
CLI 工具形態	開發者友善，易於整合到腳本和 CI/CD 流水線
JSON 資料格式	通用、可讀、易於與其他工具和語言互動
MIT 協議	最大化開放性，鼓勵社群參與和商業使用

後續迭代計畫

v1.1 -- 新增即時監控模式（wifisense monitor）
v1.2 -- 支援 GPS 座標記錄，實現訊號地圖繪製
v1.3 -- 新增 Web Dashboard 視覺化介面
v2.0 -- 引入外掛系統，支援自訂分析模組
v2.1 -- 新增機器學習異常偵測模型

📦 安裝與部署指南

從原始碼安裝（開發模式）

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

系統權限說明

平台	掃描要求	備註
Linux	需要 root 權限或 `CAP_NET_RAW` 能力	可使用 `sudo wifisense scan`
macOS	需要授權定位服務	首次執行會彈出系統授權對話框
Windows	需要管理員權限	右鍵「以管理員身分執行」終端

提示： 如果沒有相應權限，WiFiSense 會自動降級為模擬掃描器，生成模擬資料用於功能展示。

設定檔

WiFiSense 支援透過設定檔自訂行為，設定檔路徑：~/.wifisense/config.json

🤝 貢獻指南

我們歡迎並感謝所有形式的貢獻！無論是提交 Bug、改善文件，還是貢獻程式碼。

貢獻步驟

Fork 本儲存庫
建立特性分支：git checkout -b feature/amazing-feature
提交變更：git commit -m 'Add some amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

開發環境建置

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

# 執行測試
python -m pytest tests/

程式碼規範

遵循 PEP 8 編碼規範
所有公共函式必須包含 docstring
提交前確保所有測試通過

📄 開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 WiFiSense Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

English

🎉 Introduction

WiFiSense is a lightweight WiFi signal intelligent analysis and environment awareness engine CLI tool, designed for developers, network engineers, and security researchers.

Core Value:

🔍 One-Click Insight -- Get a comprehensive analysis of your WiFi environment with simple command-line operations
🧠 Intelligent Awareness -- Beyond scanning: understand environmental changes, infer human presence, and track device dynamics
🪶 Ultra Lightweight -- Zero external dependencies, built entirely with Python standard library, ready to use out of the box

Pain Points Solved:

Existing WiFi analysis tools are either too heavy (e.g., Wireshark) or depend on numerous third-party libraries
Lack of capability to transform WiFi signal data into environmental awareness insights
Poor cross-platform compatibility, requiring different tools for different operating systems
Privacy concerns -- most tools collect and upload user data

Differentiating Highlights:

🚫 Zero Dependencies -- No third-party packages needed, just pip install and go
🔒 Privacy First -- All data is processed locally, no information is ever uploaded
🌍 Cross-Platform -- Full support for Linux, macOS, and Windows
🛡️ Graceful Degradation -- Automatically falls back to a mock scanner when system permissions are unavailable

✨ Core Features

📡 WiFi Signal Scanning -- Cross-platform scanning with automatic interface detection and automatic fallback to mock scanner when permissions are unavailable
📊 Signal Strength Analysis -- RSSI statistics, channel congestion analysis, security assessment, and Signal-to-Noise Ratio (SNR) estimation
🧬 Environment Fingerprinting -- BSSID set + signal feature hashing, supporting environment comparison and custom labeling
📍 Device Tracking -- Device appearance/disappearance detection, signal change tracking, and history management
👤 Presence Detection -- Infer human presence from WiFi device changes, activity level assessment, and people count estimation
🗺️ Signal Heatmap -- Terminal ASCII heatmap + HTML visual export for intuitive signal distribution display
📈 Historical Trend Analysis -- Signal change trends, anomaly detection, and environment stability scoring
📝 Multi-Format Report Export -- Supports JSON / CSV / HTML / Markdown formats

🚀 Quick Start

Requirements

Python 3.8+ (supports 3.8, 3.9, 3.10, 3.11, 3.12)
No third-party dependencies required

Installation

# Option 1: Install from GitHub (recommended)
pip install git+https://github.com/gitstq/WiFiSense.git

# Option 2: Install from source
git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install .

Run Commands

# Scan WiFi networks
wifisense scan

# Analyze scan results
wifisense analyze -f data.json

# Generate signal heatmap
wifisense heatmap -f data.json

# Generate environment fingerprint
wifisense fingerprint --label "MyOffice"

# Presence detection
wifisense presence -f data.json

# Generate analysis report
wifisense report -f data.json

📖 Detailed Usage Guide

`wifisense scan` -- WiFi Signal Scanning

Scan surrounding WiFi networks and collect signal data.

# Basic scan (auto-select interface, default 5 seconds)
wifisense scan

# Specify interface and duration, save results
wifisense scan -i wlan0 -d 10 -o scan_data.json

# Disable mock fallback (error out when no permission)
wifisense scan --no-mock

Parameter	Description	Default
`-i, --interface`	Network interface name	`auto`
`-d, --duration`	Scan duration in seconds	`5`
`-o, --output`	Output file path for results (JSON)	-
`--no-mock`	Disable mock scanner fallback	`false`

Use Cases: Network environment survey, signal coverage assessment, routine network monitoring.

`wifisense analyze` -- Signal Strength Analysis

Perform in-depth analysis on scan results, including RSSI statistics, channel distribution, and security assessment.

# Analyze scan data
wifisense analyze -f scan_data.json

# Analyze and save results
wifisense analyze -f scan_data.json -o analysis.json

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`-o, --output`	Output path for analysis results	-

Use Cases: Network optimization, channel selection recommendations, security auditing.

`wifisense fingerprint` -- Environment Fingerprinting

Generate a unique environment fingerprint based on WiFi signal characteristics, supporting environment identification and comparison.

# Generate a labeled environment fingerprint
wifisense fingerprint -f scan_data.json --label "MyOffice"

# Generate fingerprint and compare with known fingerprints
wifisense fingerprint -f scan_data.json --label "Home" --compare

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`--label`	Environment label name	`""`
`--compare`	Compare with known fingerprints	`false`

Use Cases: Indoor positioning, environment identification, multi-location management.

`wifisense track` -- Device Tracking

Track WiFi device appearance, disappearance, and signal changes.

# Track device changes
wifisense track -f scan_data.json

# Specify data storage directory
wifisense track -f scan_data.json -d ./tracker_data

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`-d, --data-dir`	Directory for tracker data storage	-

Use Cases: Device monitoring, network asset management, rogue device detection.

`wifisense presence` -- Presence Detection

Infer human presence status and activity level based on WiFi device signal changes.

# Detect human presence in the current environment
wifisense presence -f scan_data.json

# Specify data storage directory (for historical comparison)
wifisense presence -f scan_data.json -d ./presence_data

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`-d, --data-dir`	Directory for presence data storage	-

Use Cases: Smart home automation, office occupancy detection, security assistance.

`wifisense heatmap` -- Signal Heatmap

Generate WiFi signal strength heatmaps in terminal ASCII or HTML format.

# Terminal ASCII heatmap
wifisense heatmap -f scan_data.json

# Export HTML heatmap
wifisense heatmap -f scan_data.json -o heatmap.html --format html

# Filter by SSID
wifisense heatmap -f scan_data.json --filter-ssid "MyWiFi"

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`-o, --output`	Output file path	`heatmap.html`
`--format`	Output format (`terminal` / `html`)	`terminal`
`--filter-ssid`	Filter by SSID (partial match)	-
`--filter-bssid`	Filter by BSSID (partial match)	-

Use Cases: Signal coverage visualization, AP deployment planning, network optimization reports.

`wifisense trends` -- Historical Trend Analysis

Analyze historical WiFi signal trends and detect anomalous fluctuations.

# Add current scan data and analyze trends
wifisense trends -f scan_data.json

# Specify data directory and save results
wifisense trends -f scan_data.json -d ./trend_data -o trends.json

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	-
`-d, --data-dir`	Directory for trend data storage	-
`-o, --output`	Output path for trend results	-

Use Cases: Long-term network monitoring, signal stability assessment, anomaly event investigation.

`wifisense report` -- Multi-Format Report Export

Export scan and analysis results in multiple report formats.

# Export JSON report
wifisense report -f scan_data.json -o report.json --format json

# Export HTML report
wifisense report -f scan_data.json -o report.html --format html

# Export CSV report
wifisense report -f scan_data.json -o report.csv --format csv

# Export Markdown report (with raw data)
wifisense report -f scan_data.json -o report.md --format markdown --include-raw

Parameter	Description	Default
`-f, --file`	Path to scan results JSON file	Required
`-o, --output`	Report output file path	`report.json`
`--format`	Report format (`json` / `csv` / `html` / `markdown`)	`json`
`--include-raw`	Include raw scan data in report	`false`

Use Cases: Report generation, data archiving, integration with other systems.

💡 Design Philosophy & Roadmap

Design Principles

Zero Dependency Philosophy -- All functionality is implemented using only the Python standard library, eliminating dependency hell and ensuring stable operation in any Python environment
Privacy First -- All data processing is done entirely locally; no network requests are sent, and no user information is collected
Graceful Degradation -- When system permissions are insufficient, automatically switches to mock scanner mode, ensuring the tool can always be demonstrated and learned from
Modular Architecture -- Each functional module is independently decoupled, making it easy to use, test, and extend individually

Technical Decisions

Decision	Rationale
Pure Standard Library	Eliminates dependency management complexity, improves installation success rate and runtime stability
CLI Tool Form Factor	Developer-friendly, easy to integrate into scripts and CI/CD pipelines
JSON Data Format	Universal, readable, easy to interact with other tools and languages
MIT License	Maximizes openness, encouraging community participation and commercial use

Roadmap

v1.1 -- Add real-time monitoring mode (wifisense monitor)
v1.2 -- Support GPS coordinate recording for signal map generation
v1.3 -- Add Web Dashboard visualization interface
v2.0 -- Introduce plugin system for custom analysis modules
v2.1 -- Add machine learning anomaly detection model

📦 Installation & Deployment Guide

Install from Source (Development Mode)

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

System Permissions

Platform	Scanning Requirements	Notes
Linux	Root privileges or `CAP_NET_RAW` capability	Use `sudo wifisense scan`
macOS	Location Services authorization required	System authorization dialog appears on first run
Windows	Administrator privileges required	Right-click terminal and "Run as administrator"

Tip: If you don't have the required permissions, WiFiSense will automatically fall back to a mock scanner that generates simulated data for feature demonstration.

Configuration File

WiFiSense supports behavior customization through a configuration file at: ~/.wifisense/config.json

🤝 Contributing Guide

We welcome and appreciate contributions in all forms! Whether it's filing bugs, improving documentation, or contributing code.

How to Contribute

Fork this repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add some amazing feature'
Push the branch: git push origin feature/amazing-feature
Submit a Pull Request

Development Setup

git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

# Run tests
python -m pytest tests/

Code Standards

Follow PEP 8 coding conventions
All public functions must include docstrings
Ensure all tests pass before submitting

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 WiFiSense Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

WiFiSense -- Made with ❤️ by WiFiSense Contributors

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
tests		tests
wifisense		wifisense
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

WiFiSense

简体中文

🎉 项目介绍

✨ 核心特性

🚀 快速开始

环境要求

安装步骤

运行命令

📖 详细使用指南

wifisense scan -- WiFi 信号扫描

wifisense analyze -- 信号强度分析

wifisense fingerprint -- 环境指纹生成

wifisense track -- 设备追踪

wifisense presence -- 存在检测

wifisense heatmap -- 信号热力图

wifisense trends -- 历史趋势分析

wifisense report -- 多格式报告导出

💡 设计思路与迭代规划

设计理念

技术选型原因

后续迭代计划

📦 安装与部署指南

从源码安装（开发模式）

系统权限说明

配置文件

🤝 贡献指南

贡献步骤

开发环境搭建

代码规范

📄 开源协议

繁體中文

🎉 專案介紹

✨ 核心特性

🚀 快速開始

環境要求

安裝步驟

執行命令

📖 詳細使用指南

wifisense scan -- WiFi 訊號掃描

wifisense analyze -- 訊號強度分析

wifisense fingerprint -- 環境指紋生成

wifisense track -- 設備追蹤

wifisense presence -- 存在偵測

wifisense heatmap -- 訊號熱力圖

wifisense trends -- 歷史趨勢分析

wifisense report -- 多格式報告匯出

💡 設計思路與迭代規劃

設計理念

技術選型原因

後續迭代計畫

📦 安裝與部署指南

從原始碼安裝（開發模式）

系統權限說明

設定檔

🤝 貢獻指南

貢獻步驟

開發環境建置

程式碼規範

📄 開源協議

English

🎉 Introduction

✨ Core Features

🚀 Quick Start

Requirements

Installation

Run Commands

📖 Detailed Usage Guide

wifisense scan -- WiFi Signal Scanning

wifisense analyze -- Signal Strength Analysis

wifisense fingerprint -- Environment Fingerprinting

wifisense track -- Device Tracking

wifisense presence -- Presence Detection

wifisense heatmap -- Signal Heatmap

wifisense trends -- Historical Trend Analysis

wifisense report -- Multi-Format Report Export

💡 Design Philosophy & Roadmap

`wifisense scan` -- WiFi 信号扫描

`wifisense analyze` -- 信号强度分析

`wifisense fingerprint` -- 环境指纹生成

`wifisense track` -- 设备追踪

`wifisense presence` -- 存在检测

`wifisense heatmap` -- 信号热力图

`wifisense trends` -- 历史趋势分析

`wifisense report` -- 多格式报告导出

`wifisense scan` -- WiFi 訊號掃描

`wifisense analyze` -- 訊號強度分析

`wifisense fingerprint` -- 環境指紋生成

`wifisense track` -- 設備追蹤

`wifisense presence` -- 存在偵測

`wifisense heatmap` -- 訊號熱力圖

`wifisense trends` -- 歷史趨勢分析

`wifisense report` -- 多格式報告匯出

`wifisense scan` -- WiFi Signal Scanning

`wifisense analyze` -- Signal Strength Analysis

`wifisense fingerprint` -- Environment Fingerprinting

`wifisense track` -- Device Tracking

`wifisense presence` -- Presence Detection

`wifisense heatmap` -- Signal Heatmap

`wifisense trends` -- Historical Trend Analysis

`wifisense report` -- Multi-Format Report Export

Packages