matzalazar/vigilant

 # Vigilant — 取证视频处理套件     **Vigilant** 是一套专业的取证视频处理套件，可将专有 CCTV 格式转换为开放标准，并提供本地 AI 辅助视觉分析和自动化的转换监管链。专为需要可追溯性和独立验证的调查人员、取证分析师和安全专业人员设计。 ## 系统架构 ``` graph LR subgraph IN["Input"] MFS[.mfs CCTV] PDF[PDF] end subgraph CONV["Conversion"] HB[HandBrake] RES[Rescue] HASH[SHA-256] META[Metadata] end subgraph AI["AI Analysis (optional)"] FR[Frames] YO[YOLO] LL[LLaVA] RP[Report] end subgraph OUT["Output"] MP4[.mp4] SHA[.sha256] JSON[.json] MD[.md] end MFS --> HB HB -->|ok| HASH HB -->|fail| RES --> HASH HASH --> META HASH --> MP4 --> SHA META --> JSON PDF -.-> JSON MP4 -.-> FR --> YO --> LL --> RP --> MD ``` ## 关键特性 ### 1. 取证转换（核心项目） **解决的问题：** 专有 CCTV 系统生成封闭格式的文件（目前为 `.mfs`），无法在标准播放器中播放。这使得以下操作变得困难： - 在取证设备上查看证据 - 长期保存 - 在法律诉讼中展示 - 与外部专家共享 **Vigilant 的解决方案：** ``` flowchart LR A[.mfs Video
Proprietary] --> B{HandBrakeCLI} B -->|Success| C[Clean
Conversion] B -->|Failure| D[Rescue Mode] D --> E{Stream
Analysis} E --> F[FFmpeg
Extraction] F --> G[Partial
Recovery] C --> H[SHA-256] G --> H H --> I[.mp4 + .sha256
+ .integrity.json] ``` **转换功能：** - **多工具：** 以 HandBrakeCLI 为主，FFmpeg 为备用 - **救援管道：** 自动恢复损坏或部分损坏的文件 - **取证完整性：** 自动计算源文件和目标文件的 SHA-256 - **完整元数据：** 记录工具、预设、命令、版本、时间戳和大小 - **可重现性：** 容器元数据标准化并记录命令，以减少不同运行间的差异 - **批量处理：** 完整目录的大批量转换 **每次转换生成的文件：** ``` input/ └── footage_2024_01_15.mfs output/ ├── footage_2024_01_15.mp4 ├── footage_2024_01_15.mp4.sha256 └── footage_2024_01_15.mp4.integrity.json ``` **取证元数据示例（`*.integrity.json`）：** ``` { "integrity_version": "1.0", "timestamp": "2026-01-31T14:23:45.123456+00:00", "source": { "path": "/input/footage_2024_01_15.mfs", "filename": "footage_2024_01_15.mfs", "sha256": "a3f5e9c2d1b8f4e6a9c0d5e8f1a4b7c2...", "size_bytes": 1258291200 }, "converted": { "path": "/output/footage_2024_01_15.mp4", "filename": "footage_2024_01_15.mp4", "sha256": "d9e3f6a0b5c8d2e7f1a6b9c4d8e3f7a2...", "size_bytes": 987654321 }, "conversion": { "tool": "HandBrake+ffmpeg normalize", "preset": "Fast 1080p30", "command": "HandBrakeCLI -i /input/footage_2024_01_15.mfs -o /output/footage_2024_01_15.mp4 --preset 'Fast 1080p30' && ffmpeg -y -i /output/footage_2024_01_15.mp4 -map_metadata -1 -map_chapters -1 -fflags +bitexact -flags:v +bitexact -flags:a +bitexact -c copy /output/footage_2024_01_15_normalized.mp4", "tool_version": "HandBrakeCLI 1.6.1; ffmpeg 6.1", "rescue_mode": false } } ``` ### 2. AI 驱动的视觉分析（辅助功能） **解决的问题：** 人工查看数小时的 CCTV 视频是不切实际的。需要辅助手段来快速识别相关帧。 **Vigilant 的解决方案：** ``` flowchart TD A[Video .mp4] --> B[Frame Extraction N segs + scene] B --> C{Prefilter} C -->|YOLO| D[Object detection: person, vehicle] C -->|LLaVA quick| E[Fast keyword matching] D --> F{Match?} E --> F F -->|Yes| G[Deep analysis with LLaVA detailed] F -->|No| H[Discard frame] G --> I[Legal-format report with Mistral] I --> J[Markdown + screenshots] ``` **分析功能：** - **本地离线：** Ollama 在您的机器上运行模型，无需云端数据传输 - **两种预过滤模式：** YOLO（快速，常见物体）或 LLaVA（灵活，任意标准） - **运动检测（仅限 YOLO，可选）：** 为动态物体提供附加上下文（当 `ai.filter_backend=yolo` 且启用了运动检测时） - **深度分析：** 对相关帧进行详细的取证描述 - **法律格式报告（AI 辅助）：** 由 Mistral 生成的专业格式 - **语义嵌入（可选）：** 基于相似性的过滤以减少误报（当 `ai.use_embeddings=true` 时） **重要提示：** AI 分析是一种**调查辅助工具**。结果必须由合格的专业人员审查。它不能取代人工判断。 ### 3. 监管链 - 源文件和转换文件的 SHA-256 哈希 - 标准格式的 `.sha256` 文件（兼容 `sha256sum`，可选注释/标签行） - 完整的取证元数据（`.integrity.json`） - 命令和工具版本记录在元数据中 - UTC 时间戳和转换日志 - 传输后完整性验证 ### 4. PDF 处理 - 从 PDF 报告中提取元数据 - 结构化 JSON 转换 - 准备用于与视频证据进行人工关联 ## 技术范围 - **输入**: `.mfs` (CCTV), `.pdf` (报告) - **输出**: `.mp4`, `.json` (元数据), markdown 报告 + 截图 - **完整性**: SHA-256, 转换元数据, UTC 时间戳 - **AI**: LLaVA 用于分析, Mistral 用于报告, 可选 YOLO 预过滤 - **模式**: 离线, 可重现, 无云依赖 ## 系统要求 ### 核心软件 - Python 3.8 或更高版本 - `ffmpeg` (视频处理) - `HandBrakeCLI` (主要转换) - [Ollama](https://ollama.com/) (本地 AI 引擎，仅 `vigilant analyze` 需要) ### 可选依赖 - `ultralytics` + YOLO 模型 (快速预过滤) - Docker + Docker Compose (容器化部署) ### 推荐的 AI 模型 ``` ollama pull llava:13b # Visual analysis ollama pull mistral:latest # Report generation ollama pull nomic-embed-text # Semantic embeddings (optional) ``` ## 快速安装 ### 本地安装 ``` # 克隆 repository git clone https://github.com/matzalazar/vigilant.git cd vigilant # 安装 core dependencies pip install -r requirements.txt pip install -e . # 验证 installation vigilant --version # 验证 external dependencies vigilant --check ``` ### 自动化设置 ``` # 使用 virtual environment 和 YOLO 完整安装 ./scripts/setup.sh --with-yolo --download-yolo # 仅 CPU (无 GPU) ./scripts/setup.sh --with-yolo --cpu-only ``` ### Docker (生产环境推荐) ``` # 启动 services (Vigilant + Ollama) docker compose up -d # 检查 status docker compose ps # (可选) 转换 evidence .mfs -> .mp4 (如果 data/mfs/ 中有文件) docker exec vigilant-app vigilant convert # 运行 analysis docker exec vigilant-app vigilant analyze --prompt "person with vest" ``` 完整文档：[`docs/en/12_docker_quickstart.md`](docs/en/12_docker_quickstart.md) ## 配置 ### 环境变量 (`.env`) ``` # 输入/输出 paths (必需) VIGILANT_INPUT_DIR="/mnt/evidence/raw" VIGILANT_OUTPUT_DIR="/mnt/evidence/processed" # YOLO model (可选) VIGILANT_YOLO_MODEL="/path/to/yolov8n.pt" # Logging level (可选, 默认: INFO) VIGILANT_LOG_LEVEL="DEBUG" # AI Analysis (可选) VIGILANT_OLLAMA_URL="http://localhost:11434" VIGILANT_ANALYSIS_MODEL="llava:13b" ``` ### YAML 文件 - `config/default.yaml`: 默认配置（已版本控制） - `config/local.yaml`: 本地覆盖（被 git 忽略） **优先级**: `default.yaml` → `local.yaml` → 环境变量 完整文档：[`docs/en/06_configuration_guide.md`](docs/en/06_configuration_guide.md) ## 用法 ### 视频转换 ``` # 转换输入目录中的所有 .mfs 文件 # (自动 rescue: 默认启用) vigilant convert # (可选) 禁用自动 rescue vigilant convert --no-rescue # 输出: .mp4 文件 + .sha256 + .integrity.json ``` ### PDF 报告解析 ``` # 从 PDF 报告提取 metadata 到 JSON vigilant parse # 输出: 包含结构化 metadata 的 .json 文件 ``` ### AI 视觉分析 ``` # 搜索特定 object/person vigilant analyze --prompt "Dark vehicle in motion" # 分析特定文件 vigilant analyze --video evidence.mp4 --prompt "Person with red backpack" # 输出: # - 报告: data/reports/md/analysis__.md # - 截图: data/reports/imgs/ # 注意: "Legal report (AI)" 部分已清理; 如果被丢弃，报告会说明。 ``` ## 架构 ``` vigilant/ ├── core/ # Configuration, logging, forensic integrity ├── converters/ # HandBrake, FFmpeg, rescue pipeline ├── parsers/ # PDF metadata extraction └── intelligence/ # AI analysis (frame extraction, LLaVA, YOLO) ``` **处理流程**: 1. 转换 (`.mfs` → `.mp4` 并附带监管链) 2. 帧提取 (间隔/场景/混合) 3. 可选预过滤 (YOLO 或快速 LLaVA) 4. 深度分析 (详细 LLaVA) 5. 报告生成 (Mistral 法律格式) 完整文档：[`docs/en/03_technical_architecture.md`](docs/en/03_technical_architecture.md) ## 测试 ``` # 安装 development dependencies pip install -e ".[dev]" # 运行完整 test suite pytest -v # 包含 coverage pytest -v --cov=vigilant --cov-report=term-missing # 仅快速测试 pytest -v -m "not slow" ``` 完整文档：[`docs/en/11_tests.md`](docs/en/11_tests.md) ## 文档 ### 技术文档 (`docs/`) - [00_index.md](docs/en/00_index.md) - 文档索引 - [01_installation_and_configuration.md](docs/en/01_installation_and_configuration.md) - 详细设置 - [02_chain_of_custody.md](docs/en/02_chain_of_custody.md) - 取证完整性与监管链 - [03_technical_architecture.md](docs/en/03_technical_architecture.md) - 系统设计 - [06_configuration_guide.md](docs/en/06_configuration_guide.md) - 配置参考 - [10_troubleshooting.md](docs/en/10_troubleshooting.md) - 故障排除 - [11_tests.md](docs/en/11_tests.md) - 运行测试 - [12_docker_quickstart.md](docs/en/12_docker_quickstart.md) - Docker 部署 ## 用例 **取证调查** - 将专有 CCTV 证据转换为标准格式 - 在数小时的录像中快速搜索人员/车辆 - 生成带有 SHA-256 和可追溯性的法律格式报告（AI 辅助） **安全分析** - 回顾性事件审查 - 可疑模式识别 - 与 PDF 报告的人工事件关联 **归档与保存** - 将专有格式迁移至开放标准 - 长期完整性验证 - 用于可追溯性的取证元数据 ## 非目标 本项目**不**包括： - 图形用户界面 (GUI) - 实时流媒体 - 云端处理 - 超出文件级别的专有系统集成 - 自动决策（这是一个调查辅助工具） ## 专业服务与支持 如果您的机构需要在生产环境中部署 **Vigilant**，我提供专业服务，包括： - **设置与实施：** 配置物理隔离的取证工作站以及针对本地 AI 的硬件优化。 - **技术培训：** 监管链工作流程、SHA-256 完整性管理以及用于证据分析的视觉模型使用。 - **流程咨询：** 使套件适应特定的调查工作流程。 通过 [LinkedIn](https://www.linkedin.com/in/matzalazar/) 或 [matzalazar.com](https://matzalazar.com) 联系我。 ## 许可证 本项目根据 GPL-3.0 授权。详见 `LICENSE` 文件。 **关于取证使用的说明**：本软件是一种调查辅助工具。结果必须由合格的专业人员审查。它不能取代人工判断或实体的监管链。 ## 作者 **Matías L. Zalazar** ## 其他资源 - [完整文档](docs/en/00_index.md) - [问题与支持](https://github.com/matzalazar/vigilant/issues) - [示例](examples/)

标签：AI风险缓解, CCTV监控, HandBrake, LLaVA, MFS格式, Python, SHA-256, YOLO, 司法鉴定, 域渗透, 子域名变形, 完整性校验, 开源情报工具, 数字取证, 数据恢复, 无后门, 本地AI分析, 电子数据取证, 监控格式转换, 监控视频处理, 目标检测, 离线取证工具, 自动化脚本, 视频分析, 视频取证, 证据固定, 证据链, 请求拦截, 逆向工具