Zappsec/warroom-agent
GitHub: Zappsec/warroom-agent
AI 驱动的安全事件响应编排平台，通过 Claude 大模型实现自动分类和操作规划，并利用 Auth0 CIBA 实现敏感修复操作的人工审批闭环。
Stars: 0 | Forks: 1
# WarRoom Agent
由 AI 驱动的安全事件作战室，可协调检测、分类、团队协作和修复工作，并使用 Auth0 CIBA（客户端发起的后端认证）实现敏感操作的人工审批。
为 **Auth0 黑客松** 构建。
## 目录
- [功能说明](#what-it-does)
- [技术栈](#tech-stack)
- [前置条件](#prerequisites)
- [本地开发环境搭建](#local-development-setup)
- [EC2 部署（Amazon Linux 2023）](#ec2-deployment-amazon-linux-2023)
- [环境变量](#environment-variables)
- [API 端点](#api-endpoints)
- [项目结构](#project-structure)
- [许可证](#license)
## 功能说明
WarRoom Agent 监控 Slack 频道中的安全事件，使用 Claude AI 对事件进行分类并规划响应操作，通过 Slack/Zoom/日历/邮件协调团队，并执行修复工作。在接触敏感系统（如 GitHub 仓库）之前，需要通过带外人工审批（使用 Auth0 CIBA）。
### 核心功能
- **AI 事件分类** - Claude LLM 分析原始事件文本，确定严重程度（P1/P2/P3）、受影响域、受影响系统和置信度分数
- **自动响应人匹配** - 根据事件域、专业知识和可用性匹配值班响应人
- **已知问题匹配** - 在历史知识库中搜索类似的过去事件，并建议修复步骤
- **AI 操作规划** - 生成协调操作：Zoom 作战室、日历桥接、Slack 私信、邮件升级和 GitHub 配置修复
- **Auth0 CIBA 审批流程** - 敏感的 GitHub 修复操作会触发后端推送通知，发送给修复负责人进行带外审批后再执行
- **Auth0 FGA（细粒度授权）** - 基于角色的访问检查，用于审批和执行操作
- **交互式 AI 聊天** - 面向事件的聊天助手，提供运维手册、诊断和根因分析
- **完整审计追踪** - 记录每一个 AI 决策、人工审批和操作执行
- **演示控制台** - 注入测试事件以完整演示工作流程
### CIBA 流程
```
Operator approves sensitive action
--> Backend initiates Auth0 CIBA backchannel request
--> Auth0 sends push notification to remediation owner
--> Owner approves out-of-band (phone/email)
--> Backend receives token, validates scopes
--> Action executes with approved owner's context
--> Full audit trail recorded
```
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| **前端** | React 18, TypeScript, Vite, TailwindCSS, Radix UI (shadcn) |
| **后端** | FastAPI (Python), SQLAlchemy, SQLite |
| **AI/LLM** | Anthropic Claude (claude-sonnet-4-5), LangGraph 工作流编排 |
| **认证** | Auth0 (OAuth2/OIDC), Auth0 CIBA, Auth0 FGA |
| **集成** | Slack, Zoom, Google Calendar, Gmail SMTP, GitHub |
| **部署** | GitHub Actions CI/CD, AWS EC2, Nginx, systemd |
## 前置条件
- [**Node.js** 20+](https://nodejs.org/en/download/)
- [**Python** 3.12+](https://www.python.org/downloads/)
- [**npm** 9+](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)（随 Node.js 一起提供）
- [**Git**](https://git-scm.com/downloads)
需要以下外部账户（详细设置指南见 [integrations-setup.md](integrations-setup.md)）：
- Auth0 租户（已配置 CIBA 和 FGA）
- Anthropic API 密钥
- Slack 工作区 + 机器人应用
- Zoom 服务端到服务端 OAuth 应用
- Google Cloud 服务账号（日历 API）
- Gmail 应用密码（或其它 SMTP 提供商）
- GitHub 个人访问令牌
## 本地开发环境搭建
### 1. 克隆仓库
```
git clone git@github.com:Zappsec/warroom-agent.git
cd warroom-agent
```
### 2. 前端设置
```
npm install
```
在项目根目录创建 `.env.local` 文件（此文件会被 git 忽略，供 Vite 本地开发使用）：
```
cp .env.example .env.local
nano .env.local
```
```
VITE_AUTH0_DOMAIN=dev-xxxxxxxxxxxx.us.auth0.com
VITE_AUTH0_CLIENT_ID=
VITE_AUTH0_AUDIENCE=
VITE_AUTH0_SCOPE=openid profile email offline_access read:incidents read:audit read:integrations approve:actions execute:actions admin:config
```
启动开发服务器：
```
npm run dev
```
前端将在 `http://localhost:8080` 可访问。
### 3. 后端设置
#### 创建 Python 虚拟环境
```
cd backend
python3.12 -m venv venv
```
#### 激活并安装依赖
```
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```
#### 配置环境变量
复制示例文件创建 `backend/.env`，并填写您的密钥：
```
cp .env.example .env
nano .env
```
获取每个密钥的方法见 [integrations-setup.md](integrations-setup.md)。完整的环境变量列表见下文[环境变量](#environment-variables)部分。
### 4. 初始化数据库并启动后端
```
# 在 backend/ 目录下，激活 venv
python -m scripts.seed_data
uvicorn app.main:app --reload --port 8000
```
后端 API 将在 `http://localhost:8000` 可访问。
### 5. 验证
- 打开 `http://localhost:8080` - 您应该看到登录页面
- 使用 Auth0 登录
- 导航到演示控制台（`/demo`）注入测试事件
- 观察 AI 分类、规划操作并通过审批流程
## EC2 部署（Amazon Linux 2023）
本节提供可选的便捷脚本，用于简化在运行 **Amazon Linux 2023** 的 AWS EC2 实例上部署 WarRoom Agent。这些脚本会安装所有基础依赖（Node.js、Python、Nginx 等），配置 systemd 服务，设置 SSL，并为通过 GitHub Actions CI/CD 管道进行自动部署做好准备。如果您要部署到不同的环境，可以将这些脚本作为参考。
### 一次性服务器设置
1. **启动 EC2 实例**（Amazon Linux 2023，t3.small 或更大）
2. **配置安全组** - 允许入站端口：**22**（SSH）、**80**（HTTP）、**443**（HTTPS）
3. **在 `scripts/ec2-setup-ssl.sh`（第 16 行）更新 EC2 IP**，填入您实例的公网 IP
4. **SSH 登录并运行设置脚本：**
```
ssh -i your-key.pem ec2-user@
# 先上传脚本（或克隆 repo）
cd ~/warroom/scripts
chmod +x ec2-setup.sh ec2-setup-ssl.sh
# 步骤 1：基础安装 - 安装 Node.js、Python、Nginx，创建 venv，配置 systemd 服务
sudo ./ec2-setup.sh
# 步骤 2：SSL + Nginx 反向代理（Auth0 SPA SDK 需要）
sudo ./ec2-setup-ssl.sh
```
5. **在服务器上填写 `.env` 文件：**
```
nano ~/warroom/backend/.env
nano ~/warroom/.env
```
6. **初始化数据库：**
```
cd ~/warroom/backend
source venv/bin/activate
python -m scripts.seed_data
```
7. **启动服务：**
```
sudo systemctl start warroom-backend
sudo systemctl restart nginx
```
8. **在 Auth0 仪表板更新您的 EC2 URL：**
- 允许的回调 URL：`https:///integrations`
- 允许的登出 URL：`https://`
- 允许的 Web 来源：`https://`
### CI/CD 管道（自动部署）
每次推送到 `main` 分支都会触发 GitHub Actions 管道（`.github/workflows/deploy.yml`），自动执行以下操作：
1. 使用 Vite 构建前端（从 GitHub Secrets 注入 Auth0 环境变量）
2. 从 `BACKEND_SECRET` 写入 `backend/.env`
3. 通过 rsync 将代码和构建的 `dist/` 同步到 EC2
4. 在虚拟环境中安装/更新 Python 依赖
5. 重启 `warroom-backend` 和 `nginx`
**必需的 GitHub Secrets**（设置 > Secrets 和变量 > Actions）：
| Secret | 说明 |
|--------|------------|
| `EC2_SSH_PRIVATE_KEY` | 您的 `.pem` 密钥文件内容 |
| `EC2_HOST` | EC2 公网 IP 地址 |
| `EC2_USER` | `ec2-user` |
| `VITE_AUTH0_DOMAIN` | Auth0 租户域（例如 `dev-xxxxx.us.auth0.com`） |
| `VITE_AUTH0_CLIENT_ID` | Auth0 SPA 应用客户端 ID |
| `VITE_AUTH0_AUDIENCE` | `https://warroom-api` |
| `VITE_AUTH0_SCOPE` | `openid profile email offline_access read:incidents read:audit read:integrations approve:actions execute:actions admin:config` |
| `BACKEND_ENV` | `backend/.env` 的完整内容（所有密钥） |
### 常用 EC2 命令
```
# 检查服务状态
sudo systemctl status warroom-backend
sudo systemctl status nginx
# 查看后端日志
journalctl -u warroom-backend -f
# 健康检查
curl -k https://localhost/health
# 修改配置后重启
sudo systemctl restart warroom-backend
sudo systemctl restart nginx
```
## 环境变量
### 前端（`.env.local` 用于本地开发，GitHub Secrets 用于 CI/CD）
| 变量 | 说明 |
|----------|------------|
| `VITE_AUTH0_DOMAIN` | Auth0 租户域（例如 `dev-xxxxx.us.auth0.com`） |
| `VITE_AUTH0_CLIENT_ID` | Auth0 SPA 应用客户端 ID |
| `VITE_AUTH0_AUDIENCE` | Auth0 API 标识符（例如 `https://warroom-api`） |
| `VITE_AUTH0_SCOPE` | Auth0 作用域：`openid profile email offline_access read:incidents readaudit read:integrations approve:actions execute:actions admin:config` |
### 后端（`backend/.env`）
| 变量 | 说明 |
|----------|------------|
| **数据库** | |
| `DATABASE_URL` | 数据库连接字符串（默认：`sqlite:///./warroom.db`） |
| **应用** | |
| `APP_ENV` | `development` 或 `production` |
| `LOG_LEVEL` | 日志级别（默认：`INFO`） |
| `JWT_SECRET` | JWT 签名的随机密钥 |
| **Anthropic Claude** | |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 |
| `ANTHROPIC_MODEL` | 模型名称（默认：`claude-sonnet-4-5`） |
| **Slack** | |
| `SLACK_BOT_TOKEN` | Slack 机器人令牌（`xoxb-...`） |
| `SLACK_SIGNING_SECRET` | Slack webhook 签名密钥 |
| `SLACK_CHANNEL_ID` | 用于轮询事件的频道 ID |
| `SLACK_POLL_INTERVAL` | 轮询间隔秒数（默认：`10`） |
| **Zoom** | |
| `ZOOM_CLIENT_ID` | Zoom 服务端到服务端 OAuth 客户端 ID |
| `ZOOM_CLIENT_SECRET` | Zoom 服务端到服务端 OAuth 客户端密钥 |
| `ZOOM_ACCOUNT_ID` | Zoom 账户 ID |
| **Google 日历** | |
| `GOOGLE_SERVICE_ACCOUNT_KEY` | Google 服务账号 JSON 密钥文件路径 |
| **邮件（SMTP）** | |
| `SMTP_HOST` | SMTP 服务器（默认：`smtp.gmail.com`） |
| `SMTP_PORT` | SMTP 端口（默认：`587`） |
| `SMTP_USER` | SMTP 用户名/邮箱 |
| `SMTP_PASS` | SMTP 密码或应用密码 |
| **Auth0 核心** | |
| `AUTH0_DOMAIN` | Auth0 租户域 |
| `AUTH0_CLIENT_ID` | Auth0 M2M 应用客户端 ID |
| `AUTH0_CLIENT_SECRET` | Auth0 M2M 应用客户端密钥 |
| `AUTH0_AUDIENCE` | Auth0 API 受众 |
| **Auth0 Token Vault** | |
| `AUTH0_CUSTOM_API_CLIENT_ID` | 自定义 API 客户端 ID |
| `AUTH0_CUSTOM_API_CLIENT_SECRET` | 自定义 API 客户端密钥 |
| `AUTH0_TOKEN_ENDPOINT` | Auth0 令牌端点 URL |
| **Auth0 Connections** | |
| `AUTH0_SLACK_CONNECTION_NAME` | Slack 社交连接名称 |
| `AUTH0_GOOGLE_CONNECTION_NAME` | Google 社交连接名称 |
| `AUTH0_GITHUB_CONNECTION_NAME` | GitHub 社交连接名称 |
| **Auth0 FGA** | |
| `FGA_API_URL` | FGA API URL |
| `FGA_STORE_ID` | FGA 存储 ID |
| `FGA_MODEL_ID` | FGA 授权模型 ID |
| `FGA_CLIENT_ID` | FGA 客户端 ID |
| `FGA_CLIENT_SECRET` | FGA 客户端密钥 |
| `FGA_API_TOKEN_ISSUER` | FGA 令牌发行者 |
| `FGA_API_AUDIENCE` | FGA API 受众 |
| **Auth0 CIBA** | |
| `AUTH0_CIBA_ENABLED` | 启用/禁用 CIBA（`true`/`false`） |
| `AUTH0_CIBA_CLIENT_ID` | CIBA 应用客户端 ID |
| `AUTH0_CIBA_CLIENT_SECRET` | CIBA 应用客户端密钥 |
| `AUTH0_CIBA_AUDIENCE` | CIBA 受众 |
| `AUTH0_CIBA_SCOPE` | CIBA 作用域（默认：`openid execute:remediation`） |
| `AUTH0_CIBA_REQUESTED_EXPIRY` | CIBA 请求过期秒数（默认：`300`） |
| `AUTH0_CIBA_DEFAULT_POLL_INTERVAL` | 轮询间隔秒数（默认：`5`） |
| `AUTH0_APP_REMEDIATION_OWNER_SUB` | 应用修复负责人的 Auth0 用户 ID |
| `AUTH0_NETWORK_REMEDIATION_OWNER_SUB` | 网络修复负责人的 Auth0 用户 ID |
| **GitHub 修复** | |
| `GITHUB_APP_REMEDIATION_REPO` | 应用配置修复仓库（`org/repo`） |
| `GITHUB_APP_REMEDIATION_PATH` | 应用修复仓库中的文件路径 |
| `GITHUB_NETWORK_REMEDIATION_REPO` | 网络策略修复仓库（`org/repo`） |
| `GITHUB_NETWORK_REMEDIATION_PATH` | 网络修复仓库中的文件路径 |
| **CORS** | |
| `CORS_ORIGINS` | 允许的来源 JSON 数组 |
## API 端点
| 方法 | 路径 | 说明 |
|--------|------|-------------|
| `GET` | `/api/incidents` | 列出事件（按严重程度、状态、搜索筛选） |
| `GET` | `/api/incidents/{id}` | 获取事件的完整上下文 |
| `POST` | `/api/incidents/inject` | 注入演示事件 |
| `GET` | `/api/actions` | 列出计划操作 |
| `POST` | `/api/actions/{id}/approve` | 审批操作（FGA 门控） |
| `POST` | `/api/actions/{id}/deny` | 拒绝操作（FGA 门控） |
| `POST` | `/api/actions/{id}/prepare-execute` | 准备执行（敏感操作会路由到 CIBA） |
| `POST` | `/api/actions/{id}/ciba/start` | 启动 CIBA 后端认证 |
| `GET` | `/api/actions/{id}/ciba/status` | 轮询 CIBA 审批状态 |
| `GET` | `/api/audit` | 审计追踪（按事件、操作者、事件筛选） |
| `GET` | `/api/integrations` | 列出集成连接 |
| `POST` | `/api/integrations/{id}/reconnect` | 重新连接集成 |
| `POST` | `/api/chat` | 面向事件的 AI 聊天 |
| `GET` | `/health` | 健康检查 |
## 项目结构
```
warroom-agent/
├── .github/workflows/
│ └── deploy.yml # CI/CD pipeline
├── backend/
│ ├── app/
│ │ ├── agents/ # LangGraph workflow orchestration
│ │ ├── api/ # FastAPI route handlers
│ │ ├── integrations/ # Slack, Zoom, Calendar, Email, GitHub, Auth0 adapters
│ │ ├── models/ # SQLAlchemy models
│ │ ├── security/ # JWT verification, FGA checks, CIBA enforcement
│ │ ├── services/ # Business logic (classifier, planner, CIBA, etc.)
│ │ └── main.py # FastAPI app entry point
│ ├── scripts/ # DB seed scripts
│ └── requirements.txt
├── src/ # React frontend (TypeScript)
│ ├── components/ # UI components (shadcn + custom)
│ ├── pages/ # Route pages
│ ├── hooks/ # Custom React hooks
│ └── lib/ # API client, Auth0 config
├── scripts/
│ ├── ec2-setup.sh # EC2 base setup
│ └── ec2-setup-ssl.sh # Nginx + SSL setup
├── package.json
├── vite.config.ts
└── tailwind.config.js
```
## 许可证
MIT
标签：AI安全, Amazon Linux 2023, API集成, Auth0 CIBA, Auth0 FGA, Chat Copilot, Claude AI, Client Initiated Backchannel Authentication, DLL 劫持, EC2部署, GitHub运维, HITL, Human-in-the-Loop, LLM安全应用, Python后端, Slack集成, SOAR, Zoom集成, 事件管理, 人工智能驱动安全, 人类在环, 可观测性, 大语言模型, 安全事件分诊, 安全事件响应, 安全编排自动化响应, 安全运营中心, 实时通知, 审批工作流, 审计日志, 细粒度授权, 网络映射, 自动化协调, 自动化攻击, 逆向工具