ayushkasare-beep/LogHawk-SIEM

# LogHawk — 安全日志分析平台 这是一个 SIEM (安全信息与事件管理) 作品集项目，能够摄取原始的 Linux 身份验证日志，将其解析为结构化事件，运行 8 个基于特征的威胁检测器，生成可用于分诊的告警，并提供完整的事件响应工作流。 本项目旨在展示在 SOC 工作流、日志解析架构、威胁检测设计以及全栈安全应用开发方面的实际知识。 ## 目录 1. [项目概述](#1-project-overview) 2. [功能](#2-features) 3. [截图](#3-screenshots) 4. [架构](#4-architecture) 5. [技术栈](#5-technology-stack) 6. [安装指南](#6-installation-guide) 7. [配置](#7-configuration) 8. [使用说明](#8-usage) 9. [检测能力](#9-detection-capabilities) 10. [事件响应工作流](#10-incident-response-workflow) 11. [目录结构](#11-folder-structure) 12. [API 参考](#12-api-reference) 13. [未来改进](#13-future-improvements) 14. [简历描述](#14-resume-description) ## 1. 项目概述 LogHawk 模拟了安全运营中心的核心数据 pipeline： - 分析师通过拖放界面上传原始 auth log 文件 - 后端异步调用 Python 子进程，使用编译好的 regex 模式解析日志行 - 解析后的事件被批量插入 MongoDB - 8 个威胁特征检测器扫描事件并生成结构化告警 - 分析师对告警进行分诊，将其升级为事件，添加案例备注，并执行遏制措施（Block IP、Disable User） - 被封禁的资产记录基于用户作用域，并可在专用的封禁资产视图中查看 该应用程序强制执行基于分析师的数据隔离 —— 每一个查询、告警、事件和封禁资产都会根据经过身份验证的用户的 MongoDB ObjectId 进行过滤。 ## 2. 功能 | 功能 | 描述 | |---------|-------------| | **日志摄取** | 拖放上传 `.log` / `.txt` Linux auth log 文件。立即返回 `202 Accepted`；解析在后台运行。 | | **日志浏览器** | 分页、可过滤的解析后日志事件表格。支持按用户名、源 IP、事件类型（`Login`、`Sudo`、`Session`）和状态（`Success`、`Failed`）进行过滤。 | | **威胁检测** | 每次摄取时执行 8 个特征检测器。结果以结构化告警文档的形式呈现。基于分析师的规则开关状态持久化保存在 MongoDB 中。 | | **告警中心** | 完整的告警生命周期：`Open → Investigating → Resolved`。告警详情抽屉显示相关日志事件、源 IP、建议措施和风险评分。 | | **事件响应** | 将告警升级为事件案例。添加带有时间戳的分析师备注，跟踪审计日志时间线，执行遏制措施（Block IP、Disable User、Escalate）。 | | **封禁资产** | 可搜索、分页的视图，显示通过事件遏制封锁的所有 IP 地址。基于用户作用域并带有时间戳。 | | **密码重置** | 基于 token 的密码重置流程，使用 bcrypt 重新哈希，具有 30 分钟的有效期窗口。 | | **设置** | 个人资料管理、密码修改以及实时的 API/数据库健康状态监控。 | ## 3. 截图 截图可以添加到 `assets/` 目录中。建议的命名规范： | 文件 | 页面 | |------|------| | `assets/screenshot-login.png` | 登录和注册界面 | | `assets/screenshot-dashboard.png` | 带有遥测数据统计的主 SOC dashboard | | `assets/screenshot-logs.png` | 日志上传和日志浏览器 | | `assets/screenshot-alerts.png` | 带有分诊抽屉的告警中心 | | `assets/screenshot-detection.png` | 威胁检测规则面板 | | `assets/screenshot-incidents.png` | 带有备注和时间线的事件工作区 | | `assets/screenshot-blocked.png` | 封禁资产表格 | | `assets/screenshot-settings.png` | 设置和个人资料管理 | ## 4. 架构 LogHawk 采用四层架构： ``` ┌──────────────────────────────────────────────────────┐ │ PRESENTATION TIER │ │ React 19 + React Router v7 (Vite) │ └──────────────────────────┬───────────────────────────┘ │ JSON / REST API (Axios + JWT) ┌──────────────────────────▼───────────────────────────┐ │ APPLICATION TIER │ │ Node.js + Express.js REST API Gateway │ │ Multer file handler │ JWT auth middleware │ └──────────┬───────────────────────────────┬───────────┘ │ child_process.execFile │ Mongoose ODM ┌──────────▼───────────┐ ┌─────────────▼────────────┐ │ ANALYSIS TIER │ │ DATA TIER │ │ Python subprocess │ │ MongoDB (Atlas / local) │ │ linux_auth_parser.py│ │ 6 collections │ │ 8 threat detectors │ └───────────────────────────┘ └──────────────────────┘ ``` **日志上传时的数据流：** 1. 前端以 `multipart/form-data` 格式 POST 日志文件 2. Multer 将文件保存到 `backend/uploads/` 3. Controller 返回 `202 Accepted` 并触发后台任务 4. `parserService.js` 通过 `execFile` 调用 Python，并传入 `--file`、`--output json` 和 `--enabled-rules` 参数 5. Python 返回包含解析后事件和检测到的威胁的 JSON blob 6. Node 批量插入 `ParsedLog` 文档并创建 `Alert` 文档 7. 前端轮询文件状态，直到状态变为 `complete` ## 5. 技术栈 | 层级 | 技术 | |-------|-----------| | Frontend | React 19, React Router v7, Axios, Vanilla CSS | | Backend | Node.js, Express.js | | 身份验证 | JSON Web Tokens (JWT), bcryptjs (12 salt rounds) | | 文件处理 | Multer (disk storage) | | 数据库 | MongoDB with Mongoose ODM | | Python Engine | Python 3.10+, `re`, `collections`, `argparse`, `python-dateutil` | | 开发服务器 | Vite 8, Nodemon | ## 6. 安装指南 ### 前置条件 | 要求 | 版本 | |-------------|---------| | Node.js | 18+ | | Python | 3.10+ | | MongoDB | 6+ local instance **或者** MongoDB Atlas cluster | ### 克隆仓库 ``` git clone https://github.com/your-github-username/LogHawk.git cd LogHawk ``` ### 后端设置 ``` cd backend cp .env.example .env # Copy environment template # 编辑 .env 并设置你的 MONGO_URI 和 JWT_SECRET npm install npm run dev # Starts Express on port 5000 ``` ### 前端设置 ``` cd frontend npm install npm run dev # Starts Vite dev server on port 5173 ``` ### Python Engine 设置 ``` cd python-engine pip install -r requirements.txt ``` Python engine 会被后端自动调用。无需手动启动。 ## 7. 配置 所有的后端配置都通过 `backend/.env` 处理。复制 `backend/.env.example` 并填写相关值： ``` # Server PORT=5000 NODE_ENV=development # MongoDB 连接字符串（本地或 Atlas） MONGO_URI=mongodb://127.0.0.1:27017/loghawk # JWT 签名密钥 — 在生产环境中使用长随机字符串 JWT_SECRET=your_jwt_secret_key_here_change_in_production JWT_EXPIRE=7d # 用于 CORS 的 Frontend origin CLIENT_URL=http://localhost:5173 # Python 解释器（如果未设置，则默认为 PATH 中的 'python'） # PYTHON_PATH=python3 # PYTHON_PATH=C:\Users\You\AppData\Local\Programs\Python\python.exe ``` **安全提示：** 切勿将 `.env` 提交到版本控制系统中。它已经被列入 `.gitignore` 中。 ## 8. 使用说明 1. **注册** — 在 `/register` 创建一个分析师账号。密码必须满足复杂性要求（包含大写字母、小写字母、数字、特殊字符）。 2. **上传日志** — 导航至 **Logs**，拖放上传 Linux auth log 文件，或者使用位于 `python-engine/sample_logs/sample_auth.log` 的示例文件。 3. **监控解析** — 文件卡片会显示 `Processing → Complete`。刷新页面或等待状态自动更新。 4. **探索事件** — 使用日志浏览器来搜索、过滤和分页查看解析后的事件。 5. **分诊告警** — 前往 **Alerts** 查看生成的告警。点击任意告警打开详情抽屉：查看相关日志、严重程度、源 IP 和建议的缓解措施。 6. **创建事件** — 在告警抽屉中，点击 **Escalate to Incident**。这将在事件响应工作区中创建一个案例。 7. **管理事件** — 打开事件，分配分析师，添加案例备注，并执行遏制措施（Block IP、Disable User、Escalate）。 8. **审查封禁资产** — 导航至 **Blocked Assets**，查看通过遏制措施隔离的所有 IP 地址。 9. **管理规则** — 前往 **Threat Detection**，查看哪些特征处于激活状态，并开启或关闭单个规则。 ## 9. 检测能力 Python 分析引擎包含 8 个独立的基于特征的检测器。每个都是一个独立的 class，接收解析后的日志事件列表，并返回结构化的威胁对象。 | 检测器 | MITRE ATT&CK | 严重程度 | 触发逻辑 | |----------|-------------|----------|---------------| | **BruteForceDetector** | T1110 | High | 5 分钟内来自同一 IP 的失败身份验证尝试 > 5 次 | | **PasswordSprayDetector** | T1110.003 | High | 10 分钟内来自同一 IP 的针对唯一用户名的攻击 > 3 个 | | **AccountEnumerationDetector** | T1087 | Medium | 来自同一 IP 的无效用户名尝试 > 5 次 | | **AbnormalLoginDetector** | T1078 | Medium | 来自匹配可疑网络块的 IP 的成功登录 | | **PrivilegeEscalationDetector** | T1068 | Critical | 失败的 `su`/`sudo` 命令或未经授权的 sudoers 访问 | | **ReconnaissanceDetector** | T1595 | Medium | 引用已知扫描器路径（`.env`、`wp-admin`、`/etc/passwd`）的日志行 | | **SuspiciousIPDetector** | T1090 | Medium | 源 IP 出现在先前的告警历史记录中 | | **PortScanDetector** | T1046 | Medium | 来自单个 IP 对多个唯一端口的快速连接 | 每个威胁 payload 包括：`type`、`source_ip`、`severity`、`confidence`、`description` 和 `recommendation`。 基于分析师的规则开关通过 `DetectionRule` 集合持久化保存在 MongoDB 中。在解析时，通过将 `--enabled-rules` 作为 JSON 参数传递给 Python 子进程，被禁用的规则将被跳过。 ## 10. 事件响应工作流 ``` Uploaded Log File │ ▼ Python Parser (regex extraction) │ ▼ Threat Detectors (8 signatures) │ ▼ Alert Generated → Alert Center (status: Open) │ ▼ Analyst Triages Alert → status: Investigating │ ▼ Escalate to Incident → Incident Response workspace │ ├─► Add Notes (timestamped, audit trail) ├─► Assign Analyst ├─► Execute Containment: │ • Block IP (creates BlockedAsset record) │ • Disable User Account │ • Escalate to Senior Analyst │ ▼ Resolve Incident → status: Resolved ``` 所有的操作都会记录在事件的审计日志时间线中。 ## 11. 目录结构 ``` LogHawk/ ├── LICENSE ├── README.md ├── DOCUMENTATION.md ├── .gitignore ├── assets/ # Screenshots for README (add manually) │ ├── backend/ # Express.js REST API │ ├── .env.example # Environment variable template │ ├── server.js # Entry point – middleware + route registration │ ├── config/ │ │ └── db.js # MongoDB connection via Mongoose │ ├── controllers/ │ │ ├── authController.js # Register, login, password reset, profile │ │ ├── logController.js # Upload, list, query, delete log files │ │ ├── alertController.js # Alert listing, detail, status updates │ │ ├── incidentController.js # Case management, notes, containment actions │ │ └── detectionRulesController.js # Per-user rule toggle persistence │ ├── middleware/ │ │ ├── auth.js # JWT verification middleware │ │ ├── upload.js # Multer configuration │ │ └── errorHandler.js # Global error handler │ ├── models/ │ │ ├── User.js # Analyst account schema │ │ ├── UploadedFile.js # Uploaded file metadata schema │ │ ├── ParsedLog.js # Individual parsed security event schema │ │ ├── Alert.js # Threat alert schema │ │ ├── Incident.js # Incident case schema │ │ ├── BlockedAsset.js # Blocked IP containment record schema │ │ └── DetectionRule.js # Per-user rule enabled/disabled state │ ├── routes/ │ │ ├── authRoutes.js │ │ ├── logRoutes.js │ │ ├── alertRoutes.js │ │ ├── incidentRoutes.js │ │ └── detectionRulesRoutes.js │ ├── services/ │ │ └── parserService.js # Python subprocess bridge + bulk insert logic │ └── utils/ │ └── sendEmail.js # Email utility (password reset — stub) │ ├── frontend/ # React 19 SPA (Vite) │ └── src/ │ ├── App.jsx # Route definitions │ ├── main.jsx # React root + BrowserRouter │ ├── index.css # Global CSS design tokens │ ├── components/ # Reusable UI components │ │ ├── Sidebar.jsx / .css │ │ ├── Navbar.jsx / .css │ │ ├── LogUpload.jsx / .css │ │ ├── LogExplorer.jsx / .css │ │ ├── FileList.jsx / .css │ │ └── StatCard.jsx / .css │ ├── context/ │ │ └── AuthContext.jsx # JWT session + user state provider │ ├── layouts/ │ │ └── DashboardLayout.jsx │ ├── pages/ │ │ ├── Dashboard.jsx / .css │ │ ├── Logs.jsx / .css │ │ ├── Alerts.jsx / .css │ │ ├── ThreatDetection.jsx / .css │ │ ├── IncidentResponse.jsx / .css │ │ ├── BlockedAssets.jsx / .css │ │ ├── Settings.jsx / .css │ │ ├── Login.jsx │ │ ├── Register.jsx │ │ ├── ForgotPassword.jsx / .css │ │ └── ResetPassword.jsx / .css │ └── services/ │ └── api.js # Axios instance with JWT interceptors │ └── python-engine/ # Log analysis subprocess ├── requirements.txt ├── main.py # Standalone CLI entry point (for manual use) ├── parsers/ │ ├── linux_auth_parser.py # Primary parser — called by backend │ └── log_parser.py # Multi-format parser (architecture reference) ├── detectors/ │ ├── brute_force_detector.py │ ├── password_spray_detector.py │ ├── account_enumeration_detector.py │ ├── abnormal_login_detector.py │ ├── privilege_escalation_detector.py │ ├── reconnaissance_detector.py │ ├── suspicious_ip_detector.py │ └── portscan_detector.py ├── sample_logs/ │ └── sample_auth.log # Sample Linux auth log for testing └── reports/ # Output directory for standalone CLI use ``` ## 12. API 参考 除 `/api/auth/*` 和 `/api/health` 外，所有的 endpoint 都需要在 `Authorization: Bearer ` 请求头中提供有效的 JWT。 ### 身份验证 — `/api/auth` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | POST | `/register` | 注册新的分析师账号 | | POST | `/login` | 身份验证并接收 JWT | | POST | `/logout` | 使 session 失效 (无状态) | | GET | `/me` | 返回当前用户资料 | | PUT | `/profile` | 更新用户名和邮箱 | | PATCH | `/me/password` | 修改密码（需要当前的密码） | | POST | `/forgot-password` | 生成密码重置 token | | POST | `/reset-password` | 提交重置 token 和新密码 | ### 日志管理 — `/api/logs` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | POST | `/upload` | 上传日志文件（字段：`logfile`）— 返回 202 | | GET | `/files` | 列出当前用户上传的文件 | | DELETE | `/files/:id` | 删除文件、事件及相关告警 | | GET | `/` | 分页日志查询（`page`, `limit`, `search`, `status`, `eventType`, `fileId`） | | GET | `/stats` | 聚合 dashboard 遥测数据 | ### 告警中心 — `/api/alerts` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | GET | `/` | 列出告警（`status`, `severity`, `page`, `limit`） | | GET | `/stats` | 统计未解决和未关闭的告警 | | GET | `/:id` | 获取告警详情及相关日志摘录 | | PATCH | `/:id/status` | 更新告警状态（`Open`, `Investigating`, `Resolved`） | ### 事件响应 — `/api/incidents` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | GET | `/` | 列出事件案例 | | POST | `/` | 从告警 ID 创建事件 | | GET | `/:id` | 获取包含备注和审计日志的完整事件 | | POST | `/:id/assign` | 分配分析师 | | POST | `/:id/note` | 追加备注 | | POST | `/:id/respond` | 执行遏制措施（`block_ip`, `disable_user`, `escalate`） | | POST | `/:id/resolve` | 解决案例 | ### 封禁资产 — `/api/blocked-assets` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | GET | `/` | 列出当前用户被封锁的 IP（`search`, `page`, `limit`） | ### 检测规则 — `/api/detection-rules` | 方法 | Endpoint | 描述 | |--------|----------|-------------| | GET | `/` | 获取全部 8 个规则的开启/关闭状态 | | PATCH | `/:ruleId` | 开启或关闭某项规则（body: `{ "enabled": true }`） | ### 健康检查 | 方法 | Endpoint | 描述 | |--------|----------|-------------| | GET | `//health` | 返回服务器状态、运行时间和时间戳 | ## 13. 未来改进 - 支持 Windows Event Log (XML/EVTX) 以及 Apache/Nginx access log 格式 - 自定义规则阈值编辑器 — 允许分析师通过 UI 调整暴力破解的时间窗口和次数参数 - 针对 `Critical` 严重级别告警的邮件或 webhook 通知 - 将事件报告导出为 PDF 或 Markdown - 提供 Docker Compose 设置以实现零配置的本地部署 ## 14. 简历描述

标签：AMSI绕过, GNU通用公共许可证, MITM代理, MongoDB, Node.js, Python, React, SIEM平台, Syscalls, 威胁检测, 无后门, 自定义脚本, 逆向工具