kmay89/securaCV

# SecuraCV [](https://github.com/hacs/integration) [](https://github.com/kmay89/securaCV/actions/workflows/validate.yml)  ### 拥有 24 小时记忆的安全摄像头。 视频片段保留在您的本地硬件上并会自动删除。唯一持久保存的是一份防篡改日志， 证明没有任何人——包括您自己——修改过该记录。 ## 安装（3 步） **1.** 在 Raspberry Pi 4/5 或 PC 上安装 [Home Assistant OS](https://www.home-assistant.io/installation/)。 **2.** 打开 Terminal 插件（或 SSH）并运行： ``` curl -fsSL https://raw.githubusercontent.com/kmay89/securaCV/main/scripts/install.sh | bash ``` **3.** 按照设置向导操作——从以下路径打开 Privacy Witness Kernel 插件： Settings → Add-ons → Privacy Witness Kernel → Open Web UI。 完成。摄像头片段将出现在 Frigate 中，并带有**已验证 ✓** 的事件徽章。 ## 工作原理（面向普通用户） - 您的摄像头通过 **Frigate**（一个开源 NVR）在本地录制片段 - 片段在 **24 小时后自动删除**（可配置——由您选择保留时长） - SecuraCV 为每个检测到的事件保留一份**加密见证日志** - 日志具有防篡改特性：如果任何人——包括您自己——修改了它，签名就会失效 - 如果您需要证明发生过的事情，请**打破玻璃**——这是一个多方授权流程，需要您指定的受托人批准访问 - 任何人都无法篡改日志，即使是系统管理员也不行 **每日摘要：** 每天早上您会收到推送通知，总结每个区域的事件计数，并确认所有见证均有效。 **模式警报：** 异常时间的活动或意外静默的区域会自动触发高优先级的推送通知。 ## 所需物品 | 项目 | 备注 | |------|-------| | Raspberry Pi 4 (4 GB+) 或 x86 PC | Pi 5 运行良好；支持 3 个 10 fps 的摄像头 | | Home Assistant OS | 从官方镜像安装 | | 支持 RTSP 的 IP 摄像头 | 任何 Hikvision、Dahua、Reolink、Amcrest、Ubiquiti 等品牌 | | HA Companion App（可选） | 用于向您的手机发送推送通知 | ## 工作原理（面向工程师） SecuraCV 封装了 [Frigate](https://frigate.video/)（负责摄像头数据接入、对象检测、片段存储和保留），并搭配一个 **Privacy Witness Kernel**，该内核： 1. 订阅 Frigate 的 MQTT 事件流 2. 将原始检测事件转换为保护隐私的语义声明 （例如 `BoundaryCrossingObjectLarge`），不含原始帧、无精确时间戳、 无身份数据——遵循[不变量约束](spec/invariants.md) 3. 将每个声明附加到一个**哈希链式、Ed25519 签名的仅追加日志** 4. 将敏感声明封装进加密的保管库信封（需要打破玻璃机制才能打开） 5. 通过 MQTT Discovery 将验证状态发布回 Home Assistant 结果是：一个取证级别的事件日志，证明了摄像头看到的内容， 同时丢弃了所有可能用于大规模监控的数据。 ``` Camera → Frigate (clips, detection) → MQTT → Privacy Witness Kernel ↓ Hash-chained log + sealed vault ↓ HA integration (sensors, verification) ↓ Your phone (daily digest, alerts) ``` ### 规范说明 - [`spec/invariants.md`](spec/invariants.md) — 七项不可妥协的隐私约束（在代码中强制执行） - [`spec/event_contract.md`](spec/event_contract.md) — 允许的事件结构和禁止的声明 - [`spec/threat_model.md`](spec/threat_model.md) — 范围内外的威胁 - [`kernel/architecture.md`](kernel/architecture.md) — 组件隔离，信任边界 **SecuraCV** 是一个保护隐私的计算机视觉见证系统。 # Witness Kernel Privacy Witness Kernel (PWK) 的核心库和工具。 ## 快速开始：运行演示 ``` cargo run --bin demo ``` 此演示将相关产物写入 `./demo_witness.db`、`./demo_out/export_bundle.json`，以及 位于 `./vault/envelopes` 的保管库目录（除非您覆盖了 `--out` / `--vault`）。请使用以下命令验证日志 完整性： ``` cargo run --bin log_verify -- --db demo_witness.db ``` ### 篡改演示 ``` cargo run --bin demo cargo run --bin log_verify -- --db demo_witness.db cargo run --bin export_verify -- --db demo_witness.db --bundle demo_out/export_bundle.json printf "\n" >> demo_out/export_bundle.json cargo run --bin export_verify -- --db demo_witness.db --bundle demo_out/export_bundle.json # should FAIL ``` 下一步：对于真实的 RTSP 流或本地 V4L2 设备，请参阅下面的数据接入部分。 ## 文档 * 规范说明： * `spec/invariants.md` * `spec/event_contract.md` * `spec/threat_model.md` * `kernel/architecture.md` * 其他文档应链接到规范说明，而不是重复其内容。 * 主机妥协限制记录在 `docs/root_paradox.md` 中。 * 防篡改感知的原理说明在 `docs/why_witnessing_matters.md` 中。 * 有关规范的保管库机密性策略和规则集标识符指南，请参阅 `kernel/architecture.md`。 * 贡献指南在 `CONTRIBUTING.md` 中。 * 安全策略在 `SECURITY.md` 中。 * 发行说明在 `CHANGELOG.md` 中。 ## 固件 设备固件位于 `firmware/` 下。 - **Canary Vision (ESP32-C3 + Grove Vision AI V2)**: `firmware/projects/canary-vision/` PlatformIO 项目，用于发布保护隐私的语义事件和 Home Assistant MQTT Discovery。 ## 发布关卡（v1 标签） 在标记任何 v1 版本之前，必须对 Home Assistant + Frigate MQTT 管道进行端到端验证。请完成 `docs/integrations/home-assistant-frigate-mqtt.md` 中的 v1 验证清单，并确保在运行中的完整技术栈上执行 `integrations/ha_frigate_mqtt/verify_pipeline.sh` 成功并以退出代码 `0` 结束。在验证通过之前，v1 标签将被阻止发布。 ## 设备公钥位置 设备 Ed25519 **验证密钥**本地存储在见证数据库的 `device_metadata.public_key`（行 `id = 1`）中。像 `log_verify` 这样的外部验证工具 默认从数据库读取此公钥，或者按照 `log_verify_README.md` 中的说明通过 `--public-key` / `--public-key-file` 接受显式密钥。 ## 破窗策略管理 破窗 CLI 将仲裁策略存储在内核数据库中，以便 `break_glass authorize` 可以根据持久化的受托人名册来评估批准情况。使用 `break_glass policy` 子命令管理策略： ``` DEVICE_KEY_SEED=devkey:your-seed \ cargo run --bin break_glass -- policy set \ --threshold 2 \ --trustee alice:0123... \ --trustee bob:4567... \ --db witness.db DEVICE_KEY_SEED=devkey:your-seed \ cargo run --bin break_glass -- policy show --db witness.db ``` 受托人条目使用 `id:HEX_PUBLIC_KEY` 格式，其中公钥是 十六进制编码的 32 字节 Ed25519 验证密钥。 ## 破窗解封工作流 首先确保已存储了仲裁策略（`break_glass policy set`）。然后创建 解锁请求，收集受托人的批准，并在解封之前授权该请求。授权步骤会记录 一张回执（授予或拒绝），并通过 `--output-token` 签发一个敏感令牌文件。使用该令牌来解封 信封。解封命令会将明文信封写入 `--output-dir` （默认：`vault/unsealed`），以便操作员能够找到恢复的有效载荷， 而不是假设 CLI 缺少解封路径。 ``` cargo run --bin break_glass -- request \ --envelope \ --purpose "incident response" \ --ruleset-id ruleset:v0.3.0 cargo run --bin break_glass -- approve \ --request-hash \ --trustee alice \ --signing-key /path/to/alice.signing.key \ --output alice.approval DEVICE_KEY_SEED=devkey:your-seed \ cargo run --bin break_glass -- authorize \ --envelope \ --purpose "incident response" \ --approvals alice.approval,bob.approval \ --db witness.db \ --ruleset-id ruleset:v0.3.0 \ --output-token /path/to/break_glass.token ``` ``` cargo run --bin break_glass -- unseal \ --envelope \ --token /path/to/break_glass.token \ --db witness.db \ --ruleset-id ruleset:v0.3.0 \ --vault-path vault/envelopes \ --output-dir vault/unsealed ``` ## 事件导出 使用顺序导出工具将带有粗略时间段和批量事件的本地产物写出 （无精确时间戳或身份选择器）。 ``` DEVICE_KEY_SEED=devkey:your-seed \ cargo run --bin export_events -- --db-path witness.db --output witness_export.json ``` `export_events` 会发出包含批量分桶的单个 JSON 产物，除非 被 CLI 标志覆盖，否则将应用默认的抖动和批处理。 ## Home Assistant 集成 SecuraCV 通过两种连接方式与 Home Assistant 集成： 1. **HTTP API**（必需）- 连接到 Privacy Witness Kernel，用于保管库存储、事件查询和管理 2. **MQTT**（可选）- 接收来自 Canary 设备的实时更新，实现多传输路径的弹性 该集成呈现语义见证事件、哈希链完整性和设备健康状况——绝不包含原始视频或身份数据。隐私优先设计。 ### 要求 - Home Assistant 2024.4.1 或更高版本 - SecuraCV Privacy Witness Kernel 正在运行（Docker、插件或独立运行） - MQTT broker（可选，用于 Canary 设备的实时更新） ### HACS 安装（推荐） 1. 在您的 Home Assistant 实例中打开 HACS 2. 点击右上角的三点菜单 → **Custom repositories** 3. 将 `https://github.com/kmay89/securaCV` 作为 **Integration** 添加 4. 搜索 "SecuraCV" 并安装 5. 重启 Home Assistant 6. 前往 **Settings → Devices & Services → Add Integration → SecuraCV** 7. 输入内核 URL 和 API token（必需） 8. 可选启用 MQTT 以发现 Canary 设备 ### 手动安装 将 `custom_components/securacv/` 复制到您的 Home Assistant 的 `config/custom_components/` 目录中并重启。 ### 多传输路径弹性架构 Canary 设备被设计为在被禁用前，不惜一切代价将见证数据传输出去。该集成展示了哪些通信路径处于活动状态： | 传输方式 | 描述 | 传感器 | |-----------|-------------|--------| | WiFi AP | 直接接入点模式 | `binary_sensor.securacv_{device}_transport_wifi_ap` | | WiFi Station | 连接到家庭网络 | `binary_sensor.securacv_{device}_transport_wifi_sta` | | MQTT | 基于 Broker 的消息传递 | `binary_sensor.securacv_{device}_transport_mqtt` | | 蓝牙 | BLE 直连 | `binary_sensor.securacv_{device}_transport_ble` | | Mesh (Opera) | Ed25519 认证的点对点网络 | `binary_sensor.securacv_{device}_mesh_connected` | | Chirp | 社区警报网络（临时 ID） | `binary_sensor.securacv_{device}_chirp_active` | | LoRa | 远程无线电（未来） | - | | SCQCS | 音频对讲警报（未来） | - | ### 篡改检测 每种篡改类型都有其专属的二进制传感器，用于针对性的自动化： | 威胁 | 传感器 | 触发条件 | |--------|--------|---------| | 断电 | `binary_sensor.securacv_{device}_tamper_power_loss` | 检测到电源被移除 / 电压不足 | | SD 卡被移除 | `binary_sensor.securacv_{device}_tamper_sd_remove` | 存储卡被物理移除 | | SD 卡错误 | `binary_sensor.securacv_{device}_tamper_sd_error` | 存储写入失败 | | GPS 干扰 | `binary_sensor.securacv_{device}_tamper_gps_jamming` | GPS 信号丢失或受到干扰 | | 移动 | `binary_sensor.securacv_{device}_tamper_motion` | 检测到意外移动 | | 外壳 | `binary_sensor.securacv_{device}_tamper_enclosure` | 物理外壳被打开 | | GPIO | `binary_sensor.securacv_{device}_tamper_gpio` | 篡改检测引脚被触发 | | 看门狗 | `binary_sensor.securacv_{device}_tamper_watchdog` | 系统挂起 / 超时 | | 重启 | `binary_sensor.securacv_{device}_tamper_unexpected_reboot` | 意外的设备重启 | | 内存 | `binary_sensor.securacv_{device}_tamper_memory_critical` | 严重内存耗尽 | ### 创建的实体 **内核传感器（基于 HTTP）：** - `sensor.securacv_last_event` - 来自内核的最新事件 - `binary_sensor.securacv_kernel_online` - 内核连接状态 **Canary 传感器（基于 MQTT，启用时）：** - `sensor.securacv_{device}_witness_count` - 总见证记录数 - `sensor.securacv_{device}_chain_length` - 哈希链长度 - `sensor.securacv_{device}_last_event` - 最后一次事件类型 + 时间戳 - `sensor.securacv_{device}_health_status` - 设备健康状况 - `sensor.securacv_{device}_gps_fix` - GPS 定位状态 **Canary 二进制传感器：** - `binary_sensor.securacv_{device}_online` - 设备连接状态 (MQTT LWT) - `binary_sensor.securacv_{device}_chain_valid` - 哈希链完整性 - `binary_sensor.securacv_{device}_tamper` - 通用篡改检测 - 以及各个单独的篡改类型传感器（见上文） - 以及传输健康状况传感器（见上文） **服务：** - `securacv.export_chain` - 导出防篡改见证链 - `securacv.verify_chain` - 证 Ed25519 签名和哈希链完整性 ### MQTT Discovery（自动传感器） PWK 支持 **Home Assistant MQTT Discovery** 以自动创建实体： ``` # Add-on 配置 mqtt_publish: enabled: true host: "core-mosquitto" ``` 这会为每个区域自动创建这些实体： - `sensor.pwk__events` - 事件计数 (state_class: total_increasing) - `binary_sensor.pwk__motion` - 运动状态（10 分钟后自动关闭） - `sensor.pwk_last_event` - 带有完整属性的最新事件 功能： - **QoS 1** 保证可靠的消息传递 - **Last Will Testament** 用于可用性跟踪 - **Retained messages** 确保 HA 重启后的状态持久性 ### Frigate 集成 对于使用 Frigate NVR 的用户： ``` mode: "frigate" frigate: mqtt_host: "core-mosquitto" mqtt_username: "" # Optional MQTT auth mqtt_password: "" min_confidence: 0.5 mqtt_publish: enabled: true # Enable HA Discovery ``` 完整指南请参阅 `docs/homeassistant_setup.md`，针对 Frigate 的特定设置请参阅 `docs/frigate_integration.md`。 如需查看 Home Assistant + Frigate MQTT 的综合演练，请参阅 `docs/integrations/home-assistant-frigate-mqtt.md`。 ## RTSP 摄像头设置 ### 真实摄像头的快速开始 1. 安装 RTSP 依赖项（GStreamer 或 FFmpeg）： # Ubuntu/Debian sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-good gstreamer1.0-plugins-bad libseccomp-dev # Ubuntu/Debian (FFmpeg backend) sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libseccomp-dev 2. 编译并启用 RTSP 支持： cargo build --release --features rtsp-gstreamer 或 cargo build --release --features rtsp-ffmpeg 3. 配置您的摄像头（创建 `witness.toml`）： [rtsp] url = "rtsp://admin:password@192.168.1.100:554/stream1" target_fps = 10 width = 640 height = 480 backend = "auto" # auto, gstreamer, ffmpeg [zones] module_zone_id = "zone:front_door" 4. 运行（与您编译的后端功能相匹配）： export DEVICE_KEY_SEED=$(openssl rand -hex 32) WITNESS_CONFIG=witness.toml cargo run --release --features rtsp-gstreamer --bin witnessd 有关摄像头的 URL 模式、故障排除和高级配置，请参见 `docs/rtsp_setup.md`。 ### RTSP 架构 `witnessd` 使用 GStreamer 或 FFmpeg 在内存中解码 RTSP 流。在 `RtspConfig` 中配置 RTSP URL， 内核将生成 `RawFrame` 值而不会将帧写入磁盘。时间粗化和不可逆特征哈希在 捕获时发生，并且 `RtspSource::is_healthy()` 负责报告流的健康状况。 GStreamer 支持由 `rtsp-gstreamer` 功能控制；FFmpeg 支持由 `rtsp-ffmpeg` 功能控制。 `stub://` 方案仅保留用于测试和本地开发中的合成数据源；发布版本会拒绝它。遗留的 `StubFrameSource` 辅助程序仅在测试或启用 `stub-frame-source` 功能时编译。 在 `witness.toml` 中通过 `rtsp.backend = "auto|gstreamer|ffmpeg"` 或 `WITNESS_RTSP_BACKEND` 环境变量来选择后端。当两种功能都可用时，`auto` 优先选择 GStreamer。 ## V4L2 摄像头设置（USB / 本地设备） ### 本地设备的快速开始 1. 编译并启用 V4L2 支持： cargo build --release --features ingest-v4l2 2. 配置您的设备（创建 `witness.toml`）： [ingest] backend = "v4l2" [v4l2] device = "/dev/video0" target_fps = 10 width = 640 height = 480 [zones] module_zone_id = "zone:front_door" 3. 运行： export DEVICE_KEY_SEED=$(openssl rand -hex 32) WITNESS_CONFIG=witness.toml cargo run --release --features ingest-v4l2 --bin witnessd 更多详情，包括桩设备和不变量约束，请参见 `docs/v4l2_setup.md`。 ### V4L2 架构 `witnessd` 直接从本地 `/dev/video*` 设备在内存中捕获帧，并生成带有粗化时间桶和不可逆特征哈希的 `RawFrame` 值。 V4L2 后端从不将原始帧写入磁盘，也从不通过网络公开它们。 ## Tract (ONNX) 后端 Tract 后端支持使用本地 ONNX 推理进行对象检测。它由功能门控（`backend-tract`），并且需要**本地**模型文件。它仅支持 RTSP 或 V4L2 数据接入，因为它们提供了明确的宽/高。 ### 推荐的微型模型 (Apache-2.0) 以确定性方式下载 ONNX Model Zoo 中的 `ssdlite_mobilenet_v2_12` 模型： ``` mkdir -p vendor/models curl -L \ https://github.com/onnx/models/raw/main/vision/object_detection_segmentation/ssdlite_mobilenet_v2/model/ssdlite_mobilenet_v2_12.onnx \ -o vendor/models/ssdlite_mobilenet_v2_12.onnx echo "ad6303f1ca2c3dcc0d86a87c36892be9b97b02a0105faa5cc3cfae79a2b11a31 vendor/models/ssdlite_mobilenet_v2_12.onnx" | sha256sum -c - ``` ### 必需的配置/CLI 字段 **配置 (witness.toml):** ``` [detect] backend = "tract" tract_model = "vendor/models/ssdlite_mobilenet_v2_12.onnx" [rtsp] width = 320 height = 320 # 或者，对于 V4L2： [v4l2] width = 320 height = 320 ``` **环境变量覆盖：** - `WITNESS_DETECT_BACKEND=tract` - `WITNESS_TRACT_MODEL=/absolute/path/to/model.onnx` **输入尺寸要求：** `tract` 期望帧尺寸与模型输入相匹配。请将 `rtsp.width/height` 或 `v4l2.width/height` 设置为模型输入尺寸。 **阈值：** tract 后端目前使用固定的 `0.5` 置信度阈值（暂不支持 CLI/配置覆盖）。 ## ESP32-S3 摄像头设置（HTTP MJPEG/JPEG 或 UDP RTP） ### ESP32-S3 快速开始 1. 编译并启用 ESP32-S3 支持： cargo build --release --features ingest-esp32 2. 配置您的 ESP32-S3 视频流（创建 `witness.toml`）： [ingest] backend = "esp32" [esp32] url = "http://192.168.1.50:81/stream" target_fps = 10 [zones] module_zone_id = "zone:front_door" 3. 运行： export DEVICE_KEY_SEED=$(openssl rand -hex 32) WITNESS_CONFIG=witness.toml cargo run --release --features ingest-esp32 --bin witnessd 有关支持的 ESP32-S3 URL 模式和 RTP 预期，请参见 `docs/esp32_s3_setup.md`。 ## 容器部署 有关构建和运行带有 RTSP 配置且仅暴露 Event API 的容器化 `witnessd` 产物，请参阅 `docs/container.md`。

标签：CNCF毕业项目, CSV导出, CVE, Ed25519, ESP32-S3, Frigate, HACS, Home Assistant, JSONLines, NVR, Rust, 事件自动删除, 可信计算, 可视化界面, 哈希链, 固件开发, 多方授权, 子域名变形, 安全摄像头, 家庭自动化, 密码学, 开源硬件, 手动系统调用, 数字签名, 智能安防, 智能家居, 本地存储, 物联网, 监控, 网络安全, 网络流量审计, 视频处理, 语义事件, 请求拦截, 边缘计算, 防篡改日志, 隐私保护, 零信任