Mohhudib/hybrid-rsentry

# 🛡️ 混合R-Sentry ## 概述 Hybrid R-Sentry 是一个**混合勒索软件检测系统**，它结合了多种检测层和一个AI驱动的分析器，用于在Linux终端上实时识别、分类并自动遏制勒索软件威胁。 与基于特征码的解决方案不同，Hybrid R-Sentry 使用**行为分析**来在未知和零日勒索软件变种造成重大损害之前将其捕获。 ## 功能特性 ### 检测引擎 - **诱饵文件** — 战略性布置的诱饵文件（`AAA_*.txt`），如果被任何进程触及，将立即触发**严重**警报。 - **香农熵分析** — 监控文件熵变化，以检测正在进行中的加密活动。 - **进程谱系评分** — 对可疑的进程祖先链进行评分，以识别恶意的父子关系关系。 - **马尔可夫链重定位** — 根据观察到的文件系统访问模式，自适应地将诱饵文件移动到预测的高风险目录。 - **综合威胁评分** — 将熵和谱系信号融合为一个加权威胁分数，以进行准确的严重性分类。 - **误报抑制** — 全面的白名单系统（`agent/exceptions.py`），涵盖浏览器、包管理器、系统路径、压缩包格式和媒体文件，以消除实时Linux系统上的噪声。 ### 自动遏制流程 当检测到**严重**威胁时，系统会自动执行多阶段遏制序列： 1. **SIGSTOP** — 立即冻结恶意进程。 2. **证据采集** — 收集进程元数据、打开的文件和网络连接信息。 3. **iptables DROP** — 阻止该进程的所有出站网络流量。 4. **SIGKILL** — 永久终止进程。 ### AI威胁分析师 - 使用大语言模型进行自动化威胁分类。 - 分析每个**高/严重/中等**级别的事件，并返回结构化JSON：威胁类型、技术、行为摘要、风险等级和建议。 - 两个独立的API密钥 — 一个用于实时事件分析，一个用于按需警报分析 — 以防止速率限制阻塞。 - 系统健康检查：分析最近的活动模式并报告终端整体状态。 - 自动确认被分类为良性或低风险的警报。 ### 实时仪表板 - 基于三个独立Redis发布/订阅通道的实时WebSocket数据流。 - 6个实时统计卡片（事件、按严重性分类的警报、诱饵触发、被遏制的主机）。 - 带有诱饵区域指示器、熵条和活动实时闪烁的文件系统树。 - 带有过程名称和严重性筛选器的战术响应日志。 - 警报管理，支持单个警报确认和批量“全部确认”按钮。 - 主机风险面板，带有径向风险评分仪表，在每次确认后更新。 - AI分析师页面，带有加载中旋转图标、错误卡片和4分钟的分析结果持久化。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Linux Endpoint │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ Watchdog │ │ Entropy │ │ Lineage │ │ │ │ Monitor │──▶│ Engine │──▶│ Scorer │ │ │ └──────────────┘ └──────────────┘ └────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌────────────────────┐ │ │ │ Markov │ │ Auto-Containment │ │ │ │ Repositioner │ │ SIGSTOP→iptables │ │ │ └──────────────┘ └────────────────────┘ │ └─────────────────────────────┬───────────────────────────────┘ │ HTTP POST /api/events ▼ ┌─────────────────────────────────────────────────────────────┐ │ FastAPI Backend │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ Events │ │ Alerts │ │ Hosts │ │ │ │ Router │ │ Router │ │ Router │ │ │ └──────┬───────┘ └──────────────┘ └────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ Celery │ │ PostgreSQL │ │ Redis │ │ │ │ Workers │ │ (Events, │ │ (Broker + │ │ │ │ (AI, ACK, │ │ Alerts, │ │ 3 WS chans) │ │ │ │ WS push) │ │ Hosts) │ │ │ │ │ └──────────────┘ └──────────────┘ └────────┬───────┘ │ └─────────────────────────────────────────────────┼───────────┘ │ WebSocket ▼ ┌─────────────────────────────────────────────────────────────┐ │ React Dashboard │ │ Live alerts · AI analysis · Host risk │ └─────────────────────────────────────────────────────────────┘ ``` ## 技术栈 | 层级 | 技术 | |---|---| | 代理 | Python 3.13, watchdog, psutil, networkx | | 后端 | FastAPI, SQLAlchemy (异步), PostgreSQL, asyncpg | | 任务队列 | Celery, Redis | | AI | LLM API (兼容OpenAI的端点) | | 前端 | React 18, Tailwind CSS, Recharts, WebSocket | | 基础设施 | Docker Compose (PostgreSQL + Redis) | ## 快速入门 ### 前置条件 - Python 3.13 - Node.js 18+ - Docker & Docker Compose ### 安装说明 **1. 克隆仓库** ``` git clone https://github.com/Mohhudib/hybrid-rsentry.git cd hybrid-rsentry ``` **2. 设置环境变量** ``` cp .env.example .env # 编辑 .env 文件，填入你的数据库 URL、Redis URL 和 AI API key ``` **3. 启动基础设施** ``` docker compose up -d ``` **4. 设置Python环境** ``` python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` **5. 启动后端** ``` uvicorn backend.main:app --reload ``` **6. 启动Celery工作者** ``` PYTHONPATH=. celery -A backend.workers.tasks:celery_app worker --loglevel=info ``` **7. 启动代理** ``` # 使用 sudo -E 来保留环境变量（包括 WATCH_PATH） set -a && source .env && set +a sudo -E venv/bin/python -m agent.monitor ``` **8. 启动前端** ``` cd frontend npm install npm start ``` 打开 [http://localhost:3000](http://localhost:3000) 访问仪表板。 ## 环境变量 | 变量 | 描述 | |---|---| | `POSTGRES_PASSWORD` | PostgreSQL密码 — 用于Docker Compose和`DATABASE_URL` | | `DATABASE_URL` | PostgreSQL连接字符串 (asyncpg) — **必需**，无默认值 | | `REDIS_URL` | Redis连接字符串 | | `NVIDIA_API_KEY` | 用于实时事件AI分析的API密钥 | | `NVIDIA_API_KEY_ALERTS` | 用于按需警报AI分析的API密钥 | | `HOST_ID` | 此终端的标识符 | | `WATCH_PATH` | 要监控的目录 — **必须位于项目文件夹之外** | | `CANARY_COUNT` | 要放置的诱饵文件数量（默认：15） | | `BACKEND_URL` | 代理报告的后端URL | | `SECRET_KEY` | 密钥（生产环境需32+字符） | ## 警报严重级别 | 严重性 | 触发条件 | 自动操作 | |---|---|---| | 严重 | 诱饵文件被触及 | 立即自动遏制 | | 高 | 熵值飙升 + 高谱系评分 | AI分析 + 警报 | | 中等 | 仅熵值飙升 | AI分析 + 警报 | | 低 | 心跳 / 系统事件 | 仅记录日志 | ## 项目结构 ``` hybrid-rsentry/ ├── agent/ # Endpoint monitoring agent │ ├── monitor.py # Main watchdog orchestrator │ ├── graph.py # Filesystem graph + canary placement │ ├── entropy.py # Shannon entropy engine │ ├── lineage.py # Process lineage scorer │ ├── adaptive.py # Markov chain repositioner │ ├── containment.py # Auto-containment pipeline │ ├── exceptions.py # Whitelist rules — suppresses false positives │ └── client.py # Backend HTTP client ├── backend/ │ ├── main.py # FastAPI app entry point │ ├── models/ # SQLAlchemy ORM + Pydantic schemas │ ├── routers/ # API route handlers │ ├── services/ # AI analyst service │ └── workers/ # Celery task definitions └── frontend/ ├── src/ │ ├── pages/ # Dashboard pages │ ├── components/ # Reusable UI components │ ├── hooks/ # WebSocket hook │ └── api/ # Axios API client └── public/ ``` ## 检测流程 ``` File system event │ ▼ Is it a canary file? ──YES──▶ CRITICAL alert → Auto-containment │ NO ▼ Is path/process whitelisted? ──YES──▶ Skip (suppress false positive) │ NO ▼ Entropy delta > threshold? │ ├──YES──▶ Lineage score >= 40? ──YES──▶ COMBINED_ALERT (CRITICAL/HIGH) │ └──NO───▶ ENTROPY_SPIKE (MEDIUM) │ └──NO───▶ Lineage score >= 40? ──YES──▶ PROCESS_ANOMALY (HIGH) └──NO───▶ Skip (low signal) │ ▼ AI analyst classifies threat → publishes result to dashboard ``` ## 文档 完整的项目文档可在 [GitHub Wiki](https://github.com/Mohhudib/hybrid-rsentry/wiki) 中找到，涵盖： - [架构详解](https://github.com/Mohhudib/hybrid-rsentry/wiki/Architecture) - [检测引擎内部机制](https://github.com/Mohhudib/hybrid-rsentry/wiki/Detection-Engine) - [自动遏制流程](https://github.com/Mohhudib/hybrid-rsentry/wiki/Auto-Containment) - [AI威胁分析师](https://github.com/Mohhudib/hybrid-rsentry/wiki/AI-Threat-Analyst) - [安装与设置](https://github.com/Mohhudib/hybrid-rsentry/wiki/Installation-and-Setup) - [API参考](https://github.com/Mohhudib/hybrid-rsentry/wiki/API-Reference) - [已知问题与修复](https://github.com/Mohhudib/hybrid-rsentry/wiki/Known-Issues-and-Fixes) ## 安全性 该仓库于2026年5月进行了安全审计。发现并修复了以下问题： | 修复 | 详情 | |---|---| | 移除了`python-jose`依赖 | 存在CVE-2024-33664和CVE-2024-33663（算法混淆攻击）；从未被导入 | | 移除了硬编码的数据库密码回退 | `database.py` 以前如果`DATABASE_URL`未设置，会回退到一个已知的开发密码 — 现在会引发明确错误 | | 参数化Docker Compose凭证 | `docker-compose.yml`现在从环境变量读取`${POSTGRES_PASSWORD}`，而不是嵌入明文密码 | **GitHub Dependabot警报（26个）：** 全部位于`react-scripts`的构建工具链中（`jest`、`webpack-dev-server`、`workbox`）。它们不存在于生产环境的React构建中，并且无法在不完全替换Create React App的情况下修复。它们不代表运行时风险。 如需报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 本项目采用MIT许可证。