FelixDaCraft/v308-rtsp-hack

# 📹 v308-rtsp-hack [](LICENSE) [](https://www.python.org/) [](#-测试平台) [](#-贡献) ``` flowchart LR cam["📷 V308 camera
192.168.x.y"] client["🐍 v308_protocol (Python)

• LOGIN / PLAY replay
• AES-128-ECB key derivation
• Chunk demux + decrypt"] out["⚙️ ffmpeg / go2rtc / mediamtx
Frigate / Home Assistant / OBS"] cam -- "TCP/8800
proprietary, encrypted" --> client client -- "(video, pts_ms, h264_annexb)
(audio, pts_ms, aac_adts)" --> out classDef cam fill:#1e293b,stroke:#475569,color:#f8fafc classDef client fill:#0f766e,stroke:#14b8a6,color:#f0fdfa classDef out fill:#7c2d12,stroke:#ea580c,color:#fff7ed class cam cam class client client class out out ``` ## 🤔 为什么存在这个项目 你买了一个可爱的 Wi-Fi 相机。图像不错，APP 也能用……但是： - ❌ 没有 RTSP，没有 ONVIF，没有 HTTP UI — **相机被锁定在厂商 APP 中** - ❌ 即使在**同一个 Wi-Fi** 上，直播流也会经过厂商云端（延迟、停机、监控） - ❌ 无法直接集成到 **Home Assistant / Frigate / go2rtc / OBS** 这个项目释放了相机。它在 TCP/8800 上使用专有协议，解密 AES-128-ECB 流，给你一个**标准的 H.264/HEVC + AAC 比特流**，可以传输到任何地方。 | | 厂商 APP | 本项目 | |---|---|---| | 局域网延迟 | 2-3 秒（云中转） | **~500 毫秒** | | 需要互联网 | ✅ | ❌ | | 厂商账户 | ✅ | ❌ 模板捕获后不需要 | | 支持 go2rtc / Frigate / HA | ❌ | ✅ | | 自主托管 | ❌ | ✅ | | 代码可审计 | ❌ | ✅ | ## 🚀 快速开始 选择适合你配置的路径： ### 🏠 Home Assistant（HAOS / Supervised）— 最简单 安装捆绑的**插件**，将你的相机变成普通的 RTSP 源： - 📂 [`hass-addon/`](hass-addon/) — 复制到 HA 主机的 `/addons/local/v308_camera/`，重新加载，从插件商店安装 - ⚙️ 在插件 UI 中配置相机 IP + pcap 路径 - 📺 将**通用相机**指向 `rtsp://:8554/cam` 详细说明：[`hass-addon/README.md`](hass-addon/README.md)。 ### 🐳 Docker（任何主机）— 一行命令 ``` docker run -d --name v308 \ --network host \ -v /path/to/your_cam.pcap:/template.pcap:ro \ -e CAM_IP=192.168.1.42 \ ghcr.io/felixdacraft/v308-rtsp-hack:latest ``` 然后将任何 RTSP 客户端连接到 `rtsp://:8554/cam`。容器会自动从你的 pcap 中检测 LOGIN/PLAY 源端口。 ### 🐍 独立 Python — 用于研究协议 ``` git clone https://github.com/FelixDaCraft/v308-rtsp-hack.git cd v308-rtsp-hack pip install -r requirements.txt # Capture 30 s of live stream to disk python examples/capture_to_file.py \ --cam-ip \ --pcap captures/your_cam.pcap \ --duration 30 \ --video-out /tmp/cam.h264 \ --audio-out /tmp/cam.aac # Don't know which LOGIN/PLAY src ports your pcap holds? python tools/find_pcap_ports.py captures/your_cam.pcap # Mux to MP4 with ffmpeg ffmpeg -f h264 -i /tmp/cam.h264 -f aac -i /tmp/cam.aac -c copy /tmp/cam.mp4 ``` ## 🧰 包含内容 ``` . ├── 📖 README.md ← you are here ├── 📜 LICENSE ← MIT ├── 📦 requirements.txt ├── 🐳 Dockerfile ← universal image (HA add-on base + standalone) ├── 🔌 v308_protocol/ ← the actual protocol module │ ├── key_derivation.py ← AES-128-ECB key formula │ ├── stream_decoder.py ← chunk parser + per-mode decryption │ └── v308_client.py ← LOGIN/PLAY replay + iter_streams ├── 🛠️ examples/ │ ├── capture_to_file.py ← dump 30 s to disk │ └── stream_to_ffmpeg.py ← pipe straight into ffmpeg ├── 🔍 tools/ │ └── find_pcap_ports.py ← auto-detect LOGIN/PLAY src ports ├── 📦 docker/ │ ├── entrypoint.sh ← runs mediamtx + v308 + ffmpeg │ └── mediamtx.yml ← bundled RTSP/HLS/WebRTC server config ├── 🏠 hass-addon/ ← Home Assistant add-on │ ├── config.yaml ← add-on manifest + UI options │ ├── Dockerfile ← extends the base image │ ├── run.sh ← bridges HA options → env vars │ └── README.md ← install + use guide ├── 📁 captures/ ← put your own .pcap here │ └── README.md ← how to capture └── 📚 docs/ └── REVERSE_ENGINEERING.md ← full RE writeup (Ghidra + Frida) ``` ## 🔧 工作原理（简述） 1. 🎯 **发现协议。** 厂商 APP → 相机使用专有二进制协议在 TCP/8800 上通信。AES-128-ECB 加密流，在块边界有明文标记。 2. 🔑 **找到密钥。** 在 Ghidra 中逆向厂商 APK 的 `libhsMediaLibrary.so`。函数 `HSLiveDataV2Transmitter::updateLoginHandle` 将密钥构建为 `KEY[0..3] = sid || KEY[4..15] = 硬编码的 12 字节常量`。用 Frida 钩子验证 `AES_set_decrypt_key`。 3. 🎟️ **重放 LOGIN。** 认证 blob 是签名的，但相机只检查时间戳是否最近。捕获一次有效的 LOGIN，在偏移量 `[17:36]` 刷新时间戳，即可永久重放。 4. ▶️ **播放。** 发送 4 个 PLAY 包，在已知偏移量注入新 sid。相机开始流传输。 5. 🔓 **解密 + 解复用。** 按长度字段遍历块，通过 2 字节标记识别类型（`7f 28`/`29` = HEVC，`7f 00`/`01` = H.264，`7f 18` = AAC），应用正确的解密模式（视频选择性解密，音频全解密）。 6. ⏱️ **原生 PTS。** 每个块的内部头部携带毫秒精度的 PTS，音频和视频共享 — 将它们作为 Matroska 时间码，实现完美的 A/V 同步。 → 包含 Ghidra 截图、Frida 追踪和注意事项的完整分析：[`docs/REVERSE_ENGINEERING.md`](docs/REVERSE_ENGINEERING.md) ## ✅ 测试平台 - **📷 Xiaovv XVVE31**（也以各种 Macrovideo SKU 销售） - **🔧 固件版本 > v30**（2023 年后的构建 — AES 密钥派生公式针对 `0x1e < firmwareVersion` 代码路径） - **📐 分辨率**：HD 主码流和 640×360 子码流 - **🎥 编解码器**：H.264 主码流 + HEVC（取决于相机配置） - **🔊 音频**：AAC-LC 单声道，16 kHz ## 🌐 可能也适用 协议栈来自 **Macrovideo / 杭州丽川 SDK**（又名 "HS" / "HSCam"）的 `libhsMediaLibrary.so`。它被打包在**很多** OEM 品牌中。如果你的相机满足以下**全部四个**条件，很可能是候选产品： - 📲 厂商 APP 使用 **8-11 位 P2P UID**（你扫描相机上的二维码配对） - 🔍 厂商 APK 包含 `lib/*/libhsMediaLibrary.so` — 用 `unzip -l vendor_app.apk | grep libhs` 检查 - 🌐 相机在局域网时监听 **TCP/8800**（`nmap -p 8800 `） - ☁️ 厂商云使用类似 `*.macrovideo.cn`、`*.eye4.cn` 的域名 已知捆绑该 SDK 的 APP（*非完整列表 — 请提交 issues / PRs 扩展*）： | 品牌 / APP | 状态 | |---|---| | Xiaovv | ✅ 已测试 | | LookCam / LookCam Pro | 🟡 可能（相同 SDK） | | Eye4 / VStarcam（部分 VS 前缀相机） | 🟡 可能 | | YsxLite / YS / YsxPro | 🟡 可能 | | 各种 Aliexpress 无名相机（"HD WiFi"、"P2P IP cam"） | 🟡 可能 | ## ❌ 已知不适用 - v30 之前的固件（不同的密钥派生，尚未实现 — 欢迎 PR） - 非 Macrovideo SDK：**Tuya、Yi、Ezviz、Reolink、TP-Link、Wyze** — 这些有各自的协议 ## 🔌 集成 ### 🐳 go2rtc（推荐） 在 `go2rtc.yaml` 中添加为 exec 源： ``` streams: cam: - exec:python3 /path/to/v308-rtsp-hack/examples/stream_to_ffmpeg.py --cam-ip 192.168.X.X --pcap /path/to/your_cam.pcap --login-src-port XXXXX --play-src-port XXXXX --audio-fifo /tmp/v308-audio.fifo#killsignal=15 ``` go2rtc 然后重新发布为 **RTSP / RTMP / WebRTC / HLS**，供任何消费者使用（Frigate、Home Assistant、mediamtx、OBS……）。 ### 📺 Frigate / Home Assistant / mediamtx 使用 go2rtc 重新发布的 RTSP — 你的标准 `rtsp://homelab:8554/cam` 可以像相机原生支持 RTSP 一样工作。 ### 🎛️ OBS / VLC / mpv 直接打开 `rtsp://homelab:8554/cam`。 ## 🧱 限制 - **双会话限制。** 相机拒绝第三个并发流 — 从**同一个** `iter_streams` 调用中获取视频和音频（本模块已经这样做）。 - **PPS 嵌入特性。** 此固件在 SPS RBSP 内以 2 字节起始码嵌入 H.264 PPS NAL。我们会即时重写为标准 Annex-B。如果你构建自定义解码器，请注意这一点。 - **无相机控制。** 仅支持直播。PTZ、运动警报、OSD 等需要扩展 LOGIN 模板以包含额外的命令包。 ## 🤝 贡献 非常欢迎 PR — 特别是： - 📷 **工作或不工作**的相机型号（扩展兼容性表） - 🔑 不同固件的 AES 后缀（扩展 `key_derivation.py`） - 🐳 Docker 镜像、Home Assistant 集成、Frigate 配置片段 - 🧪 测试脚本和fixture - 📝 更好的文档 / 翻译 ## 📚 致谢 / 先前工作 - 🔬 [Ghidra](https://ghidra-sre.org/) 用于静态分析 `libhsMediaLibrary.so` - 🐉 [Frida](https://frida.re/) 用于运行时 AES 密钥验证 - 🐍 [`scapy`](https://scapy.net/) 用于 pcap 解析 - 🔐 [`pycryptodome`](https://pycryptodome.readthedocs.io/) 用于 AES-128-ECB 如果你发现相关项目或其他固件变体，**请提交 issue** — 记录的变体越多，解放相机越多。 ## ⚖️ 许可证 [MIT](LICENSE)。 这是对未文档化协议的干净室重新实现，用于**互操作性目的**。未重新分发任何厂商代码。仅在你拥有的相机上使用。

标签：AAC, AES加密, DNS 反向解析, Frigate, H.264, HEVC, Home Assistant, IoT安全, IP摄像头, Macrovideo, Python, RTSP替代方案, TCP/8800, V308, Xiaovv, 云资产清单, 内核驱动, 协议分析, 无后门, 智能家居, 权限提升, 流媒体, 网络协议, 视频流处理, 视频解码, 请求拦截, 逆向工程, 防御绕过