et0ILesTevy/incident-management-pipeline

# AI 增强的事件管理流水线 一个自动化、安全优先的事件管理和异常检测流水线，基于 **FastAPI**、**PagerDuty**、**ServiceNow** 和 **Gemini AI** 构建。 该项目接收高频遥测数据，检测性能异常，在 PagerDuty 中触发事件响应流程，利用 AI 诊断创建并丰富 ServiceNow 工单，并分发多阶段的电子邮件通知。 ## 核心功能 1. **异常检测：** 实时滑动窗口遥测速率分析。当请求速率超过可配置的阈值（默认为 `8.0 req/sec`）时，系统将标记为中断事件。 2. **ServiceNow 编排：** 使用异步 API 操作，在 ServiceNow 中自动创建、丰富和解决事件工单。 3. **Gemini AI 诊断：** 使用 `gemini-2.5-flash` 模型，从遥测日志中生成 Markdown 格式的根因分析（RCA）和分类摘要。 4. **两阶段电子邮件警报：** 在 AI 诊断报告编制完成之前，先发送即时的低延迟分类通知，随后再发送内容丰富的 HTML 格式电子邮件。 5. **自动恢复循环：** 当检测到遥测速率降至恢复阈值以下时，自动解决处于活动状态的 PagerDuty 事件，并将相应的 ServiceNow 工单标记为已解决。 ## 安全架构 为了防止滥用、欺骗和未经授权的访问，该流水线实施了四层安全验证： * **HMAC-SHA256 Webhook 签名：** 根据已配置的 webhook 密钥，验证传入的 PagerDuty webhook payload 的加密签名（`X-PagerDuty-Signature`）。 * **自定义 Token Header 检查：** 要求传入的 webhook 携带预先共享的安全标头（`X-Secure-Token`），以防止伪造调用。 * **IP 允许列表强制执行：** 将传入的 webhook 调用限制为 PagerDuty 官方的传出 IP 地址和 CIDR 网段。 * **安全的模拟器端点：** 在预先共享的 128 位 header token 检查（`X-Simulator-Token`）的保护下，安全地暴露突发流量模拟器（`/api/simulator/burst` 和 `/api/simulator/clear`）。 ## 技术栈 * **编程语言：** Python 3.13+ * **框架：** FastAPI, Uvicorn * **HTTP 客户端：** HTTPX (异步请求) * **AI 模型：** Google Gen AI SDK (`gemini-2.5-flash`) * **数据库/集成：** PagerDuty Events API v2, ServiceNow Table API, SMTP 邮件服务器 * **隧道穿透：** Cloudflare Tunnels (`cloudflared`) ## 快速开始 ### 1. 安装 克隆仓库并在虚拟环境中安装依赖项： ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ### 2. 配置 (`.env`) 根据 `.env.example` 模板，在根目录下创建一个 `.env` 文件： ``` # PagerDuty Webhook Secret（用于 HMAC 验证） PAGERDUTY_WEBHOOK_SECRET=your_pagerduty_webhook_secret # 传入 Webhook 的自定义 Header Token PAGERDUTY_SECURE_TOKEN=your_pagerduty_secure_token # SMTP 电子邮件凭据 SENDER_EMAIL=your_sender@gmail.com SENDER_APP_PASSWORD=your_sender_app_password RECEIVER_EMAIL=your_receiver@gmail.com # ServiceNow 连接详情 SERVICENOW_INSTANCE=your_servicenow_instance_subdomain SERVICENOW_USER=admin SERVICENOW_PASSWORD=your_servicenow_password # Gemini AI 凭据 GEMINI_API_KEY=your_gemini_api_key # 用于 Burst Simulator 身份验证的 Pre-Shared Token SIMULATOR_AUTH_TOKEN=your_secure_simulator_token ``` ### 3. 运行服务器 启动 FastAPI 应用程序： ``` PYTHONPATH=. .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000 ``` ### 4. 通过 Cloudflare Tunnel 暴露服务器 在一个新的终端窗口中，启动一个安全的公共 Cloudflare Tunnel，将您的 webhook 处理程序映射到互联网： ``` cloudflared tunnel --url http://127.0.0.1:8000 ``` 记下生成的 `*.trycloudflare.com` URL，并将其注册为您的 PagerDuty Webhook 订阅目标： `https://.trycloudflare.com/webhooks/pagerduty` ## 中断模拟与测试 要在本地测试端到端的集成流程，请通过发送您的预共享模拟器 token 来触发突发流量模拟器： ``` curl -X POST "http://127.0.0.1:8000/api/simulator/burst?duration=15" \ -H "X-Simulator-Token: your_secure_simulator_token" ``` **需要关注的日志序列：** 1. 大量遥测请求涌入（`⚡ BURST`）。 2. 异常检测器检测到速率突增并触发 PagerDuty。 3. PagerDuty webhook 触发，创建 ServiceNow 工单并发送分类电子邮件。 4. Gemini 诊断丰富操作异步执行，将注释发布到 ServiceNow 事件中，并发送内容丰富的 HTML 电子邮件。 5. 15 秒后，突发流量停止，速率回落至基线水平，事件得以解决，ServiceNow 工单状态更新为 **Resolved**。 ## 运行测试 运行集成测试套件以验证端点身份验证和流程行为： ``` PYTHONPATH=. .venv/bin/python tests/test_flow.py ```

标签：逆向工具