9to5ninja-projects/sentinel

# Sentinel v0.3 — 进程与端点威胁监控器 一款零臃肿的端点威胁监控器：枚举正在运行的进程、服务、计划任务、自启动项和 WMI 订阅。结合 VirusTotal 进行交叉引用，使用 YARA 规则进行扫描，实时监控文件系统以发现新威胁 —— 所有这些都由一个能为您节省 VT 配额的本地启发式引擎支持。 **仪表板是一个 Claude.ai artifact。** 将 `sentinel-dashboard.jsx` 粘贴到 Claude 中，Claude 会将其渲染为一个连接到您正在运行的 Sentinel 实例的交互式应用程序。Claude 同时也是 AI 解释层 —— 将威胁数据粘贴到对话中，它会告诉您这些检测结果的实际含义。 ## 架构 ``` ┌─────────────────┐ ┌──────────────┐ ┌───────────────┐ │ ProcessScanner │ │ FileWatcher │ │ YARA Engine │ │ (psutil) │ │ (watchdog) │ │ (yara-python) │ └────────┬────────┘ └──────┬───────┘ └───────┬───────┘ │ │ │ ┌────────┴───────────────────┴────────────────────┘ │ HeuristicEngine │ │ (offline static analysis — gates VT calls) │ └────────────────────────┬────────────────────────┘ │ ┌────────┴─────────┐ ▼ ▼ ┌──────────┐ ┌─────────────┐ │ REST API │ │ WebSocket │ ← real-time push │ (hydrate)│ │ /ws/events │ └──────────┘ └─────────────┘ ``` 额外的扫描器 (v0.3)： - **ServiceScanner** — systemctl (Linux), SCM (Windows), launchd plist (macOS) - **ScheduledTaskScanner** — crontab + systemd timers (Linux), schtasks XML (Windows) - **AutostartScanner** — XDG autostart + shell profiles (Linux), Registry Run keys + startup folders (Windows) - **WMISubscriptionScanner** — event filters, consumers, bindings (Windows only) ## 功能特性 ### 进程与服务扫描 - 通过 psutil / systemctl / SCM 枚举所有正在运行的进程和服务 - 计算可执行文件的 SHA-256 哈希值并与 VirusTotal 交叉比对 - 显示 CPU、内存、网络连接、父进程、命令行 - 结果缓存在 SQLite 中（经 HMAC 签名 —— 防篡改） ### 启发式引擎 (离线，无需 API) - 分段 Shannon 熵 (PE/ELF) - 导入表异常评分（可疑 API 组合：注入、凭证窃取等） - 卡方字节频率 vs 编译代码分布 - PE/ELF 结构分析（节名、大小比率、子系统标志） - 评分范围 0.0–1.0；控制 VT 查询 —— 只有真正可疑的文件才会消耗 API 配额 ### 文件监控器 - 通过 watchdog 监控 Downloads、Desktop、/tmp 和持久化目录 - 通过扩展名和魔数检测新增/修改的可执行文件（可捕获重命名的二进制文件） - 检测到后立即进行 YARA 扫描 + VT 查询 ### YARA 扫描 - 热重载规则：将 `.yar` 文件放入 `yara_rules/`，点击重载 - 内置 13 条规则涵盖：加壳器、挖矿程序、反向 Shell、进程注入、凭证窃取、Web Shell、勒索软件、持久化、C2 - 匹配去重：每个二进制文件针对每条规则仅报告一次 ### 持久化与自启动扫描 - Linux: XDG autostart, shell profile 注入检测 (.bashrc, .zshrc, etc.) - Windows: Registry Run keys (HKCU/HKLM), startup folders, schtasks XML, WMI event subscriptions - 命令异常检测：18+ 种模式 (curl|bash, base64 -d, -EncodedCommand, /dev/tcp, etc.) ### WebSocket 实时事件 - 位于 `/ws/events` 的单通道传输类型化 JSON 事件 - 事件类型：`process_scan`, `service_scan`, `task_scan`, `autostart_scan`, `file_alert`, `yara_hit`, `vt_result`, `status_update` - REST 端点用于初始状态加载；WebSocket 用于实时更新 - 基于会话的 Bearer token 认证（启动时打印） - HMAC 签名的 SQLite 缓存；关键文件的自我完整性监控 ## 仪表板 — Claude.ai Artifact 工作流 仪表板 (`sentinel-dashboard.jsx`) 被设计为一个 **Claude.ai artifact**： 1. 在运行 Sentinel 的同一台机器上的浏览器中打开 [claude.ai](https://claude.ai) 2. 开始新对话 → 点击 artifact/canvas 图标 3. 粘贴 `sentinel-dashboard.jsx` 的全部内容 4. Claude 将其渲染为一个交互式 React 应用 5. 仪表板自动连接到 `localhost:8000` **为什么采用这种方式？** Claude 既是 UI 也是 AI 解释层。当您看到 YARA 命中或可疑进程时，可以直接询问 Claude：*"`UPX_Packed_Binary` 是什么意思？这是威胁吗？"* —— 并根据屏幕上的实际数据获得上下文相关的答案。 **不同的主机？** 在浏览器控制台中设置： ``` window.SENTINEL_HOST = "192.168.1.10:8000" ``` 然后重新加载 artifact。 ## 快速开始 ### Linux / WSL2 ``` git clone https://github.com/9to5ninja-projects/sentinel cd sentinel # 安装依赖 python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 设置 YARA 规则 mkdir -p yara_rules cp sentinel_base.yar yara_rules/ # 运行 bash scripts/run_sentinel.sh # 可选：VirusTotal 集成（免费版：4 次/分钟，500 次/天） VT_API_KEY=your_key bash scripts/run_sentinel.sh ``` ### Windows ``` git clone https://github.com/9to5ninja-projects/sentinel cd sentinel scripts\setup_windows.bat scripts\run_sentinel.bat ``` ### 运行测试 ``` # 必须先运行 Sentinel python3 tests/test_sentinel.py # 启用 VT 集成： VT_API_KEY=your_key python3 tests/test_sentinel.py ``` ## 配置 | 变量 | 默认值 | 描述 | |---|---|---| | `VT_API_KEY` | (无) | VirusTotal API key | | `VT_API_KEY_FILE` | (无) | 包含 VT key 的文件路径（推荐 —— 不在环境变量中） | | `SENTINEL_CACHE_DB` | `sentinel_cache.db` | SQLite 数据库路径 | | `SENTINEL_SCAN_INTERVAL` | `5` | 进程扫描间隔秒数 | | `SENTINEL_SERVICE_INTERVAL` | `60` | 服务扫描间隔秒数 | | `SENTINEL_TASK_INTERVAL` | `60` | 计划任务扫描间隔秒数 | | `SENTINEL_AUTOSTART_INTERVAL` | `60` | 自启动项扫描间隔秒数 | | `SENTINEL_WMI_INTERVAL` | `120` | WMI 扫描间隔秒数 (Windows only) | | `VT_RATE_PER_MIN` | `4` | 每分钟 VT 请求数 | | `VT_RATE_PER_DAY` | `500` | 每天 VT 请求数 | | `SENTINEL_YARA_DIR` | `yara_rules` | `.yar` 规则文件的目录 | | `SENTINEL_WATCH_DIRS` | 平台默认值 | 逗号分隔的要监控的目录 | | `SENTINEL_HEURISTIC_VT_THRESHOLD` | `0.3` | 触发 VT 查询的最小启发式分数 | | `SENTINEL_HEURISTIC_GATE_VT` | `false` | 根据启发式分数控制 VT 调用 | | `SENTINEL_WS_TOKEN` | (随机) | 固定的 WebSocket 认证 token（默认：每次会话随机） | | `SENTINEL_HMAC_KEY` | `.sentinel_hmac_key` | 用于缓存完整性的 HMAC key 文件路径 | ## API 参考 | 端点 | 方法 | 认证 | 描述 | |---|---|---|---| | `/api/auth/token` | GET | None (loopback only) | 获取会话 Bearer token | | `/ws/events` | WS | Token | 实时事件流 | | `/api/processes` | GET | Bearer | 所有进程及威胁数据 | | `/api/services` | GET | Bearer | 所有服务及威胁数据 | | `/api/tasks` | GET | Bearer | 计划任务 | | `/api/autostart` | GET | Bearer | 自启动项 | | `/api/wmi` | GET | Bearer | WMI event subscriptions (Windows) | | `/api/threats` | GET | Bearer | 所有类别的已标记项 | | `/api/alerts` | GET | Bearer | 最近的文件监控警报 | | `/api/yara/hits` | GET | Bearer | 最近的 YARA 匹配 | | `/api/status` | GET | Bearer | 系统信息、扫描器状态、速率限制器 | | `/api/yara/reload` | POST | Bearer | 从 `yara_rules/` 重新编译 YARA 规则 | | `/api/scan/{sha256}` | POST | Bearer | 强制查询已知哈希的 VT | ## 扩展 YARA 规则 将 `.yar` 或 `.yara` 文件放入 `yara_rules/` 目录，然后： ``` curl -X POST -H "Authorization: Bearer " http://localhost:8000/api/yara/reload ``` 或者点击仪表板中的重载按钮。 推荐的社区规则集： - [Yara-Rules/rules](https://github.com/Yara-Rules/rules) - [Neo23x0/signature-base](https://github.com/Neo23x0/signature-base) - [elastic/protections-artifacts](https://github.com/elastic/protections-artifacts) ## 局限性 - **无文件恶意软件**：磁盘上没有二进制文件可供哈希或扫描 - **零日漏洞**：尚未出现在 VirusTotal 或 YARA 签名中 - **Rootkits**：隐藏在进程枚举之外，不会出现在 psutil 中 - **多态二进制文件**：哈希值随副本变化，导致 VT 缓存失效 - **WMI 扫描**：仅限 Windows（需要 PowerShell，可能需要提升权限） - **注册表自启动**：仅限 Windows（HKLM keys 需要管理员权限） - **schtasks XML 解析**：在某些 Windows 版本上，多文档 XML 输出的回退处理尚不完善 对于遵循合理卫生习惯的开发者来说，这个工具加上 Defender/ClamAV 可以覆盖现实的威胁面，而且没有臃肿。 ## 许可证 MIT — 见 [LICENSE](LICENSE)

标签：Claude仪表盘, DNS 反向解析, EDR工具, HTTP工具, Psutil, Python安全工具, VirusTotal集成, Watchdog, WebSocket通信, WMI事件订阅, YARA规则扫描, 启发式分析引擎, 安全可视化, 实时文件监控, 持久化检查, 本地静态分析, 端点威胁检测, 系统态势感知, 网络信息收集, 网络安全审计, 自启动项管理, 计划任务分析, 逆向工具