makalin/rf-correlator

# RF Correlator - 被动式 RF 指纹关联 用于匿名设备连续性分析的被动式 Wi-Fi 和 Bluetooth 信号关联。本项目关注行为 RF 模式，而非身份。 ## 重要声明 本项目不识别人员或设备所有者。 - 无 IMEI、IMSI 或电话号码 - 不进行 MAC 去随机化 - 无主动攻击、欺骗或探测 - 仅限被动监听 - 匿名的连续性与存在性分析 - 仅供研究与教育使用 如果您正在寻找用于监视或身份追踪的工具，请勿使用本项目。 ## 目的 现代设备会将其 Wi-Fi 和 BLE 地址随机化。直接识别被故意设计得非常困难，但仍然可以从匿名的 RF 事件中研究时间与行为的连续性。 RF Correlator 演示了如何将被动事件流进行聚类，以推断： - 设备持久性 - 存在时长 - 移动模式 ## 本仓库实现的内容 本仓库提供了一个实用的离线分析 pipeline： - 用于被动 Wi-Fi 和 BLE 事件日志的 CSV 获取 - 对短暂标识符的隐私保护清理 - 针对时间、RSSI 漂移、信道变化以及 Wi-Fi/BLE 共现的特征提取 - 时间关联评分 - 在安装了 `hdbscan` 时使用基于密度的聚类，否则使用 `DBSCAN` 作为后备方案 - 匿名设备时间轴生成 - 合成样本数据与自动化测试 它不包含实时的数据包捕获固件或特定硬件的嗅探代码。 ## 架构 ``` RF Event Log (Wi-Fi / BLE) | v Feature Extraction | v Temporal Correlation | v Density-Based Clustering | v Anonymous Device Timeline ``` ## 输入格式 输入文件为包含以下必需列的 CSV： - `timestamp` - ISO-8601 时间戳 - `radio` - `wifi` 或 `ble` - `rssi` - 接收信号强度 - `channel` - 信道编号 - `sensor_id` - 观测传感器标识符 可选列： - `ephemeral_id` - 短暂的数据包标识符；它将被哈希处理并从分析输出中丢弃 ## 快速开始 ``` python -m venv .venv .venv\Scripts\activate pip install -e .[dev] python -m rf_correlator.cli --sample-data --output output/timelines.csv pytest ``` CLI 会打印一份简短的 JSON 摘要，并将生成的时间轴写入 `output/timelines.csv`。 ## 示例输出 ``` cluster_id,event_count,first_seen,last_seen,duration_seconds,dominant_sensor,radios,mean_rssi,confidence,pattern 0,10,2026-01-01T18:42:00+00:00,2026-01-01T18:42:51+00:00,51.0,sensor-a,"ble,wifi",-50.5,0.731,stationary 1,10,2026-01-01T18:42:20+00:00,2026-01-01T18:43:11+00:00,51.0,sensor-a,"ble,wifi",-78.0,0.684,moving ``` ## 硬件背景 实际部署中的典型数据源可能包括： - ESP32 捕获节点 - 处于监听模式且支持 BLE 的 Linux 笔记本电脑 - 基于 SDR 的研究装置 这些捕获组件被有意排除在本仓库的范围之外。 ## 法律与道德声明 - 不应存储任何个人数据 - MAC 地址在分析前应进行哈希处理或丢弃 - 不应创建长期标识符 - 不应尝试跨数据集的身份关联 本仓库仅用于隐私保护的研究工作流。 ## 路线图 - ESP32 嗅探器固件 - 实时可视化 dashboard - 多传感器关联 - 公开的匿名化数据集 - 学术论文草案 ## 许可证 MIT License。 本 README 中的道德约束属于项目指导与贡献政策，而非一份单独的许可文件。

标签：BLE, DBSCAN, HDBSCAN, MAC随机化, Python, RF指纹分析, Wi-Fi分析, 信号关联, 匿名分析, 学术研究, 射频分析, 数据管道, 文档结构分析, 无后门, 无线协议, 无线路由, 时间序列分析, 渗透测试(防御视角), 网络安全, 聚类算法, 蓝牙分析, 被动监听, 设备轨迹分析, 软件工程, 逆向工具, 防御绕过, 隐私保护, 隐私计算