DanielsRT/boron-incident-response

# Boron：事件响应仪表板 一个生产级、分布式的事件处理平台，用于安全事件检测和响应。它接收海量的 Azure 安全遥测数据，应用可插拔的基于规则的威胁检测机制，将告警标准化至 Elasticsearch 中，并通过响应式的 React 仪表板展示分析洞察。 **使用场景**：企业 SOC 团队以低延迟和可水平扩展的处理能力，监控 Azure 基础设施中的可疑活动。 ## 架构概述 ``` Azure Log Analytics → FastAPI Backend → Logstash Pipeline → Elasticsearch → React Dashboard ↓ Celery Workers (Redis Queue) ↓ Redis Cache Layer ``` ### 设计原则 **异步优先后端**：使用 Celery worker 将 API 请求处理与计算密集型的规则评估解耦。防止在查询 Azure Log Analytics 或评估数千条安全规则时发生阻塞 I/O。 **微服务分离**：Logstash 作为专用的 ETL 层，将标准化逻辑从应用代码中抽象出来——实现了独立扩展和复用。后端保持无状态，便于水平扩展。 **用于安全分析的 Elasticsearch**：提供取证分析和告警关联所需的全文本搜索、时间序列聚合以及复杂的布尔查询。Redis 缓存层减少了针对热点数据集的重复查询。 ## 技术栈与选型理由 ### 后端 (Python 3.11+) | 组件 | 选择 | 理由 | |-----------|--------|-----------| | **框架** | FastAPI | 类型安全的 async/await，自动生成 OpenAPI 文档，样板代码少——这对于维持告警 SLA 至关重要 | | **任务队列** | Celery + Redis | 经过实战检验的分布式任务编排；取代简单的线程机制以实现 worker 的水平扩展 | | **搜索与存储** | Elasticsearch | 倒排索引可实现低于 100ms 的安全查询；针对保留策略进行时间序列优化 | | **缓存** | Redis | 内存缓存，用于重复的威胁情报查询；支持 pub/sub 以实现仪表板实时更新 | | **测试** | pytest + pytest-cov | 覆盖单元/集成测试的 82 个测试用例；兼容 CI 的覆盖率报告 | ### 前端 (TypeScript + React 19) | 组件 | 选择 | 理由 | |-----------|--------|-----------| | **框架** | React 19 | 严格模式兼容性确保了可维护性；并发渲染可避免在大量告警接入时界面卡顿 | | **语言** | TypeScript | 安全领域的类型安全可防止空指针 bug；为 Alert/Rule schema 提供更好的 IDE 自动补全 | | **构建工具** | Vite | HMR 速度比 webpack 快 10 倍——对于快速迭代事件响应仪表板至关重要 | | **样式** | Tailwind CSS | 实用优先的方法减少了 CSS 负载；在 76 个通过的测试中保持一致的设计系统 | | **测试** | Jest + React Testing Library | 优先关注可访问性断言；强制实现零 console 警告 | ### 基础设施 - **Docker Compose**：可复现的本地开发环境，模拟生产环境拓扑结构 - **Logstash 8+**：无状态 ETL pipeline；独立于后端进行版本控制 - **TLS/SSL**：用于零信任内部通信的证书生成脚本 ## 核心功能 ### 后端功能 - **Azure 集成**：通过 Azure Log Analytics REST API 查询 SecurityEvent 日志，并使用连接池 - **异步规则引擎**：可插拔、无状态的检测规则——通过规则仓库模式实现免改代码的扩展 - **实时处理**：Celery 任务将 API 响应与告警生成解耦；借助 Redis pub/sub 可实现亚秒级延迟 - **REST API**：FastAPI 暴露强类型的 endpoint（`GET /alerts`, `POST /rules/test`）；通过 OpenAPI 实现自带文档 - **可观测性就绪**：针对 correlation ID 的结构化日志；兼容 ECS 的 JSON 输出 ### 前端功能 - **性能表现**：React 19 的并发渲染可防止在分页加载 1 万+ 告警时出现 UI 卡死 - **实时更新**：适配 WebSocket 的架构，无需轮询即可刷新仪表板 - **高级过滤**：针对 1 万+ 告警实现客户端过滤与服务器端分页 - **响应式设计**：移动优先的 Tailwind；零可访问性违规 - **状态管理**：通过 context 最小化 props 传递；在此规模下无需使用强类型的 Redux 替代方案 ### 检测规则（可扩展） 1. **暴力破解检测**：来自单一 IP 的多次失败登录 + 时间窗口阈值 2. **权限提升**：检测将用户添加到敏感 AAD 组的行为（需要接入审计日志） 3. **可疑进程执行**：基于规则的匹配，针对已知的恶意软件命令行特征 ## 项目结构 ``` boron-incident-response/ ├── backend/ # Python FastAPI + Celery │ ├── app/ │ │ ├── core/config.py # Environment-based config management │ │ ├── alert/ # Detection rules & alert lifecycle │ │ │ ├── model.py # Pydantic schemas (type validation) │ │ │ ├── service.py # Business logic (rule eval, dedup) │ │ │ ├── tasks.py # Celery task definitions │ │ │ └── router.py # FastAPI endpoints (/alerts, /stats) │ │ └── log/service.py # Azure Log Analytics client │ ├── tests/ # 82 tests across unit/integration │ ├── scripts/ # Deployment helpers │ ├── main.py # Uvicorn entrypoint │ └── requirements.txt │ ├── frontend/ # TypeScript React + Vite │ ├── src/ │ │ ├── components/ # Reusable Alert, Filter, Stat components │ │ ├── services/ # API client (with auth interceptors) │ │ ├── types/ # TypeScript interfaces (Alert, Rule, etc.) │ │ └── App.tsx # Root component + routing │ ├── tests/ # 76 tests, Jest + React Testing Library │ └── vite.config.ts │ ├── logstash/ │ └── pipeline/logstash.conf # Normalization: Azure → ECS schema │ └── docker-compose.yml # Full stack orchestration ``` ## 快速上手 ### 前置条件 - Docker & Docker Compose 2.0+ - Azure Service Principal（用于 Log Analytics 查询权限） - Node.js 18+（用于前端开发） ### 快速启动 ``` # 1. 克隆并设置环境 git clone cd boron-incident-response cp .env.example .env # Configure Azure credentials # 2. 启动 infrastructure docker-compose up -d # 3. 验证服务 curl http://localhost:8000/health # FastAPI curl http://localhost:3000 # React dashboard ``` 有关详细的测试执行和 CI/CD 设置，请参阅 **TESTING.md**。 ## 测试与质量 ### 测试覆盖率 | 测试套件 | 数量 | 工具 | 覆盖率 | |-------|-------|------|----------| | **后端** | 82 个测试 | pytest | 使用 `pytest --cov=app` 运行 | | **前端** | 76 个测试 | Jest + RTL | 使用 `npm test -- --coverage` 运行 | | **React 警告** | 0 | 严格模式 | 在 CI pipeline 中强制执行 | ### 在本地运行测试 ``` # Frontend cd frontend && npm test -- --watchAll=false --coverage # Backend cd backend && pytest --cov=app --cov-report=html ``` ## 部署考量 ### 水平扩展 - **前端**：无状态的 React SPA——可通过任意 CDN（Cloudflare, CloudFront）提供服务 - **后端**：负载均衡器后端运行无状态的 FastAPI 副本；Celery worker 独立扩展 - **队列**：在生产环境中使用 Redis Cluster 或托管的 Azure Cache for Redis ### 高可用性 - Elasticsearch 集群包含 3 个以上的 master 节点以及专用的 data 节点 - Logstash 无状态 pipeline 具备负载均衡能力 - 在 `GET /health` 上配置 FastAPI 健康检查，用于负载均衡器集成 ### 安全态势 - 所有服务间通信均采用 TLS 1.3 - 采用最小权限角色（SecurityEventReader）的 Azure Service Principal - Redis 密码保护；Elasticsearch X-Pack 身份验证 - 针对每条检测规则进行 API 速率限制（防止规则引擎遭遇 DOS） ## 技术决策摘要 | 决策 | 备选方案 | 权衡 | |----------|-------------|-----------| | Celery + Redis | AWS Lambda + SQS | 有状态 worker 与供应商锁定之间权衡；选择了灵活性 | | Elasticsearch | DuckDB + S3 | OLAP 速度与 OLTP 查询新鲜度之间权衡；为了事件响应选择了 OLTP | | React + TypeScript | Vue.js + TS | 生态系统成熟度与就业市场需求；选择了 React | | Logstash | 定制 ETL sidecar | 运维开销与久经考验的工具之间权衡；选择了可维护性 | ## 贡献指南 1. 优先编写测试（安全代码采用 TDD） 2. 在提交 PR 之前在本地运行覆盖率检查 3. 遵循类型注解（若无正当理由，禁止使用 `Any`） 4. 如果添加了新的测试套件，请更新 TESTING.md ## 许可证 MIT

标签：AV绕过, Elasticsearch, FastAPI, Python, 内容过滤, 分布式架构, 安全规则引擎, 安全运营, 扫描框架, 搜索引擎查询, 无后门, 版权保护, 红队行动, 自动化攻击, 逆向工具