Ali-hey-0/Browser-Data-Logger

## ✨ 这是什么？ Browser Data Logger 是一个客户端 JavaScript 研究工具包，旨在探索现代浏览器 API 暴露的信息。 它从多个独立来源收集浏览器遥测数据，将结果标准化为单一报告，并可以通过以下方式传输收集到的数据： - 📡 **WebSocket** — 机器可读的实时遥测 - 🤖 **Telegram Bot API** — 人类可读的报告及可选的媒体传输 本项目特意采用模块化的收集器架构构建。每个功能独立运行，并且故障会被隔离，允许不受支持或被阻止的浏览器 API 失败，而不会停止其余的收集流水线。 ## 🧭 项目概览 | 层级 | 职责 | |---|---| | 🧩 **收集器** | 查询单个浏览器 API 和数据源 | | 🧠 **聚合器** | 将结果合并为统一的遥测对象 | | 🛡️ **错误隔离** | 防止一个 API 失败导致整个收集周期停止 | | 📦 **格式化器** | 将收集的数据转换为兼容 Telegram 的报告 | | 📡 **WebSocket 传输** | 传输结构化 JSON 事件和完整快照 | | 🤖 **Telegram 传输** | 交付文本报告和可选的 JPEG 截图 | | 🔁 **收集循环** | 定期重复收集过程 | ## 📚 目录 - [✨ 这是什么？](#-what-is-this) - [🧭 项目概览](#-project-at-a-glance) - [🧰 功能](#-capabilities) - [🏗️ 架构](#️-architecture) - [🔄 收集生命周期](#-collection-lifecycle) - [⚡ 快速开始](#-quick-start) - [⚙️ 配置](#️-configuration) - [📡 WebSocket 集成](#-websocket-integration) - [🤖 Telegram 集成](#-telegram-integration) - [📊 数据目录](#-data-catalog) - [🔐 权限与浏览器限制](#-permissions--browser-restrictions) - [🔒 安全与隐私](#-security--privacy) - [⚠️ 已知限制](#️-known-limitations) - [🛠️ 故障排除](#️-troubleshooting) - [🗺️ 路线图](#️-roadmap) - [🤝 贡献](#-contributing) - [📜 许可证](#-license) ## 🧰 功能 本项目围绕独立的数据收集模块进行组织。

🖥️ 浏览器与设备遥测

收集浏览器和执行环境元数据，例如： - User agent - 平台 - 首选语言和语言列表 - 屏幕分辨率 - 颜色深度 - 设备像素比 - 时区 - 硬件并发数 - 设备内存（在暴露的情况下） - 触摸支持 - WebDriver 标志 - Referrer - 当前 URL - 窗口尺寸 - 屏幕方向 - JavaScript 堆信息（在可用的情况下） - 基本性能计时信息 静态值在第一次收集周期后会被缓存在内存中。

🎨 指纹收集面

探索多种浏览器指纹收集面： | 收集面 | 检查内容 | |---|---| | 🖼️ **Canvas** | Canvas 渲染输出 | | 🎮 **WebGL** | 渲染器、供应商、版本、支持的扩展 | | 🔊 **Audio** | 音频上下文特征 | | 🔤 **Fonts** | 选定字体的可用性 | | 🧱 **WebAssembly** | 基本的 WASM 支持 |

🌐 网络与位置

项目可以结合： - 公共 IP 查询 - 基于 IP 的地理定位元数据 - ISP / 组织信息 - ASN - 时区 - 大致坐标 - 浏览器地理位置（在可用且被允许的情况下） - 通过 OpenStreetMap Nominatim 进行反向地理编码 本项目尝试区分浏览器提供的精确位置和基于 IP 的大致位置。

🔋 运行时与连接状态

在浏览器支持的情况下： - 电池电量 - 充电状态 - 充电和放电预估时间 - 有效网络类型 - 预估下行速率 - RTT - 数据节省状态 某些状态更改可以作为实时 WebSocket 事件转发。

📱 传感器与硬件 API

收集器可以探测浏览器可访问的功能，包括： - 加速度计数据 - 设备方向 - 环境光传感器 - 游戏手柄 - MIDI 设备 - USB 设备 - WebXR 沉浸式 VR 支持

📋 存储与客户端状态

当前实现会检查以下内容的可用性及可访问内容： - 当前文档可用的 Cookies - `localStorage` - `sessionStorage` - IndexedDB 可用性 - 导航历史元数据

🎙️ 媒体 API

在获得浏览器权限且处于安全上下文的前提下，项目可以与以下内容进行交互： - 🎤 麦克风输入 - 📸 摄像头输入 - 🖥️ 屏幕共享 生成的媒体数据在传输前会被转换为 JPEG 或元数据表示形式。

⌨️ 交互遥测

收集器可以观察页面生命周期内的选定交互事件，包括： - 键盘事件 - 鼠标移动 - 点击事件 为了减少无限制的增长，当前实现对某些交互收集进行了限制。

📡 多通道交付

收集到的信息可以通过两个独立的通道进行交付： **WebSocket** 适用于以下场景的结构化 JSON： - 仪表板 - 监控系统 - 事件流水线 - 自定义分析工具 **Telegram** 人类可读的报告，附带可选的 JPEG 媒体附件。 两种交付路径均实现了带有指数退避的重试机制。

## 🏗️ 架构 系统遵循简单的 **收集 → 聚合 → 格式化 → 传输** 流水线。 ``` flowchart TD A["Browser Loads java.js"] --> B["Initialize WebSocket"] B --> C["Start Collection Cycle"] C --> D["Parallel Collectors"] D --> D1["Permissions"] D --> D2["IP & Network"] D --> D3["Device Metadata"] D --> D4["Fingerprinting"] D --> D5["WebGPU"] D --> D6["Geolocation"] D --> D7["Battery"] D --> D8["Sensors"] D --> D9["Clipboard"] D --> D10["Storage"] D --> D11["WebRTC"] D --> D12["Interactions"] D --> D13["Media Devices"] D --> D14["Gamepad / MIDI / USB"] D --> D15["WebXR / History / Extensions"] D1 --> E["Unified Telemetry Object"] D2 --> E D3 --> E D4 --> E D5 --> E D6 --> E D7 --> E D8 --> E D9 --> E D10 --> E D11 --> E D12 --> E D13 --> E D14 --> E D15 --> E E --> F["Format Report"] F --> G["Telegram"] E --> H["WebSocket JSON"] G --> I["Text Report"] G --> J["Optional JPEG Media"] E --> K["Periodic Recollection"] K --> C ``` ### 核心设计原则 **⚡ 并行收集** 使用 `Promise.all` 并发执行独立的收集器。这减少了完成收集周期所需的时间，尽管某些 API 可能仍会引入自身的延迟。 **🧱 故障隔离** 每个收集器都有自己的错误边界。一项功能的失败不会阻止其他收集器完成收集。 **🗃️ 内存缓存** 一些相对静态的数据在第一次收集后会被缓存： - 设备元数据 - 指纹识别结果 - 基于 IP 的详细信息 这减少了后续收集周期中的重复工作。 **🔁 带有指数退避的重试** Telegram 交付使用逐渐延长的延迟来重试失败的请求： ``` 1s → 2s → 4s → 8s → 16s ``` ## 🔄 收集生命周期 每个收集周期遵循以下基本顺序： ``` ┌────────────────────┐ │ Start Collection │ └─────────┬──────────┘ │ ▼ ┌────────────────────┐ │ Check Secure Context│ └─────────┬──────────┘ │ ▼ ┌────────────────────┐ │ Run Collectors │ │ in Parallel │ └─────────┬──────────┘ │ ▼ ┌────────────────────┐ │ Aggregate Results │ └─────────┬──────────┘ │ ├──────────────► WebSocket JSON │ ▼ ┌────────────────────┐ │ Format Text Report │ └─────────┬──────────┘ │ ▼ ┌────────────────────┐ │ Telegram Delivery │ └─────────┬──────────┘ │ ├──────────────► Text Report │ └──────────────► Optional Media ▼ ┌────────────────────┐ │ Wait ~120 seconds │ └─────────┬──────────┘ │ └──────────────► Repeat ``` ## ⚡ 快速开始 ### 1. 克隆仓库 ``` git clone https://github.com/Ali-hey-0/Browser-Data-Logger.git cd Browser-Data-Logger ``` ### 2. 配置 `java.js` 打开文件顶部的配置部分： ``` const BOT_TOKEN = 'YOUR_BOT_TOKEN'; const CHAT_ID = 'YOUR_CHAT_ID'; const DEBUG = false; ``` ### 3. 启动项目服务 许多浏览器 API 需要安全上下文。进行基本的本地测试： ``` python3 -m http.server 8000 ``` 然后打开： ``` http://localhost:8000 ``` ### 4. 加载脚本 将 JavaScript 文件包含在您的页面中： ``` ``` 脚本会自动初始化其 WebSocket 连接并开始一个收集周期。 ## ⚙️ 配置 主要配置值为： | 变量 | 用途 | |---|---| | `BOT_TOKEN` | Telegram Bot API 凭证 | | `CHAT_ID` | 目标 Telegram 聊天 | | `DEBUG` | 启用详细的浏览器控制台日志记录 | | `WS_URL` | WebSocket endpoint | ``` const BOT_TOKEN = 'YOUR_BOT_TOKEN'; const CHAT_ID = 'YOUR_CHAT_ID'; const DEBUG = false; ``` ### 推荐的配置模型 对于实际部署，建议通过您自己的后端路由收集的数据，而不是将敏感的 API 凭证直接放在客户端 JavaScript 中： ``` Browser │ ▼ Client Collector │ ▼ Your Backend ├── Telegram API ├── Database ├── Dashboard └── Analysis Pipeline ``` ## 📡 WebSocket 集成 收集器将结构化的 JSON 消息发送到配置的 WebSocket endpoint。 ### 最小化的 Node.js 接收器 ``` npm init -y npm install ws ``` 创建 `server.js`： ``` const WebSocket = require('ws'); const wss = new WebSocket.Server({ port: 8080 }); wss.on('connection', (ws) => { console.log('Client connected'); ws.on('message', (data) => { console.log('Received:', data.toString()); }); ws.on('close', () => { console.log('Client disconnected'); }); }); console.log('WebSocket server listening on ws://localhost:8080'); ``` 运行： ``` node server.js ``` 然后配置： ``` const WS_URL = 'ws://localhost:8080'; ``` ### WebSocket 事件示例

IP 元数据

``` { "ipDetails": { "city": "Example City", "country": "Example Country", "asn": "AS12345" } } ```

电池更新

``` { "batteryUpdate": { "charging": true, "timestamp": "2026-07-21T14:22:10.123Z" } } ```

交互事件

``` { "interaction": "Click:320,540:123456.78" } ```

完整收集快照

``` { "timestamp": "2026-07-21T14:22:10.123Z", "isSecure": true, "deviceInfo": {}, "network": {}, "battery": {} } ```

## 🤖 Telegram 集成 Telegram 被用作人类可读的交付通道。 收集器可以发送： | 类型 | 条件 | |---|---| | 📝 **文本报告** | 始终发送（在配置完成的情况下） | | 📸 **摄像头截图** | 摄像头可用 + 浏览器权限 + 安全上下文 | | 🖥️ **屏幕截图** | 浏览器支持屏幕共享 + 用户同意原生提示 | ### 🔁 重试机制 失败请求将使用指数退避进行重试： | 尝试次数 | 延迟 | |---|---| | 1 | 1 秒 | | 2 | 2 秒 | | 3 | 4 秒 | | 4 | 8 秒 | | 5 | 16 秒 | ## 📊 数据目录

🖥️ 设备元数据

| 数据 | 可用性 | |---|---| | User agent | 通常可用 | | 平台 | 通常可用 | | 语言 | 通常可用 | | 屏幕尺寸 | 通常可用 | | 像素比 | 通常可用 | | 时区 | 通常可用 | | CPU 核心数 | 取决于浏览器 | | 设备内存 | 取决于浏览器 | | 触摸支持 | 通常可用 | | WebDriver 标志 | 取决于浏览器 | | Referrer | 取决于导航上下文 | | JavaScript 堆 | 取决于浏览器 |

🎨 指纹识别

本项目检查： - Canvas 渲染 - WebGL 渲染器信息 - WebGL 供应商信息 - 支持的 WebGL 扩展 - 音频上下文特征 - 选定字体的可用性 - WebAssembly 支持

🌐 网络

项目可以收集： - 公共 IP 地址 - 大致的 IP 位置 - ISP / 组织 | ASN - 地区与国家 - 邮政编码 - 时区 - 大致坐标 该实现使用外部服务进行 IP 和地理定位信息扩充。

📍 地理定位

在可用且被允许的情况下： ``` Browser Geolocation │ ▼ Latitude / Longitude │ ▼ Reverse Geocoding │ ▼ Human-Readable Address ``` 如果浏览器地理定位失败，在可用时，该实现可能会保留基于 IP 的大致位置信息。

🔋 电池与网络状态

**电池数值**可能包括： - 电池百分比 - 充电状态 - 充电时间 - 放电时间 **网络数值**可能包括： - 有效连接类型 - 预估下行速率 - RTT - 数据节省状态

📱 传感器

支持的环境可能会暴露： - 加速度计读数 - 设备方向 - 环境光照度 可用性因浏览器、操作系统、设备、权限模型和安全上下文要求而有很大差异。

📦 存储

``` Cookies ├── document.cookie localStorage ├── Key/value data available to the current origin sessionStorage ├── Session-scoped key/value data IndexedDB └── Availability ``` 浏览器的同源策略仍然有效。

🖧 WebRTC

项目创建一个临时的对等连接，并观察浏览器暴露的 ICE 候选信息。生成的数据可能包含本地暴露的网络地址，具体取决于： - 浏览器实现 - WebRTC 隐私保护 - 网络配置 - mDNS 混淆

🎙️ 麦克风

在获得许可的情况下，实现步骤如下： 1. 请求麦克风访问权限 2. 创建音频上下文 3. 分析音频流 4. 提取基本的频域元数据 5. 停媒体轨道 当前实现发送的是元数据，而不是存储连续的录音。

📸 摄像头

摄像头模块： 1. 枚举视频输入设备 2. 尝试多种摄像头约束 3. 捕获单帧 4. 将该帧转换为 JPEG 5. 通过配置的交付通道发送生成的图像

🖥️ 屏幕截图

屏幕截图模块使用浏览器原生的屏幕共享 API。用户必须与浏览器的权限对话框进行交互。收集器不会在静默状态下绕过浏览器原生的屏幕共享权限流程。

⌨️ 交互事件

``` Keyboard Events │ ├── Key └── Timestamp Mouse Events │ ├── Movement ├── Coordinates └── Timestamp Click Events │ ├── Coordinates └── Timestamp ```

🎮 硬件与扩展 API

附加的功能检查包括：

## 🔐 权限与浏览器限制 现代浏览器有意限制了许多敏感 API。 | 功能 | 典型要求 | |---|---| | 📍 地理定位 | 用户许可 + 合适的上下文 | | 🎤 麦克风 | 用户许可 + 安全上下文 | | 📸 摄像头 | 用户许可 + 安全上下文 | | 🖥️ 屏幕共享 | 明确的用户交互 | | 📋 剪贴板 | 安全上下文及浏览器限制 | | 🔌 USB | 浏览器许可 / 用户交互 | | 🎹 MIDI | 取决于浏览器的权限模型 | | 📱 传感器 | 设备和浏览器支持 | | 🥽 WebXR | 兼容的硬件和浏览器 | 收集尝试失败并不一定代表存在软件错误。它可能仅仅意味着： ``` API unavailable OR Permission denied OR Browser restriction OR Insecure context OR Operating-system limitation ``` ## 🔒 安全与隐私 本项目可能会处理高度敏感的信息。 **请将以下内容视为敏感信息：** - 精确位置 - 摄像头图像 - 屏幕截图 - 剪贴板内容 - 键盘事件 - 本地网络信息 - 设备指纹 - 存储数据 ### 部署建议 **✅ 应该做的** - 仅在授权的系统上使用 - 在需要时获得知情同意 - 在实际部署中使用 HTTPS/WSS - 保护 Telegram 凭证 - 避免将机密提交到 Git - 尽可能减少收集的数据 - 限制对接收系统的访问 - 删除不再必要的数据 **❌ 不应该做的** - 秘密部署针对第三方 - 将其用作隐蔽的监控机制 - 未经授权收集凭证或个人信息 - 在公开仓库中暴露 bot token 或后端机密 - 认为浏览器的权限提示会自动使部署符合法律合规性 ## ⚠️ 已知限制 浏览器 API 并不统一。相同的代码在不同环境下的行为可能不同： - Chromium - Firefox - Safari - Android 浏览器 - iOS 浏览器 - 桌面环境 某些 API 可能会： - 完全不可用 - 需要权限门控 - 被浏览器策略禁用 - 仅限于安全上下文 - 受到隐私保护的限制 - 在不同设备上表现不一致 ## 🛠️ 故障排除

Telegram 消息未到达

检查： - Bot token - Chat ID - 网络连接 - Telegram API 可用性 - `DEBUG = true` 时的浏览器控制台输出

摄像头或麦克风访问失败

检查： - HTTPS 或 `localhost` - 浏览器权限状态 - 操作系统权限 - 是否有其他应用程序正在使用该设备

地理定位失败

可能的原因： - 用户拒绝许可 - 没有可用的位置提供程序 - 浏览器限制 - 超时 - 不安全的上下文 在可用的情况下，实现可能会回退到基于 IP 的大致位置。

WebSocket 连接失败

验证您的 `WS_URL`： ``` WS_URL │ ├── Correct protocol (ws:// or wss://) ├── Correct hostname ├── Correct port └── Server is running ``` 本地开发使用 `ws://`，受 TLS 保护的部署使用 `wss://`。

脚本似乎停止了

启用调试日志记录： ``` const DEBUG = true; ``` 然后检查浏览器控制台是否有错误。

## 🗺️ 路线图 ### 📊 可观测性 - 结构化事件 schema - 更好的收集器状态报告 - 各模块执行指标 - 收集延迟测量 ### 🖥️ 仪表板 - 实时 WebSocket 仪表板 - 设备/会话时间线 - 收集器状态可视化 - 事件过滤 ### 🧩 插件架构 未来的收集器接口可以允许注册模块而无需修改核心流水线： ``` registerCollector({ name: 'customCollector', collect: async () => { return {}; } }); ``` ### 🗄️ 数据后端 潜在的集成： - PostgreSQL - MongoDB - Elasticsearch - InfluxDB - ClickHouse ### 🛡️ 隐私工程 未来的改进可能包括： - 明确的按类别同意 - 数据最小化模式 - 收集器白名单 - 数据脱敏策略 - 仅本地操作 - 可配置的保留策略 ### 开发工作流 ``` git checkout -b feature/your-feature ``` 进行更改、测试并提交： ``` git add . git commit -m "Add your feature" git push origin feature/your-feature ``` 然后发起 Pull Request。 ### 贡献原则 - 保持收集器的模块化 - 优雅处理不支持的 API - 避免不必要地破坏现有配置 - 记录特定于浏览器的行为 - 不要引入硬编码的机密 - 清楚地记录敏感数据的收集 - 优先使用明确、易于理解的代码，而不是晦涩的抽象 ## 📜 许可证 本项目基于 [MIT 许可证](LICENSE)分发。 ## 🔗 项目 **仓库：** [github.com/Ali-hey-0/Browser-Data-Logger](https://github.com/Ali-hey-0/Browser-Data-Logger) 如需报告错误、提出建议和负责任的安全报告，请发起 [GitHub Issue](https://github.com/Ali-hey-0/Browser-Data-Logger/issues)。

标签：数据可视化, 自定义脚本