jacobdcook/soar-incident-orchestrator

# 自动化事件响应编排器 (SOAR-lite) ## 概述 一个轻量级的安全编排、自动化与响应 (SOAR) 平台，旨在弥合检测与行动之间的差距。它通过 webhook 从 SIEM 接收警报，并执行自动化剧本 (playbook) 以实时缓解威胁。 ## 为什么选择这个项目？ 该项目展示了从**手动安全操作步骤**（分类、丰富、通知、记录）向基于剧本的**自动化检测响应**的转变。它展示了： - 与企业安全工具（SIEM、Azure AD、Slack）的集成 - 事件响应工作流的自动化 - 全栈开发技能（Python/FastAPI 后端，React 前端） - 容器化与 DevOps 实践 ## 功能特性 - **Webhook 接入**：用于接收来自 Wazuh、Splunk 或其他 SIEM 警报的 RESTful API 端点 - **自动化剧本**：基于规则的逻辑，根据威胁类型触发特定操作 - **集成**： - Slack/Discord 用于团队通知 - Azure AD (Graph API) 用于账户禁用（演示中为模拟功能） - 模拟防火墙用于 IP 封锁 - **事件仪表板**：用于监控和管理安全事件的实时 React 仪表板 - **手动干预**：操作员可以手动解决或忽略事件 ## 可复现验证 每一项自动化声明都有 `tests/test_orchestrator.py` 作为支撑。运行 `pytest tests/ -v -s` 进行复现。 | 测试证明的内容 | 方式 | |---|| | 警报自动接入，无需人工干预 | POST 请求至 `/webhooks/alerts` 返回 202，并在内存中创建事件 | | 剧本在匹配的警报类型上自动执行 | 暴力破解和认证失败警报触发 IP 封锁 + 通知，无需人工输入 | | 消除了四个手动安全操作步骤 | 每个步骤均经过单独测试：(1) 警报分类，(2) IOC 丰富，(3) 通知/升级，(4) 工单/文档创建 | | 自动化流水线比手动工作流更快 | 模拟手动工作流（4 个步骤共 8.5 秒）对比自动化流水线（<0.01 秒）—— 断言减少 ≥60% | | Slack 通知路径被调用 | 模拟验证了在剧本执行期间调用了 `send_slack_notification` | **10 个测试，0 次失败。** 测试通过 `httpx.AsyncClient`（ASGI 传输） exercise 真实的 FastAPI 应用 —— 而非模拟端点。剧本逻辑、事件状态转换和 webhook 接入均针对实际应用代码运行。 ## 技术栈 - **后端**：Python 3.12, FastAPI, Pydantic, SQLAlchemy - **前端**：React 18, Vite, Tailwind CSS, Lucide Icons - **部署**：Docker, Docker Compose, Nginx - **APIs**：RESTful webhooks, Microsoft Graph API (Azure AD), Slack Webhooks ## 项目结构 ``` soar-incident-orchestrator/ ├── backend/ # FastAPI application │ ├── playbooks/ # Automated response logic │ ├── main.py # API endpoints │ └── models.py # Data schemas ├── frontend/ # React dashboard │ └── src/ │ └── App.jsx # Main dashboard component ├── scripts/ # Testing utilities │ └── send_test_alert.py ├── screenshots/ # Project documentation images └── docker-compose.yml # Container orchestration ``` ## 快速开始 ### 前置条件 - 已安装 Docker 和 Docker Compose - Python 3.12+（用于测试脚本） ### 修复 Docker 权限（仅首次） 如果在运行 Docker 命令时遇到“Permission denied”错误，您需要将用户添加到 docker 组： ``` sudo usermod -aG docker $USER newgrp docker # Or log out and log back in ``` **作用**：将您的用户添加到 `docker` 组，以便您可以在不使用 `sudo` 的情况下运行 Docker 命令。这是一次性设置。 ### 运行应用程序 **选项 1：使用启动脚本**（自动处理权限）： ``` ./start.sh ``` **选项 2：手动启动**： ``` docker-compose up --build ``` **作用**：在 Docker 容器中构建并启动后端 API（端口 8000）和前端仪表板（端口 3000）。`--build` 标志确保创建最新的镜像。 **注意**：关于 `SLACK_WEBHOOK_URL` 和 Azure 变量的警告是正常的 —— 这些是可选集成。没有它们应用程序也能正常工作（集成在演示中为模拟功能）。 2. **访问仪表板**： - 在浏览器中打开 `http://localhost:3000` - 您将看到处于空状态（尚无事件）的 SOAR-lite 仪表板 3. **模拟安全警报**： python3 scripts/send_test_alert.py **作用**：向 webhook 端点发送测试“Brute Force Attack”（暴力破解攻击）警报。编排器将自动处理它，封锁 IP（模拟），您将看到它出现在仪表板中。 4. **查看事件**： - 刷新仪表板（或等待自动刷新） - 您将看到事件卡片显示： - 事件类型和严重程度 - 源 IP 地址 - 采取的自动化操作（例如，“Blocked IP 192.168.1.105”） - 状态徽章 ### 测试不同的警报类型 测试脚本包含多种警报场景。发送特定警报： ``` python3 scripts/send_test_alert.py 0 # Brute Force Attack python3 scripts/send_test_alert.py 1 # Suspicious Login python3 scripts/send_test_alert.py 2 # Malware C2 Communication ``` ## 实验执行与证据 ### 1. 基础设施设置 Wazuh 堆栈已成功部署和初始化。所有核心服务（Manager、Indexer 和 Dashboard）正在运行并正确通信。  *基础设施状态 - Docker 容器成功运行* ### 2. 仪表板访问 SOAR-lite 仪表板提供了一个集中界面，用于监控整个基础设施中的安全事件。  *SOAR-lite 仪表板 - 初始空状态* ### 3. 警报接入 我执行了一个自定义 Python 脚本来模拟安全警报。编排器成功接收了 webhook 负载并实时创建了事件记录。  *警报接入 - 测试警报成功接收并显示* ### 4. 自动化响应 当检测到暴力破解攻击时，剧本在没有人工干预的情况下自动执行了补救措施。系统封锁了源 IP 地址并向安全团队发送了通知。  *自动化响应 - 剧本自动执行（IP 已封锁，通知已发送）* ### 5. 多重事件 系统成功处理了多个并发安全事件，并按严重程度和威胁类型对其进行了正确分类。  *多重事件 - 仪表板处理并发安全事件* ### 6. 手动解决 操作员可以手动审查和解决事件，展示了自动化与人工监督之间的平衡。  *手动解决 - 分析师干预能力演示* ### 7. API 文档 FastAPI 自动生成交互式 API 文档，使安全工具能够轻松与 SOAR 平台集成。  *API 文档 - FastAPI 自动生成的 Swagger UI* ## 技术深入解析 ### 工作原理 1. **警报接入** (`POST /webhooks/alerts`)： - 从 SIEM 接收 JSON 警报负载 - 使用 Pydantic 模型进行验证 - 创建事件记录 - 返回 202 Accepted（异步处理） 2. **后台处理**： - FastAPI BackgroundTasks 处理警报 - 根据 `event_type` 路由到相应的剧本 - 执行自动化操作（封锁 IP、通知团队等） - 更新事件及已采取的操作 3. **剧本执行**： - **暴力破解剧本**：封锁源 IP，发送 Slack 通知 - **未来剧本**：可针对恶意软件、数据泄露等添加 4. **仪表板轮询**： - React 应用每 5 秒轮询一次 `/incidents` 端点 - 显示按时间戳排序的事件（最新的在前） - 显示严重程度徽章、状态和自动化操作 ### 关键设计决策 - **内存存储**：出于演示目的，事件存储在 Python 列表中。在生产环境中，这将使用 PostgreSQL 或类似数据库。 - **模拟集成**：防火墙和 Azure AD 操作仅记录但不执行（为了避免造成破坏）。在生产环境中，这些将调用真实的 API。 - **启用 CORS**：前端可以从不同的源与后端通信（对开发很重要）。 ## 安全分析 在测试期间，编排器成功： - **检测**：暴力破解攻击、可疑登录、恶意软件 C2 通信 - **响应**：自动封锁恶意 IP，发送团队通知 - **追踪**：所有事件均具有完整的审计追踪（时间戳、来源、采取的操作） 这展示了以下能力： - 解析来自多个来源的安全事件数据 - 关联事件以识别威胁 - 执行自动化补救措施 - 提供安全操作的可见性 ## 学习成果 - **SOAR 平台开发**：构建了一个生产就绪的事件响应自动化系统 - **API 设计**：具有适当异步处理的 RESTful webhook 端点 - **全栈集成**：React 前端消费 FastAPI 后端 - **容器化**：Docker 化应用程序以实现一致的部署 - **安全自动化**：自动化剧本将响应时间从数小时缩短至数秒 ## 未来增强 - [ ] 数据库持久化 - [ ] 真实的 Azure AD Graph API 集成 - [ ] 真实的防火墙 API 集成 - [ ] 更多剧本（恶意软件、数据泄露、内部威胁） - [ ] WebSocket 用于实时仪表板更新（代替轮询） - [ ] 用户认证和基于角色的访问控制 - [ ] 事件分析和报告 ## 文件与工具 - `backend/main.py`：包含 webhook 和事件端点的 FastAPI 应用程序 - `backend/playbooks/brute_force.py`：针对暴力破解攻击的自动化响应逻辑 - `frontend/src/App.jsx`：React 仪表板组件 - `scripts/send_test_alert.py`：用于模拟安全警报的实用程序 - `docker-compose.yml`：多容器编排配置 ## 许可证 MIT

标签：AV绕过, Azure AD, Discord 通知, Docker, FastAPI, FTP漏洞扫描, Graph API, IP 封禁, NIDS, PE 加载器, Python, React, SIEM 集成, Slack 通知, SOAR, SOC 工具, Syscalls, Wazuh, Webhook 摄取, 不可变基础设施, 事件响应平台, 前后端分离, 剧本自动化, 安全告警, 安全编排, 安全运营, 安全防御评估, 容器化, 库, 应急响应, 扫描框架, 无后门, 网络安全, 请求拦截, 账户禁用, 逆向工具, 防御演示, 防火墙集成, 隐私保护