HoloOlagokeLabs/shield-eye-desktop

# ShieldEye 日志分析器     ShieldEye 日志分析器是一个为开发者、SOC 分析师和网络安全专业人士设计的 **手动日志事件收集和分析系统**。 该系统允许开发者定义和记录有意义的应用程序事件，将它们存储在 MongoDB 中，并使用 ShieldEye 平台进行分析，以检测潜在的安全事件。 本 README 文件是集成和使用 ShieldEye 事件记录器的 **技术手册**。 [ShieldEye 文档](https://docs.shieldeye.holoolagoke.com) ## 目录 - [ShieldEye 日志分析器](#shieldeye-log-analyzer) - [目录](#table-of-contents) - [项目概述](#project-overview) - [功能](#features) - [平台功能](#platform-capabilities) - [桌面安装](#desktop-installation) - [快速安装（Debian/Ubuntu）](#quick-install-debianubuntu) - [快速安装（Windows）](#quick-install-windows) - [快速入门](#quick-start) - [安装 & 启动](#install--launch) - [从 MongoDB 导出日志](#export-logs-from-mongodb) - [设置警报偏好](#set-alert-preferences) - [上传日志](#upload-logs) - [分析](#analyze) - [更多信息](#more-info) - [入门](#getting-started) - [日志事件结构](#log-event-structure) - [应用程序元数据](#application-metadata) - [网络请求上下文](#network-request-context) - [创建日志事件](#creating-log-events) - [错误日志中间件](#error-logging-middleware) - [示例用法](#example-usage) - [数据库连接](#database-connection) - [设置偏好](#setting-up-preferences) - [教程](#tutorials) - [SOC 分析师工作流程](#soc-analyst-workflow) - [Web 平台（检测阶段）](#web-platform-detection-phase) - [调查阶段](#investigation-phase) - [桌面平台（取证分析）](#desktop-platform-forensic-analysis) - [分析 & 使用](#analysis--usage) - [架构哲学](#architecture-philosophy) - [开源 & 定制](#open-source--customization) - [发布](#releases) - [最新发布](#latest-release) - [亮点](#highlights) - [安装](#installation) - [贡献](#contributing) - [许可证](#license) - [备注](#notes) - [安全通知](#security-notice) - [致谢](#acknowledgements) - [作者](#author) ## 项目概述 ShieldEye 日志分析器使开发者能够在他们的应用程序中手动创建结构化日志事件。 这些事件： - 存储在开发者的 MongoDB 实例中 - 由 ShieldEye 应用程序读取和分析 - 用于识别异常、安全威胁和不正常行为 一旦用户在 ShieldEye 上注册，平台就会连接到用户的 MongoDB 数据库（只读）并分析存储的日志。**ShieldEye 不会在其自己的服务器上存储用户日志**。 ## 功能 - 手动、开发者控制的日志事件创建 - 结构化日志记录，用于安全和可观察性 - 多种事件类型（身份验证、系统、网络、应用程序等） - 可配置的严重级别（`info`、`warn`、`error`、`critical`） - 基于 MongoDB 的存储，可扩展 - 事件标记，用于过滤和关联 - 通过 ShieldEye 平台进行只读日志分析 ### 平台功能 [**Web 平台**](https://shieldeye.holoolagoke.com) - 实时和近实时日志分析 - 当前月日志范围，以提高性能效率 - 轻量级 SOC 风格监控 [**桌面平台**] - 离线日志分析 - 超出当前月的日志调查 - 从 MongoDB 导出（mongoexport 或自定义导出脚本）的 JSON 日志文件导入 - 专为取证审查和长期分析设计 ## 桌面安装 ShieldEye 桌面应用程序可以从 [最新发布](https://github.com/holoolagoke/shield-eye-desktop/releases/latest) 下载 ### 快速安装（Debian/Ubuntu） ``` sudo apt update sudo apt install ./shieldeye_1.1.0_amd64.deb ``` ### 快速安装（Windows） 双击安装程序 `shieldeye_1.1.0_setup.exe` ## 快速入门 ### 安装 & 启动 下载适用于您的操作系统的安装程序并运行它。 首次启动时，创建一个 PRAGMA 密钥（至少 8 个字符）。 此密钥加密您的本地数据库 — 请妥善保管。  成功后，仪表板页面将显示空数据  ### 从 MongoDB 导出日志 在您的 MongoDB Atlas 仪表板中，使用 mongoexport 或 Atlas UI 导出工具将 `event_logs` 集合导出为 JSON。 ### 设置警报偏好 打开 **偏好设置** 页面，选择哪些日志级别（`warn`、`error`、`critical`）应触发警报，然后点击保存。  ### 上传日志 在相同的偏好设置页面，点击 **上传日志**，然后选择您导出的 JSON 文件。  ### 分析 转到 **仪表板** 以查看日志摘要、图表并过滤事件。 - **总日志**：列出数据库中的总事件日志 - **日期范围**：显示日志的时间日期间隔 - **日志级别**：显示每个日志级别发生的次数 - **日志饼图**：以饼图视图显示日志级别 - **日志表**：以表格格式显示事件日志 - **查看窗格**：提供有关事件日志的更多信息 - **搜索栏**：根据输入文本过滤事件日志  检查 **警报** 页面，查看基于您偏好的标记条目。 - **总警报**：列出生成的总警报数 - **已读警报**：显示已读警报的数量 - **未读警报**：显示未读警报的数量 - **日志级别警报**：显示为每个日志级别生成的警报数量 - **标记为已读**：将选定的警报标记为已读 - **全部标记为已读**：将所有警报标记为已读 - **删除警报**：删除选定的警报 - **全部删除**：删除所有警报 - **警报表**：以表格格式显示日志事件警报 - **查看窗格**：提供有关警报的更多信息 - **搜索栏**：根据输入文本过滤警报  ### 更多信息 转到 **关于** 页面，查看 *关于应用程序*、*检查更新* 或 *访问应用程序 Web 版本*。  ## 入门 ### 日志事件结构 每个日志事件都遵循一致的格式： | 字段 | 描述 | |---------------|-------------------------------------------------------| | `_id` | 唯一的日志事件标识符 | | `timestamp` | 事件发生的时间 | | `level` | 严重级别（`info`、`warn`、`error`、`critical`） | | `event_type` | 事件的高级名称 | | `category` | 将事件分组到定义的标准中 | | `source` | 事件起源的文件或模块 | | `message` | 可读的事件描述 | | `stack` | 错误堆栈跟踪（如果适用） | | `tags` | 用于分类的简短关键词 | ### 应用程序元数据 | 字段 | 描述 | |---------------|-----------------------------------| | `app.name` | 开发者应用程序的名称 | | `app.version` | 应用程序版本 | ### 网络请求上下文 以下字段在可用时自动从传入请求中捕获： ``` user.id user.ip user.method user.endpoint user.status user.user_agent ``` ### 创建日志事件 在您的应用程序中创建一个集中的事件记录器文件。 示例记录器实现 ``` // shieldeye-logger.js import { v4 as uuidv4 } from "uuid" import clientPromise from "..." // Connect to MongoDB const client = await clientPromise const db = client.db("logs") export async function logEvent(req, res, { event_type, level = "info", category, source, message, stack = "", tags = [] }) { try { if (!db) return const collection = db.collection("event_logs") const log = { _id: uuidv4(), timestamp: new Date(), level, category, event_type, source, message, stack, app: { name: process.env.APP_NAME || "YourAppName", version: process.env.APP_VERSION || "1.0.0" }, user: { id: req?.validatedUserId || "anonymous", ip: req?.ip || "0.0.0.0", method: req?.method || "N/A", endpoint: req?.originalUrl || "N/A", status: res?.statusCode || null, user_agent: req?.headers?.["user-agent"] || "N/A" }, tags } return await collection.insertOne(log) } catch (err) { console.error("ShieldEye Logger Error:", err.message) } } ``` ### 错误日志中间件 ``` // shieldeye-logger.js export function errorEvent(err, req, res, next) { logEvent(req, res, { event_type: err.name || "UnhandledException", category: "Server Error", source: req?.originalUrl || "N/A", message: err.message, stack: err.stack, tags: ["error", "exception"] }) } ``` ### 示例用法 ``` await logEvent(req, res, { event_type: "Authentication", level: "warn", category: "auth_failed", source: "auth func", message: `${username} login attempt failed`, tags: ["auth", "login"] }) ``` ### 数据库连接 创建一个名为 `logs` 的数据库 创建一个名为 `event_logs` 的集合 ShieldEye 只扫描名为 *logs* 的数据库和名为 *event_logs* 的集合 数据库用户（必需）： ``` * Create a MongoDB user named: shieldeye_agent * Permissions: Read-only * Restricted to: logs database and event_logs collection * Add the ShieldEye application IP address to your MongoDB IP allowlist. ``` ### 设置偏好 在注册并登录 ShieldEye 账户后，配置您的偏好。 必需字段： - **mongoUrl**: mongodb+srv://shieldeye_agent:@... - **level**: 创建警报时监控的日志级别数组。例如： ``` ["warn", "error", "critical"] ``` ## 教程 - [如何集成 ShieldEye](./tutorials/How_to_integrate_ShieldEye.md) - [YouTube 播放列表](https://youtube.com/playlist?list=PL1IOjRE7eB0HsqeGqTmeWZBgaqxmHwUcI&si=Ms5X1LMK-679Ot5V) ## SOC 分析师工作流程 ShieldEye 支持实用的 SOC 调查工作流程： ### Web 平台（检测阶段） - 监控当前月的日志，接近实时 - 通过严重性（`warn`、`error`、`critical`）进行过滤 - 识别可疑模式（例如，重复失败的登录、异常端点） ### 调查阶段 - 从 MongoDB 导出相关日志 - 记录观察到的异常和时间线 ### 桌面平台（取证分析） - 将导出的日志导入桌面应用程序 - 在扩展的时间范围内进行深入分析 - 关联事件并重建攻击模式 此工作流程符合现实世界的 SOC 操作，平衡 **性能（Web）** 和 **深度（桌面）**。 ## 分析 & 使用 日志直接从用户的 MongoDB 实例收集。ShieldEye 分析这些日志以查找异常和安全模式。 日志可以通过以下方式过滤： - event_type - level - category - tags - 日期 - 文字搜索 建议定期审查以尽早检测异常行为 最佳实践 - 使用清晰且描述性的消息值 - 应用一致的类别命名 - 使用小写标签以保持一致性 - 避免记录敏感数据（密码、令牌、机密、PII） - 归档或轮换旧日志以防止数据库膨胀 ## 架构哲学 ShieldEye 采用 **关注点分离** 的方法： - [**Web 平台**](https://shieldeye.holoolagoke.com) 专注于轻量级、当前月的检测和监控。 - [**桌面平台**](https://github.com/holoolagoke/shield-eye-desktop/releases/latest) 专注于深入、离线和历史取证分析。 - 这种混合方法反映了现实世界的安全架构，其中 **热数据（最近日志）** 与 **冷数据（归档日志）** 分离，以优化性能和调查深度。 这种设计确保了可扩展性、性能效率和分析师的灵活性。 ## 开源 & 定制 ShieldEye 被设计为可扩展的。 感兴趣的用户可以： - 探索和修改在此存储库中可用的完整源代码 - 定制检测逻辑 - 实现额外的关联规则 - 修改 UI 或后端逻辑以用于企业 - 扩展日志模式以符合内部安全标准 鼓励开发者分叉存储库并调整平台以满足组织或研究需求。 有关升级策略和架构扩展想法，请查看代码库结构和桌面导入模块。 ## 发布 ### 最新发布 **当前版本：** v1.1.0 查看 [CHANGELOG.md](./CHANGELOG.md) 以获取完整的发布历史和详细发布说明。 #### 亮点 - 改进的 JSON 导入可靠性 - 事件日志按最新顺序排序 - 部署间一致的数据库存储 - 改进的 SQLCipher 验证和数据库处理 - 多个错误修复和稳定性改进 #### 安装 - 从 GitHub 发布中下载最新版本 - 遵循 DESKTOP_INSTALLATION.md 中的安装指南 ## 贡献 - 分叉存储库 - 创建功能分支 - 提交带有清晰描述的拉取请求 - 遵循现有的代码风格 - 不要提交敏感数据或凭据 未来增强功能包括： - 高级关联规则 - 基于时间线的调查 - 扩展的导出和报告功能 欢迎贡献、设计反馈和安全审查。 ## 许可证 本项目采用 MIT 许可证。 © Holo Olagoke ## 备注 - 日志不会存储在 ShieldEye 服务器上。如果从您的 MongoDB 实例中删除日志，则无法恢复。 - 只提供使用 shieldeye_agent 只读用户创建的 MongoDB URL。 - ShieldEye Web 版本仅分析当前日历月内生成的日志（1 日 - 31 日），每月开始时，ShieldEye 开始分析新生成的日志。 - Web 版本不支持超出当前月的日志调查。 - 调查人员或开发人员鼓励记录异常模式或将日志从 MongoDB 导出，以保留历史数据以供离线分析。 - 可用桌面版本的 ShieldEye 支持长期日志保留和历史取证分析。 - 由于日志存储在用户的 MongoDB 实例中，因此可以将其导出并上传到 ShieldEye 桌面应用程序。 - 桌面版本允许在当前月之外进行调查，而不会影响 Web 平台的性能。 ## 安全通知 - 开发者负责确保敏感信息永远不会被记录。 - ShieldEye 不会在源处清理或编辑日志。 ## 致谢 本项目得到网络安全和软件工程社区的持续学习和专业指导的支持。 特别感谢： - **[Steven - MyDFIR](https://www.youtube.com/@MyDFIR)** 对于实用的 SOC 针对性培训、检测工程概念和影响 Shield Eye 日志分析和调查设计的现实世界防御性安全知识。 - **[Dave Gray](https://www.youtube.com/@DaveGrayTeachesCode)** 对于基础和高级全栈软件工程知识，知识有助于本项目的架构设计、可扩展性考虑和实现方法。 他们的教育内容对在 ShieldEye 开发中应用的技能和知识做出了重大贡献。 ## 作者 姓名：Holo Olagoke Friday 职业路径：网络安全 & 软件工程 网站：[www.holoolagoke.com](https://www.holoolagoke.com) 联系：[contact@holoolagoke.com](mailto:contact@holoolagoke.com)

标签：BurpSuite集成, MongoDB, OISF, PB级数据处理, Python, SOC分析, 安全事件响应, 安全事件检测, 安全运维, 无后门, 日志分析工具, 日志分析平台, 日志分析服务, 日志分析系统, 日志分析解决方案, 日志分析软件, 日志告警, 日志存储, 日志收集, 日志查询, 日志管理, 日志结构化, 桌面应用, 网络安全, 逆向工具, 隐私保护