Hemanth19i/SecureRAG

# SecureRAG [](https://github.com/Hemanth19i/SecureRAG/actions/workflows/ci.yml) ## 🎥 观看 SecureRAG 实战演示 [观看演示视频](https://youtu.be/RVEu-tW_dhg?si=Ztjuzv8Vyn11BSsC) **AI 驱动的威胁情报与 SIEM 平台。** 支持接入安全日志，利用 RAG 检索相关证据，并自动提取 IOC、进行关联分析、映射到 MITRE ATT&CK、构建攻击时间线与关系图、通过审计追踪管理安全案件、利用威胁情报丰富指标信息、衡量检索质量，以及展示实时告警。 ## 1. 概述 SecureRAG 将原始、非结构化的安全日志转化为结构化、可供分析师直接使用的情报。后端采用 Flask 运行基于 SQLite + ChromaDB 的接入/分析 pipeline，并暴露受 JWT 保护的 REST API；前端使用 React 19 + TypeScript (Vite) 构建的单页应用提供了 SOC 控制台 —— 包括仪表盘分析、AI 调查、IOC 探索与丰富、MITRE 视图、时间线、攻击图、带有审计追踪的案件管理、RAG 评估页面以及实时告警流。 LLM 分析由 **Google Gemini** 提供，并带有自动的**基于规则的降级方案**，因此即使在未配置 API key 的情况下，产品也能优雅降级。 ## 2. 核心功能 以下每项功能都有真实的页面、endpoint 和子系统作为支撑（参见 [§8 API 概述](#8-api-overview) 和 [docs/ARCHITECTURE_DIAGRAMS.md](docs/ARCHITECTURE_DIAGRAMS.md))。 **调查与分析** - **AI 调查** — 提出自然语言问题；获得基于证据的回答（严重性、威胁、建议），以及用于回答该问题的 IOC、关联分析、MITRE 映射和时间线 (`POST /query`，Gemini + 基于规则的降级方案)。 - **日志接入** — 分块 → 向量化 → ChromaDB + SQLite 持久化 (`POST /upload`)。 - **重复上传防范** — 基于文件 SHA-256 哈希的去重 (重新上传返回 `409`)。 - **IOC 提取** — IP、哈希、CVE、域名、电子邮件、URL、IPv6。 - **IOC 探索器** — 带有风险评分和分析师洞察的跨日志关联 (`POST /correlate`)。 - **IOC 丰富** — 通过 AbuseIPDB 获取 IP 信誉，缓存优先并带有 TTL (`GET /enrich`)。 - **MITRE ATT&CK 映射** — 技术/战术映射 + 杀伤链构建。 - **时间线分析** — 带有严重性的按时间顺序排列的威胁事件。 - **攻击图** — 针对单次上传的节点/边关系图 (`GET /attack-graph`)。 **运营** - **案件管理** — 创建/列出/更新案件，管理生命周期状态，以及线索化的笔记。 - **审计追踪** — 仅追加的案件历史记录（创建 / 状态 / 分配 / 笔记 / 关联证据），随案件详情一同返回。 - **实时监控** — 告警生成、确认生命周期、基于游标的增量轮询、严重性/已确认状态过滤，以及实时日志接入 (`POST /monitor/feed`)。 - **报告** — 生成安全事件报告 (`POST /report`)。 **衡量与分析** - **RAG 评估** — 专用的纯检索路径 (`POST /retrieval/eval`)，展示各阶段（向量化 / 搜索 / 总计）的延迟以及带有相似度/距离的排序分块，同时提供离线的 Recall@K / MRR 基准测试。 - **仪表盘分析** — KPI 读数，以及基于真实数据的分布图（IOC 类型、告警类型），数据来源于 `GET /stats`、`GET /alerts` 和 `POST /correlate`。 **平台** - **身份验证与 RBAC** — JWT access/refresh token，ADMIN / ANALYST 角色，登录频率限制，以及严格的密钥校验机制。 ## 3. 架构 ``` React 19 + TS SPA (Vite, App.tsx) ── dev: :3000 dashboard | AI investigation | ingest | investigations | IOC explorer IOC enrichment | MITRE | timeline | attack graph | cases | reports live monitoring | RAG evaluation | settings | /api proxy (dev) · HTTPS + JWT (Bearer) v Flask API (api/) ── :5000 auth_bp (/auth) | api_bp | JWT | CORS | rate limit | +---------------------+----------------------+ v v v intelligence/ rag/ external APIs ingest pipeline chunker | embedder Gemini (LLM) IOC | MITRE | (all-MiniLM-L6-v2) AbuseIPDB (TI) timeline | vectorstore (ChromaDB) correlator | alerts | cases | v SQLite (WAL) SIEM store log_chunks | extracted_iocs | mappings | mitre | timeline | cases | notes | audit | enrichment | alerts ``` **接入 pipeline** (通过 `ingest_text` 被 `/upload` 和 `/monitor/feed` 共享)： ``` text -> chunk -> embed -> ChromaDB -> SQLite{IOCs, MITRE, timeline} -> correlate -> alerts ``` 完整的 Mermaid 图表集合（系统上下文、组件、数据流、数据模型、部署、告警/认证状态机）：**[docs/ARCHITECTURE_DIAGRAMS.md](docs/ARCHITECTURE_DIAGRAMS.md)**。 ## 4. 技术栈 - **后端：** Python 3.11，Flask (blueprints)，Flask-JWT-Extended，SQLite (WAL)，ChromaDB，SentenceTransformers (`all-MiniLM-L6-v2`)，Google Gemini。 - **前端：** React 19，TypeScript，Vite，Tailwind CSS + shadcn/ui，React Router，React Flow (`@xyflow/react`，攻击图)，Recharts (仪表盘图表)，three.js (主视觉画布)。 - **基础设施：** Waitress/gunicorn WSGI，Docker + Docker Compose，nginx (静态 SPA)；通过 GitHub Actions 进行 CI (ruff + pytest)。 ## 5. 截图 请根据 [docs/screenshots/README.md](docs/screenshots/README.md) 中的清单进行截图， 并将 PNG 文件提交到 `docs/screenshots/` 目录。 | 视图 | 截图 | |---|---| | 仪表盘 |  | | AI 调查 |  | | IOC 探索器 |  | | MITRE 映射 |  | | 时间线 |  | | 攻击图 |  | | 案件管理 |  | | 实时监控 |  | | RAG 评估 |  | ## 6. 安装说明 ### 前置条件 - Python **3.10+** (基于 3.11 开发) - Node **18+** (基于 20 开发) ### 后端 ``` cd server python -m venv venv # Windows: venv\Scripts\activate | macOS/Linux: source venv/bin/activate pip install -r requirements.txt cp .env.example .env # 编辑 .env：设置一个 STRONG JWT_SECRET_KEY (>=32 字符) 并 (可选地) GEMINI_API_KEY。 # python -c "import secrets; print(secrets.token_urlsafe(48))" python app.py # serves http://localhost:5000 ``` 首次启动时会创建一个 `admin` 用户。如果未设置 `DEFAULT_ADMIN_PASSWORD`（或密码强度较弱），系统将生成一个强随机密码并**在日志中仅打印一次** — 请妥善保存。 ### 前端 ``` cd frontend npm install npm run dev # serves http://localhost:3000 ``` Vite 开发服务器将 `/api` 代理到 `http://localhost:5000`，因此 SPA 以同源方式与后端通信 — 在开发环境中无需配置 `VITE_API_BASE_URL` 和 CORS。(`frontend/.env.local` 默认为空。) ## 7. 本地开发 - **运行顺序：** 先启动后端 (`:5000`)，再启动前端 (`:3000`)。 - **API 基础地址：** 在开发环境中，应用使用同源的 `/api` 代理 (`vite.config.ts`)；仅在针对远程 API 源的生产构建中设置 `VITE_API_BASE_URL` (参见 [DEPLOYMENT.md](DEPLOYMENT.md))。 - **构建 / 类型检查：** `npm run build` (先运行 `tsc -b`，再运行 `vite build`)。 ### 环境变量 后端 (`server/.env`)： | 变量 | 必填 | 默认值 | 描述 | |---|---|---|---| | `JWT_SECRET_KEY` | **是** | — | JWT 签名密钥；必须 ≥32 个字符且不能是已知的占位符（否则应用将拒绝启动）。 | | `GEMINI_API_KEY` | 否 | — | Google Gemini 密钥。如果未设置，则使用基于规则的分析器。 | | `ABUSEIPDB_API_KEY` | 否 | — | 启用 IP 信誉丰富；如果未设置，将优雅降级。 | | `DEFAULT_ADMIN_PASSWORD` | 否 | (随机) | 初始管理员密码。弱密码将被忽略并被随机密码替换。 | | `CHROMA_DB_PATH` | 否 | `./chroma_store` | ChromaDB 持久化目录。 | | `FLASK_PORT` | 否 | `5000` | 后端端口。 | | `FLASK_DEBUG` | 否 | `false` | 启用 Werkzeug 调试（切勿用于生产环境）。 | | `LOG_LEVEL` | 否 | `INFO` | 日志级别。 | | `MAX_UPLOAD_MB` | 否 | `50` | 最大请求体大小 (MB)。 | | `CORS_ORIGINS` | 否 | `http://localhost:5173` | 逗号分隔的允许的前端源（用于直接/生产环境访问；开发代理为同源）。 | | `SQLITE_TIMEOUT_SECONDS` | 否 | `30` | SQLite 忙碌/锁定等待时间。 | | `MAX_QUERY_CHARS` | 否 | `10000` | 最大 `/query` 长度。 | | `MAX_TOP_K` | 否 | `50` | 最大检索 `top_k`。 | | `MAX_FEED_CHARS` | 否 | `1000000` | 最大 `/monitor/feed` 内容长度。 | | `MAX_SOURCE_CHARS` | 否 | `200` | 最大 `/monitor/feed` 源长度。 | | `ENRICH_TTL_SECONDS` | 否 | `86400` | 威胁情报缓存 TTL (成功时)。 | | `ENRICH_NEG_TTL_SECONDS` | 否 | `3600` | 威胁情报负缓存 TTL。 | | `LOGIN_RATE_LIMIT` | 否 | `10` | 每个时间窗口的最大登录尝试次数。 | | `LOGIN_RATE_WINDOW` | 否 | `60` | 登录频率限制时间窗口 (秒)。 | 前端 (`frontend/.env.local`，仅用于生产构建)： | 变量 | 默认值 | 描述 | |---|---|---| | `VITE_API_BASE_URL` | (空 → `/api` 代理) | 用于生产构建的后端基础 URL，例如 `https://api.your-domain.com`。 | ## 8. API 概述 除 `POST /auth/login` 外，所有 endpoint 都需要 `Authorization: Bearer `。角色：**A** = ADMIN，**N** = ANALYST。 ### 认证 | 方法 | 路径 | 角色 | 请求体 → 响应 | |---|---|---|---| | POST | `/auth/login` | 公开 | `{username, password}` → `{access_token, refresh_token, role}` | | POST | `/auth/refresh` | refresh token | → `{access_token}` | | POST | `/auth/register` | A | `{username, password, role}` → `201` | ### 核心功能 | 方法 | 路径 | 角色 | 备注 | |---|---|---|---| | POST | `/upload` | A | multipart `file` → `{message, chunks_stored}`；重复时返回 `409` | | POST | `/query` | A·N | `{query, top_k?}` → 分析结果 + iocs + correlation + mitre + timeline + citations | | POST | `/retrieval/eval` | A·N | `{query, top_k?}` → 排序后的分块 + 各阶段延迟 (仅限检索) | | GET | `/stats` | A·N | → `{readouts, evidence}` | | POST | `/report` | A·N | `{analysis}` → `{report}` | | GET | `/debug/chunks` | A | 调试：列出已存储的分块 | ### 情报 | 方法 | 路径 | 角色 | 备注 | |---|---|---|---| | POST | `/correlate` | A·N | → 关联摘要 + 分析师洞察 | | POST | `/mitre-map` | A·N | `{text}` → MITRE 技术 + 杀伤链 | | POST | `/timeline` | A·N | `{text}` → 时间线事件 | | GET | `/attack-graph?upload_id=` | A·N | → `{nodes, edges}`；未知上传返回 `404` | | GET | `/enrich?value=` | A·N | → 威胁情报记录 (缓存优先) | ### 案件 | 方法 | 路径 | 角色 | |---|---|---| | POST | `/cases` | A·N | | GET | `/cases` | A·N | | GET | `/cases/` | A·N (返回字段 + 笔记 + 审计追踪) | | PATCH | `/cases/` | A·N | | POST | `/cases//notes` | A·N | | GET | `/cases//notes` | A·N | | POST | `/casesid>/link-evidence` | A·N | ### 告警与监控 | 方法 | 路径 | 角色 | 备注 | |---|---|---|---| | GET | `/alerts?since=&limit=` | A·N | 游标轮询 → `{alerts, total, cursor}` | | PATCH | `/alerts/` | A·N | `{acknowledged: true}` | | POST | `/monitor/feed` | A | `{source, content}` → `{upload_id, chunks_stored, alerts_created}` | `POST /query` 的响应结构已通过契约测试锁定 — 参见 [server/tests/CONTRACT.md](server/tests/CONTRACT.md)。 ## 9. 演示流程 (5 分钟) 示例攻击日志和完整的约 10 分钟演示脚本位于 [`demo/`](demo/) ([demo/DEMO_SCRIPT.md](demo/DEMO_SCRIPT.md)) 中。精简流程如下： 1. **登录** 为 `admin` (密码来自首次启动日志或 `DEFAULT_ADMIN_PASSWORD`)。 2. **接入日志** — 从 `demo/sample_logs/` 上传示例；pipeline 会自动运行 (重新上传返回 `409`)。 3. **AI 调查** — 询问 *“是否发生了暴力破解攻击，是否成功了？”*；查看 AI 分析、IOC、关联分析、MITRE 映射和时间线。 4. **IOC 探索器** — 检查关联的指标；**丰富**一个公网 IP。 5. **MITRE / 时间线 / 攻击图** — 探索技术、序列和关系。 6. **案件管理** — 将调查结果保存为案件；设置状态、添加笔记、查看审计追踪。 7. **实时监控** — 确认告警；按严重性过滤；观察倒计时。 8. **RAG 评估** — 运行查询以衡量向量化/搜索延迟并检查排序后的分块；查看离线 Recall@K / MRR 基准测试。 ## 10. 已知局限性 当前构建版本存在的客观限制： - **桌面优先的 UI** — 固定最大宽度的布局并带有侧边栏；未针对移动端进行优化。 - **演示规模数据** — 分布是真实的但数据量很小 (单节点、单租户)。 - **管理员开通的用户** — 无自助注册功能 (`/auth/register` 仅限 ADMIN 使用) 且**没有密码重置**工作流。 - **Recall@K / MRR 仅限离线** — 由 `server/eval/recall_eval.py` 针对带有标签的数据集进行衡量。实时的 `/retrieval/eval` 返回延迟和排序后的分块；其 `recall_at_k` 字段是一个预留接口，始终为 `null`。 - **历史分析功能有限** — 没有时间序列/趋势图表 (在演示规模下，接入数据具有突发性，渲染出的图表会显得稀疏且产生误导)。 - **没有针对单次上传的 MITRE/时间线读取 endpoint** — `/mitre-map` 和 `/timeline` 分析提交的文本；单次上传的存储分析结果无法单独读取。 - **没有上传管理功能** — 无法通过 API 单独列出/删除上传的文件。 - **单节点 SQLite** (WAL + 忙碌超时)，基于**轮询**的实时交付 (~10秒)，**内存级频率限制器** (基于单进程)，以及大于 500 kB 的 JS bundle (无代码分割)。`VIEWER` 角色已保留，但尚未在 endpoint 中启用。 ## 11. 路线图 从早期评估中延期的项目（务实的未来工作）： - 上传管理（查看/删除上传文件）。 - 仪表盘上的“RAG 健康”摘要卡片（基于延迟）。 - 基于真实数据的**实时 Recall@K** 评分（响应接口已预留）。 - 针对单次上传的 MITRE/时间线读取 endpoint。 - 更丰富的报告导出（超越纯文本格式）。 - 通过 SSE/WebSocket 进行推送交付（游标可直接映射到 `Last-Event-ID`）。 - 启用只读的 `VIEWER` 角色；基于 Redis 的频率限制；可选的 Postgres 后端；路由级别的代码分割。 ## 测试 后端测试位于 `server/tests/` 中 (pytest)。它们**完全离线**运行 — 向量化模型和 Gemini 都被 stub/mock，测试使用临时的 SQLite + Chroma 存储，因此您真实的 `securerag.db` / `chroma_store` 绝不会受到影响。 ``` cd server pip install -r requirements-dev.txt pytest # unit + contract + API tests (integration excluded by default) ruff check . # lint pytest -m integration # opt-in end-to-end: REAL embedder + Chroma + /query ``` 在 repo 根目录下运行：`make test`，`make lint`，`make test-integration`。 - **契约测试** (`tests/test_contract_query.py`) 锁定了 `/query` 的响应结构 — 详见 [server/tests/CONTRACT.md](server/tests/CONTRACT.md) 文档。 - **CI** (`.github/workflows/ci.yml`) 在每次 push 和 PR 时运行 ruff + pytest (不包括集成测试) (Python 3.11)，并带有 pip 缓存。 ### 检索评估 (离线 RAG 指标) 检索功能通过带有标签的测试集 ([`server/eval/`](server/eval/)) 进行衡量：包含 **30 条 SOC 日志语料库**和 **10 个查询到目标的映射对**。相关性是精确匹配的 — 只有当检索到的排名为 *r* 的分块 ID 是标记的目标时，该查询才算命中。 指标基于**真实的**技术栈 (SentenceTransformer `all-MiniLM-L6-v2` + ChromaDB) 进行计算。 ``` cd server python eval/recall_eval.py # semantic baseline python eval/recall_eval.py --mode hybrid # semantic + BM25 fused via RRF python eval/recall_eval.py --mode rerank # hybrid + cross-encoder rerank ``` **结果 (语料库 = 30，查询 = 10)：** | 指标 | 语义检索 | 混合检索 (BM25+RRF) | 混合检索 + 重排序 | |---|---|---|---| | Recall@1 | 0.80 | 0.80 | **0.90** | | Recall@3 | 1.00 | 1.00 | 1.00 | | Recall@5 | 1.00 | 1.00 | 1.00 | | MRR | 0.90 | 0.90 | **0.95** | *客观解读：* 在此数据集上，仅使用 BM25+RRF 融合没有任何改变；是交叉编码器重排序器将 Recall@1 从 0.80 提升到了 0.90，将 MRR 从 0.90 提升到了 0.95。在当前语料库规模下，Recall@3/@5 已达到饱和，因此 Recall@1 和 MRR 是有意义的信号。这些离线数据将展示在 RAG 评估页面上（清楚地标记为基准测试，而非实时数据）。 ## 安全说明 - 密钥仅存在于 `server/.env` 中 (已被 gitignore)。切勿提交真实的密钥。 - 如果没有强大的 `JWT_SECRET_KEY`，应用将拒绝启动并失效。 - 默认运行时为 Flask/Werkzeug 开发服务器；对于生产环境，应使用 WSGI 服务器 (waitress/gunicorn) 作为前端并置于 TLS 之后。请参阅 [SECURITY.md](SECURITY.md) 和 [DEPLOYMENT.md](DEPLOYMENT.md)。 ## 12. 许可证 专有 — 内部项目（未提交 `LICENSE` 文件；在任何公开发布之前请适当更新）。 *由 Hemanth A R 构建。*

标签：DLL 劫持, Flask, RAG, React, Syscalls, 大语言模型, 威胁情报, 安全运营, 开发者工具, 扫描框架, 自动化攻击, 请求拦截, 逆向工具