naveena-zen/agentic-incident-response
GitHub: naveena-zen/agentic-incident-response
Vigil 是一个采用双阶段架构（只读 LLM 诊断 + 确定性策略引擎）的自主事件响应代理，结合 RAG 历史检索实现安全的自动化运维排障与缓解。
Stars: 0 | Forks: 0
# Vigil：自主事件响应代理控制台
Vigil 是一个自主事件响应原型。它采用**双阶段架构**，将概率性诊断推理与确定性安全控制分离开来。在异常情况下，Vigil 会使用 Groq API 模型实例执行只读代理循环（阶段 1）来隔离问题，然后将结果移交给确定性的 Python 策略引擎（阶段 2）进行自动缓解（例如模拟服务重启或回滚）或升级（人工呼叫）。
## 如何运行
### 前置条件：数据库设置
确保已启用并运行带有 `pgvector` 的 PostgreSQL 数据库实例。对于 Windows 用户，[`install_pgvector.ps1`](file:///c:/Users/navee/OneDrive/Desktop/Vigil/install_pgvector.ps1) 中提供了一个脚本用于复制扩展二进制文件。在 Docker 环境中，Compose 文件会自动配置带有 pgvector 的 PG 数据库。
### 选项 1：在本地运行（后端和前端）
1. **设置后端**：
安装依赖：
pip install -r requirements.txt
启动 FastAPI 开发服务器：
python -m uvicorn main:app --host 0.0.0.0 --port 8000
*注意：这会自动准备数据库 schema，运行数据库数据植入（添加 10 个带 embedding 的历史事件），启动指标循环调度程序，并启动服务器。*
2. **设置前端**：
导航到 frontend 文件夹，安装依赖并运行：
cd frontend
npm install
npm start
*React 控制台将在 `http://localhost:3000` 打开。*
3. **验证安装**：
通过执行冒烟测试脚本来验证 endpoint 是否正在运行：
python smoke_test.py
### 选项 2：通过 Docker Compose 运行
构建并启动容器化的 PostgreSQL 和 FastAPI 后端：
```
docker-compose up --build
```
*注意：仍需使用 Node/NPM 在本地 `http://localhost:3000` 运行前端。*
## 功能（已验证）
* **后台监控计时**：通过 `psutil` 定期记录本地主机的真实 CPU 和内存指标，并为内部服务生成模拟指标（`metrics_loop.py` 第 246-309 行）。
* **阈值告警引擎**：当指标超过阈值（延迟 > 500ms，错误率 > 5%，或 CPU > 85%）时触发警报，并保留服务级别的锁（`Service.investigation_in_progress`）以阻止重复运行（`metrics_loop.py` 第 174-201 行）。
* **AI 诊断循环（阶段 1）**：迭代只读的 OpenAI 兼容（Groq）工具调用代理，以检查服务器上下文（`phase1_agent.py` 第 279-395 行）。
* **本地语义 RAG**：使用本地 SentenceTransformer（`all-MiniLM-L6-v2`）和 pgvector HNSW 索引，将事件症状与 PostgreSQL 中的历史文档进行匹配（`phase1_agent.py` 第 217-243 行）。
* **动作策略网关（阶段 2）**：评估代理输出的确定性策略（规则、置信度、白名单），以触发模拟恢复或呼叫处理人员（`policy_engine.py` 第 163-260 行）。
* **交互式 SRE 控制台**：展示事件详情、指标、日志和时间线。对于等待升级的事件，可使用“批准动作”控制台按钮进行解决，这将直接绕过 LLM（`frontend/src/App.js`）。
* **Prometheus 监控**：在 `/metrics` 上暴露路由性能和事件监控的指标计数器（`main.py` 第 56-61 行）。
* **JWT 访问安全**：保护 endpoint 免受未经授权的修改（`auth.py`）。
## 配置
### 环境变量
Vigil 从根目录下的 `.env` 文件中读取配置。以下是代码中已验证的所有环境变量：
| 变量 | 描述 | 代码中的默认值 |
| :--- | :--- | :--- |
| `DB_HOST` | PostgreSQL 服务器的主机名。 | `localhost` |
| `DB_PORT` | PostgreSQL 服务器的端口。 | `5432` |
| `DB_NAME` | 数据库名称。 | `vigil` |
| `DB_USER` | 用于数据库连接的用户名。 | `postgres` |
| `DB_PASSWORD` | 用于数据库连接的密码。 | `postgres` |
| `GROQ_API_KEY` | Groq Cloud API endpoint 的身份验证密钥。 | `""` （必填） |
| `GROQ_MODEL` | 用于诊断分析的 Groq LLM 模型。 | `llama-3.3-70b-versatile` |
| `AGENT_MAX_ITERATIONS` | 阶段 1 期间的最大工具调用次数。 | `10` |
| `JWT_SECRET` | 用于 JSON Web Token 的签名密钥。 | `supersecretjwtsigningkey_changeme` |
| `JWT_ALGORITHM` | 用于签名 JWT token 的算法。 | `HS256` |
| `JWT_EXPIRE_MINUTES` | 用户 token 的过期时间（以分钟为单位）。 | `480` |
| `DEMO_USERNAME` | 管理员登录用户名。 | `admin` |
| `DEMO_PASSWORD` | 管理员登录密码。 | `vigil2025` |
| `SMTP_HOST` | 目标 SMTP 邮件服务器的主机地址。 | `smtp.gmail.com` |
| `SMTP_PORT` | 目标 SMTP 邮件服务器的端口。 | `587` |
| `SMTP_USER` | 用于 SMTP 身份验证的用户名。 | `""` |
| `SMTP_PASSWORD` | 用于 SMTP 身份验证的应用程序密码。 | `""` |
| `ALERT_EMAIL_TO` | 接收警报的电子邮件地址。 | `(SMTP_USER)` |
| `METRICS_INTERVAL_SECONDS` | 指标聚合计时的调度间隔（秒）。 | `5` |
| `ANOMALY_MIN_INTERVAL` | 随机异常注入之间的最小延迟（秒）。 | `30` |
| `ANOMALY_MAX_INTERVAL` | 随机异常注入之间的最大延迟（秒）。 | `60` |
## 用法
1. **登录**：在 `http://localhost:3000` 访问 Web UI，并使用由 `DEMO_USERNAME` / `DEMO_PASSWORD` 定义的凭据（默认值：`admin` / `vigil2025`）进行登录。
2. **注入异常**：点击右上角标题栏上的 **注入异常** 按钮，手动将 `high_latency` 错误注入到模拟的 `checkout-api` 中。
3. **跟踪事件**：在 **事件** 部分观察日志、指标和传入的调查。如果问题影响到 `checkout-api` 且置信度 $\ge 80\%$，引擎将自动进行缓解并显示结果。如果它影响到任何其他服务或置信度较低，它将等待人工批准。
4. **手动批准**：对于已呼叫的事件，请查看推理时间线并点击 **批准动作** 按钮将其解决。
## 文件夹结构
```
.
├── auth.py # JWT credential authentication checks
├── database.py # PostgreSQL database initialization & SQLAlchemy ORM mapping
├── Dockerfile # Build configuration for running the FastAPI application
├── docker-compose.yml # Configuration for deploying Postgres DB and API service
├── install_pgvector.ps1 # Powershell installation script for pgvector (Windows local)
├── main.py # FastAPI application entry points, endpoints & scheduler tasks
├── metrics_loop.py # Background metric collection & threshold rule evaluator
├── notifications.py # SMTP email paging and fallback logging mechanisms
├── phase1_agent.py # SRE agent tool-calling loop utilizing the Groq SDK
├── policy_engine.py # Safety allowlists, mock actions, and RAG compilation
├── requirements.txt # List of Python dependencies
├── seed.py # Seeding script for services, deploys, and vector data
├── smoke_test.py # Local endpoint integration verification test script
├── docs/ # Architecture diagrams, reports, assessment, and roadmaps
└── frontend/ # React dashboard frontend project files
├── package.json # Node.js dependencies
└── src/ # React component source code
```
## 架构
Vigil 使用解耦的 pipeline 来防止 LLM 幻觉导致不受控的基础设施操作：
1. **指标引擎与规则**：当指标突破阈值时触发事件，并设置数据库级别的锁。
2. **阶段 1（诊断代理）**：使用严格的只读工具（`get_metrics`、`get_logs`、`get_recent_deploys`、`search_similar_incidents`）探索诊断。在 LLM 上下文中未定义任何执行操作的工具。
3. **阶段 2（安全策略）**：使用确定性 Python 引擎评估 LLM 的诊断 JSON 输出。如果满足安全标准（服务白名单、置信度阈值），它将执行模拟操作。否则，它将向人工操作员发送呼叫。
4. **人工审核**：人工操作员可以在 React 控制台上查看时间线并手动批准恢复操作。
有关详细的时序图、系统组件映射和数据流可视化，请参阅[架构图文档](file:///c:/Users/navee/OneDrive/Desktop/Vigil/docs/ARCHITECTURE_DIAGRAMS.md)。
## 未来增强功能
* 将模拟操作过渡到实际的云服务商集成（例如 AWS ECS/EKS 任务重启）。
* 用分布式存储模型（例如 Redis）替换内存中的异常和冷却变量。
* 通过在 thread 执行器或微服务中执行 embedding 计算，消除 API 事件循环中阻塞 CPU 的调用。
* 实施基于角色的授权，以保护管理 API 路由。
## 贡献指南
1. **Fork 仓库**：确保将更改提交到功能特性分支。
2. **Linting 与格式化**：对于 Python 代码，请遵循 pep8 规范。
3. **依赖注入**：将新的后端包直接添加到 `requirements.txt` 中。
4. **测试覆盖率**：在合并前运行 `smoke_test.py` 以确保核心 endpoint 成功运行。
标签：AV绕过, FastAPI, LLM Agent, PostgreSQL, React, Syscalls, 检索增强生成, 测试用例, 自动化运维, 自定义请求头, 请求拦截, 逆向工具