levvedrov/Voidwatch

# Voidwatch 端点安全监控系统。一个轻量级 agent 在受监控的机器上运行，每 5 秒收集一次进程和网络遥测数据，并将其发送到后端；后端使用混合规则引擎 + ML 分类器对每个进程进行评分。威胁会显示在桌面仪表板中。 ## 架构 ``` Agent (Python) └─ collects process + network telemetry every 5s └─ POST /telemetry → Backend Backend (FastAPI + SQLite) └─ rule engine (MITRE-mapped scoring) └─ RandomForest classifier └─ alert deduplication (10-min window) └─ REST API → Dashboard Dashboard (Electron) └─ starts backend + agent automatically on launch └─ Dashboard, Processes, MITRE ATT&CK views ``` ## 环境要求 - Python 3.11+ - Node.js 18+ ``` pip install -r requirements.txt cd dashboard && npm install ``` ## 运行 ``` cd dashboard npm start ``` 仪表板会自动启动后端（端口 8000）和 agent。首次启动时，请预留约 3 秒的时间用于 ML 模型训练。 ## 身份验证（可选） 在运行后端的机器和所有运行 agent 的机器上设置 `VOIDWATCH_API_KEY`： ``` # Windows $env:VOIDWATCH_API_KEY = "your-secret-key" # Linux / macOS export VOIDWATCH_API_KEY="your-secret-key" ``` 如果未设置该变量，API 将接受所有请求（适用于本地/受信任的网络）。 ## 风险评分 每个进程使用以下四个组成部分进行 0–150 分的评分： | 组成部分 | 描述 | |---|---| | 基础分 | 规则引擎 —— 映射 MITRE 的检测项（PowerShell 滥用、LOLBins、持久化等） | | 关联加成 | 行为链 —— 例如：Office 应用程序生成带有网络活动的编码 PowerShell | | 置信度修正值 | 根据指标强度和进程上下文向上/向下调整分数 | | 上下文修正值 | 父进程类型和执行路径 | 当分数 ≥ 25 时会生成警报。风险等级：LOW / MEDIUM / HIGH / CRITICAL / SEVERE。 ## ML 分类器 在合成的带标签进程数据上训练的 RandomForest。用于补充（而非替代）规则引擎。每次训练运行时，控制台都会打印精确率/召回率/F1 指标。 若要手动重新训练： ``` cd backend python -c "from classifier import classifier; classifier.train()" ``` ## API 端点 如果设置了 `VOIDWATCH_API_KEY`，所有端点都需要 `X-API-Key` 请求头。 | 方法 | 路径 | 描述 | |---|---|---| | POST | `/telemetry` | 接收 agent 遥测批次数据 | | GET | `/agents` | 列出已注册的 agent | | GET | `/processes` | 列出已收集的进程 | | GET | `/alerts` | 列出生成的警报 | | GET | `/timeline` | 警报事件时间线 | ## 项目结构 ``` agent/ main.py — entry point, collect loop telemetry.py — TelemetryEvent dataclass process_collector.py network_collector.py sender.py — HTTP POST to backend config.py — SERVER_URL, API_KEY, AGENT_ID backend/ main.py — FastAPI app entry point api.py — REST endpoints, auth, deduplication scoring.py — rule engine + correlation engine classifier.py — RandomForest classifier + metrics features.py — feature extraction database.py — SQLAlchemy models + SQLite models.py — Pydantic schemas dashboard/ main.js — Electron entry, spawns backend + agent app.js — router, window controls, status bar pages/ dashboard.js — overview + high-risk processes processes.js — full process list mitre.js — MITRE ATT&CK technique mapping ```

标签：AMSI绕过, Apex, API密钥认证, AV绕过, Cloudflare, DAST, EDR, Electron, FastAPI, GNU通用公共许可证, IP 地址批量处理, MITM代理, MITRE ATT&CK, Node.js, OpenCanary, Python, SecOps, SQLite, 云安全架构, 云计算, 人工智能安全, 合规性, 命令控制, 威胁检测, 安全运营, 异常检测, 恶意软件分析, 扫描框架, 数据包嗅探, 数据采集, 无后门, 无线安全, 机器学习, 桌面应用, 知识库安全, 端点安全, 网络安全, 网络遥测, 脆弱性评估, 补丁管理, 规则引擎, 逆向工具, 随机森林, 隐私保护