ihabkhaled/auraspear-backend
GitHub: ihabkhaled/auraspear-backend
基于 NestJS 构建的多租户 AI 安全运营平台后端，通过统一 API 编排 Wazuh、Graylog、MISP 等安全工具，为 SOC 团队提供告警管理、事件响应、威胁狩猎、SOAR 自动化和 AI 辅助分析的一体化工作流。
Stars: 0 | Forks: 0
# AuraSpear SOC 后端
一个基于 NestJS 11 构建的多租户 **安全信息与事件管理 (SIEM) 服务于前端的后端** API。通过告警管理、案例追踪、威胁狩猎、威胁情报、连接器集成和 AI 辅助分析等功能为 AuraSpear SOC 仪表盘提供支持——所有功能均限定在隔离的租户范围内。
本仓库中的运维仪表盘契约保持查询驱动和可重用性，以便前端能够基于真实的后端聚合数据构建高管和操作员视图，而不是依赖页面本地的占位符计算逻辑。
## 目录
- [技术栈](#tech-stack)
- [架构](#architecture)
- [快速入门](#getting-started)
- [环境变量](#environment-variables)
- [项目结构](#project-structure)
- [API 模块](#api-modules)
- [身份验证与授权](#authentication--authorization)
- [安全加固](#security-hardening)
- [连接器集成](#connector-integrations)
- [数据库与种子数据](#database--seed-data)
- [Docker](#docker)
- [NPM 脚本](#npm-scripts)
- [代码质量](#code-quality)
## 技术栈
| 类别 | 技术 | 版本 |
| ---------------- | ------------------------ | ---- |
| 运行时 | Node.js | 22 |
| 框架 | NestJS | 11 |
| 语言 | TypeScript (严格模式) | 5.7 |
| ORM | Prisma | 6 |
| 数据库 | PostgreSQL | 16 |
| 缓存 | Redis (ioredis) | 7 |
| 校验 | Zod | 3.23 |
| 身份验证 | JWT + JWKS | 9 |
| 日志 | nestjs-pino | 4 |
| 限流 | @nestjs/throttler | 6 |
| 安全标头 | Helmet | 8 |
| API 文档 | @nestjs/swagger | 11 |
## 架构
```
Frontend (Next.js) ──► BFF (NestJS) ──┬──► Wazuh Manager (SIEM)
├──► Wazuh Indexer (Alert search)
├──► Graylog (Log management)
├──► Velociraptor (EDR / DFIR)
├──► Grafana (Dashboards)
├──► InfluxDB (Time-series)
├──► MISP (Threat intel)
├──► Shuffle (SOAR)
├──► AWS Bedrock (AI analysis)
└──► PostgreSQL + Redis (State & cache)
```
### 请求管道
每个请求都会经过一个守卫链：
1. **ThrottlerGuard** — 基于 IP 的限流
2. **AuthGuard** — JWT 验证 + 用户激活状态检查 + Token 黑名单
3. **TenantGuard** — 租户上下文验证
4. **PermissionsGuard** — 基于动态权限的授权（取代静态 RolesGuard）
5. **AuditInterceptor** — 变更日志记录（异步）
### 分层
```
Controller → Service → Repository → Prisma
↓
Utilities
```
- **Controllers** — HTTP 路由、验证、响应。不包含业务逻辑。
- **Services** — 精简的编排器。调用 repository 和 utility 函数。
- **Repositories** — 纯 Prisma 数据访问。每个查询都通过 `tenantId` 进行范围限定。
- **Utilities** — 所有业务逻辑：映射器、构建器、验证器、格式化器。
## 快速入门
### 前置条件
- Node.js >= 18, npm >= 9
- Docker + Docker Compose
### 快速启动
```
# 安装依赖项
npm install
# 配置环境
cp .env.example .env
# 编辑 .env — 设置 DATABASE_URL, JWT_SECRET, CONFIG_ENCRYPTION_KEY, SEED_DEFAULT_PASSWORD
# 启动基础设施 (Postgres + Redis + PgAdmin)
npm run docker:infra
# 运行 migrations 和 seed
npm run prisma:migrate
npm run prisma:seed
# 启动开发服务器
npm run start:dev
```
- **API**: `http://localhost:4000/api/v1`
- **Swagger**: `http://localhost:4000/api/docs` (仅限开发环境)
- **PgAdmin**: `http://localhost:5050`
### 生产环境
```
npm run build
npm start # Runs migrations + seed + production server
```
## 环境变量
将 `.env.example` 复制为 `.env`。所有变量均在那里有详细说明。
### 必需项
| 变量 | 描述 |
| ----------------------- | ------------------------------------------------ |
| `DATABASE_URL` | PostgreSQL 连接字符串 |
| `JWT_SECRET` | 用于 HS256 签名的最少 64 位十六进制字符 |
| `CONFIG_ENCRYPTION_KEY` | 用于 AES-256-GCM 的恰好 64 位十六进制字符 (32 字节) |
| `SEED_DEFAULT_PASSWORD` | 种子管理员使用的强密码（无备用方案） |
### 应用配置（含默认值）
| 变量 | 默认值 | 描述 |
| --------------------- | ----------------------- | ------------------------------ |
| `PORT` | `4000` | HTTP 服务器端口 |
| `NODE_ENV` | `production` | `production` / `development` |
| `LOG_LEVEL` | `info` | Pino 日志级别 |
| `CORS_ORIGINS` | `http://localhost:3000` | 逗号分隔的允许来源 |
| `JWT_ACCESS_EXPIRY` | `15m` | 访问令牌 TTL |
| `JWT_REFRESH_EXPIRY` | `7d` | 刷新令牌 TTL |
| `REDIS_HOST` | `localhost` | Redis 主机 |
| `REDIS_PORT` | `6379` | Redis 端口 |
### OIDC（可选 — 启用则需全部配置）
| 变量 | 描述 |
| -------------------- | -------------------------------- |
| `OIDC_AUTHORITY` | Entra ID 颁发者 URL |
| `OIDC_CLIENT_ID` | OAuth 客户端 ID |
| `OIDC_REDIRECT_URI` | 登录后重定向 URI |
| `OIDC_JWKS_URI` | 用于 RS256 验证的 JWKS 端点 |
### 连接器 URL（可选 — 在数据库中按租户覆盖）
`WAZUH_MANAGER_URL`, `WAZUH_INDEXER_URL`, `GRAYLOG_BASE_URL`, `VELOCIRAPTOR_BASE_URL`, `GRAFANA_BASE_URL`, `INFLUXDB_BASE_URL`, `MISP_BASE_URL`, `SHUFFLE_BASE_URL`
### AWS Bedrock（可选）
`AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_BEDROCK_MODEL_ID`
### 种子连接器凭证（可选）
`SEED_WAZUH_PASSWORD`, `SEED_WAZUH_INDEXER_PASSWORD`, `SEED_GRAYLOG_PASSWORD`, `SEED_VELOCIRAPTOR_PASSWORD`, `SEED_GRAFANA_API_KEY`, `SEED_INFLUXDB_TOKEN`, `SEED_MISP_AUTH_KEY`, `SEED_SHUFFLE_API_KEY`
## 项目结构
```
src/
├── main.ts # Bootstrap (Helmet, CORS, Swagger, rate limits)
├── app.module.ts # Root module
├── common/
│ ├── decorators/ # @CurrentUser, @RequirePermission, @Public, @TenantId
│ ├── filters/ # GlobalExceptionFilter (error sanitization)
│ ├── guards/ # AuthGuard, TenantGuard, PermissionsGuard
│ ├── interceptors/ # AuditInterceptor
│ ├── interfaces/ # JwtPayload, AuthenticatedRequest
│ ├── pipes/ # ZodValidationPipe
│ ├── enums/ # Shared enums
│ ├── constants/ # Shared constants
│ └── utils/ # encryption, mask, ssrf, es-sanitize, query
├── config/ # env.validation.ts (Zod env schema)
├── modules/ # 32 API modules (see below)
└── prisma/ # PrismaModule, PrismaService
```
### 模块结构
每个模块遵循以下模式：
```
src/modules//
├── .module.ts
├── .controller.ts
├── .service.ts
├── .repository.ts
├── .utilities.ts
├── .types.ts
├── .enums.ts
├── .constants.ts
└── dto/
└── .dto.ts
```
## API 模块
| 模块 | 描述 |
| ------------------------ | ---------------------------------------------------------------- |
| **auth** | 登录，JWT 刷新，登出，Token 黑名单，带权限的 /me 接口 |
| **alerts** | 告警搜索、分诊、调查、摄取、批量操作 |
| **cases** | 案例 CRUD、笔记、时间线、关联告警、工件 |
| **role-settings** | 动态 RBAC 权限矩阵管理 |
| **case-cycles** | 案例周期管理 |
| **incidents** | 事件生命周期管理 |
| **hunts** | 结合 AI 的威胁狩猎会话 |
| **intel** | MISP 威胁情报、IOC 搜索与匹配 |
| **connectors** | 连接器 CRUD、测试、开关（9 种类型） |
| **connector-sync** | 连接器数据同步 |
| **connector-workspaces** | 特定工作区的操作（Wazuh、Graylog） |
| **dashboards** | KPI、趋势、MITRE 统计、管道健康状况 |
| **data-explorer** | 跨连接器的日志/事件搜索 |
| **correlation** | 关联规则引擎 |
| **detection-rules** | 检测规则管理 |
| **normalization** | 日志规范化管道 |
| **attack-paths** | 攻击路径分析 |
| **cloud-security** | 云账号发现 |
| **compliance** | 合规框架追踪 |
| **vulnerabilities** | 漏洞追踪 |
| **ueba** | 用户与实体行为分析 |
| **soar** | Shuffle SOAR 剧本管理 |
| **ai-agents** | AI 代理管理 |
| **ai** | AI 驱动的分析 (Bedrock) |
| **reports** | 报告生成（PDF、CSV、HTML） |
| **notifications** | WebSocket 实时通知 |
| **tenants** | 多租户 CRUD |
| **users** | 用户资料与偏好设置 |
| **audit-logs** | 审计追踪查询 |
| **app-logs** | 应用日志 |
| **health** | 系统健康检查 |
| **system-health** | 详细服务监控 |
## 身份验证与授权
### Token 生命周期
1. **登录** — 签发访问令牌 (15分钟) + 刷新令牌 (7天)，两者均包含 `jti` 和 `tokenType`。响应包含基于租户和角色的 `permissions[]` 数组
2. **刷新** — 验证 Token 类型 + 黑名单，签发新 Token 对，并将旧的刷新 JTI 加入黑名单
3. **登出** — 将访问和刷新的 JTI 都加入 Redis 黑名单
4. **每次请求** — 验证 JWT，检查 `tokenType === 'access'`，检查 Redis 黑名单，验证用户是否处于激活状态
### 角色层级
| 角色 | 级别 | 描述 |
| -------------------- | ---- | ---------------- |
| `GLOBAL_ADMIN` | 1 | 平台管理员 |
| `TENANT_ADMIN` | 2 | 租户管理员 |
| `SOC_ANALYST_L2` | 3 | 高级分析师 |
| `THREAT_HUNTER` | 4 | 威胁猎人 |
| `SOC_ANALYST_L1` | 5 | 初级分析师 |
| `EXECUTIVE_READONLY` | 6 | 只读高管 |
### 动态 RBAC 与权限系统
AuraSpear 使用**数据库支持的权限矩阵**取代了静态角色检查。该系统由两个 Prisma 模型组成 — `PermissionDefinition`（包含约 70 个细粒度权限的目录）和 `RolePermission`（按租户、按角色的授权表）。
**关键行为：**
- 所有端点上的 **`@RequirePermission()` 装饰器** 取代了旧的 `@Roles()` 方法。`PermissionsGuard` 解析当前用户的角色 + 租户，查找已授予的权限，并允许或拒绝访问。
- **GLOBAL_ADMIN 始终拥有完全访问权限** — 守卫会对此角色进行短路处理。
- **具有 5 分钟 TTL 的内存缓存** 用于权限查找，避免每次请求都访问数据库。
- **登录和 `/auth/me` 会返回 `permissions[]` 数组**，以便前端可以根据实际的权限集来控制 UI 的可见性。
#### 权限类别（约 70 个权限）
权限遵循 `MODULE_ACTION` 命名约定。示例：
| 权限 | 描述 |
| ------------------------ | ---------------------------- |
| `ALERTS_VIEW` | 查看告警列表和详情 |
| `ALERTS_ESCALATE` | 将告警升级为事件 |
| `ALERTS_BULK_ACKNOWLEDGE` | 批量确认告警 |
| `ALERTS_BULK_CLOSE` | 批量关闭告警 |
| `INCIDENTS_VIEW` | 查看事件列表和详情 |
| `INCIDENTS_CHANGE_STATUS` | 更改事件状态 |
| `INCIDENTS_ADD_TIMELINE` | 添加时间线条目 |
| `CASES_CREATE` | 创建新案例 |
| `HUNTS_EXECUTE` | 执行威胁狩猎会话 |
| `CONNECTORS_MANAGE` | 创建/更新/删除连接器 |
| `USERS_MANAGE` | 管理租户用户 |
| `ROLE_SETTINGS_VIEW` | 查看角色权限矩阵 |
| `ROLE_SETTINGS_MANAGE` | 更新角色权限 |
#### 角色设置 API
| 方法 | 端点 | 描述 |
| ---- | ----------------------- | ---------------------------------------- |
| GET | `/role-settings` | 获取完整权限矩阵 |
| PUT | `/role-settings` | 更新角色权限（仅限 GLOBAL_ADMIN） |
| POST | `/role-settings/reset` | 将权限重置为种子默认值 |
数据填充程序会为所有角色填充默认权限，确保每次全新部署都有一个可用的 RBAC 基线。
### 批量告警操作
| 方法 | 端点 | 描述 |
| ---- | ------------------------- | ---------------------- |
| POST | `/alerts/bulk/acknowledge` | 批量确认多个告警 | POST | `/alerts/bulk/close` | 批量关闭多个告警 |
这两个端点都接受一个告警 ID 数组，并且需要相应的批量操作权限。
### GLOBAL_ADMIN 租户切换
GLOBAL_ADMIN 用户可以发送 `X-Tenant-Id` 标头来切换租户上下文。身份验证守卫会覆盖 `request.user.tenantId`，以便所有 `@TenantId()` 装饰器自动返回切换后的租户。
### 用户管理
- **软删除**：`status: 'inactive'`（可恢复）
- **封禁**：`status: 'suspended'`（可解封）
- **受保护用户**：种子 GLOBAL_ADMIN 拥有 `isProtected: true` 属性 — 无法被删除、封禁或更改角色
## 安全加固
| 功能 | 实现 |
| -------------------------- | ---------------------------------------------------------------- |
| **限流** | 分层：身份验证 5次/分钟，CRUD 30次/分钟，批量 5次/分钟，AI 10次/分钟 |
| **Token 撤销** | 由 Redis 支持的带 TTL 的 JTI 黑名单 |
| **静态加密** | 使用 AES-256-GCM 加密连接器配置 |
| **SSRF 防护** | 输入时的 URL 验证 + 阻止私有 IP |
| **ES 查询清理** | 剥离 `script`、`_search`、`_mapping`、`_cluster` 模式 |
| **时序攻击防护** | 针对缺失用户进行常量时间 bcrypt 比较 |
| **错误清理** | 剥离文件路径，将消息截断为 500 个字符 |
| **安全标头** | Helmet (CSP, HSTS 1年, X-Frame-Options: DENY) |
| **请求体大小限制** | 全局 1MB，每个 JSON 字段 64KB |
| **请求追踪** | X-Request-ID 中间件（每个请求生成一个 UUID） |
| **密码脱敏** | Pino `redact` 数组覆盖日志中的所有凭证字段 |
| **审计日志** | 所有变更通过 AuditInterceptor 记录 |
| **Source maps** | 在生产环境中禁用 |
| **环境变量验证** | Zod schema 拒绝零熵密钥及生产环境中的 localhost |
## 连接器集成
| 连接器 | 用途 | 认证类型 |
| ------------ | ------------------ | ----------------- |
| Wazuh Manager | SIEM 告警与代理 | 用户名/密码 |
| Wazuh Indexer | OpenSearch 日志搜索 | 用户名/密码 |
| Graylog | 日志管理 | 用户名/密码 |
| Velociraptor | EDR / DFIR | 用户名/密码 |
| Grafana | 指标仪表盘 | API Key |
| InfluxDB | 时间序列数据 | Token |
| MISP | 威胁情报 | Auth Key |
| Shuffle | SOAR 工作流 | API Key |
| AWS Bedrock | AI 分析 | IAM 凭证 |
所有连接器配置均使用 AES-256-GCM 加密，并在存储前使用按类型划分的 Zod schema 进行验证。
## 数据库与种子数据
### Schema
通过 Prisma 使用 PostgreSQL，包含 20 多个模型，包括：`Tenant`、`TenantUser`、`TenantMembership`、`ConnectorConfig`、`Alert`、`Case`、`CaseNote`、`CaseTimeline`、`HuntSession`、`HuntEvent`、`IntelIOC`、`IntelMispEvent`、`AuditLog`、`AiAuditLog`、`Incident`、`SavedQuery`、`PermissionDefinition`、`RolePermission`，以及用于合规、漏洞、UEBA、SOAR、检测规则和关联的领域特定模型。
### 数据填充
种子脚本是**幂等的** — 可以安全地多次运行。它们会创建：
- 具有确定性 UUID 的默认租户
- 受保护的 GLOBAL_ADMIN 用户
- 默认权限定义（约 70 个细粒度权限）
- 每个租户下所有角色的默认角色权限分配
- 示例连接器配置（凭证来自环境变量，无硬编码密码）
- 示例告警、案例和查找数据
```
npm run prisma:seed
```
## Docker
### Compose 文件
| 文件 | 用途 |
| ------------------------------ | ------------------------------------------------- |
| `docker-compose.yml` | 生产环境 (Postgres + Redis + Backend) |
| `docker-compose.dev.yml` | 开发环境 (+ PgAdmin，热重载) |
| `docker-compose.prod.yml` | 生产环境构建 (仅暴露端口 4000) |
| `docker-compose.infra.yml` | 仅基础设施 (Postgres + Redis + PgAdmin) |
| `docker-compose.connectors.yml` | 安全连接器 (Wazuh, Graylog 等) |
### 常用命令
```
npm run docker:infra # Start Postgres + Redis + PgAdmin
npm run docker:dev # Full dev environment
npm run docker:prod # Production build
npm run docker:connectors # Security tool containers
npm run docker:all # Everything
```
## NPM 脚本
```
# 开发
npm run start:dev # Dev with watch mode
npm run start:debug # Debug with watch
# 构建与生产
npm run build # Production build
npm start # Migrations + seed + production server
# 验证 (提交前运行)
npm run validate # typecheck + lint:strict + format:check
npm run validate:full # validate + tests + production build
npm run validate:fix # lint:fix + format
# 数据库
npm run prisma:migrate # Run migrations (dev)
npm run prisma:seed # Seed database
npm run prisma:studio # Open Prisma Studio
# 测试
npm test # Unit tests
npm run test:cov # With coverage
npm run test:e2e # End-to-end tests
```
## 贡献者指南
- 迁移与种子数据: [`docs/migrations-and-seeds.md`](./docs/migrations-and-seeds.md)
- 权限与角色: [`docs/permissions-and-roles.md`](./docs/permissions-and-roles.md)
- 添加连接器: [`docs/adding-connectors.md`](./docs/adding-connectors.md)
- AI 代理安全性: [`docs/ai-agent-safety.md`](./docs/ai-agent-safety.md)
- AI 自动化系统: [`docs/AI-AUTOMATION.md`](./docs/AI-AUTOMATION.md) -- 28 个代理目录、执行流程、配置与安全性
- AI 提供者路由: [`docs/AI-ROUTING.md`](./docs/AI-ROUTING.md) -- Bedrock/LLM APIs/OpenClaw 选择、回退、能力矩阵
- 权限参考: [`docs/PERMISSIONS.md`](./docs/PERMISSIONS.md) -- 涵盖 12 个角色的完整 136 项权限矩阵
- 贡献工作流: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
- 安装与本地环境: [`INSTALL.md`](./INSTALL.md)
## 代码质量
### 强制执行规则
- **禁止使用 `any`** — 请使用 `unknown`、泛型或适当的类型
- **禁止禁用 ESLint** — 必须修复根本原因
- **禁止使用 `console.log`** — 请使用 NestJS `Logger`
- **禁止使用原始字符串字面量** — 请使用枚举
- **禁止内联类型** — 所有类型必须位于 `*.types.ts` 文件中
- **禁止内联常量/枚举** — 所有定义必须位于 `*.constants.ts` / `*.enums.ts` 文件中
- **服务中禁止直接使用 Prisma** — 必须全部通过 repository
- **控制器中禁止包含业务逻辑** — 请委托给服务
- **repository 中禁止包含逻辑** — 仅限纯粹的数据访问
- 所有函数必须具有 **显式返回类型**
- 所有 Zod 字符串/数组字段必须使用 **`.max()`**
- 所有错误必须使用带有 `messageKey` 的 **`BusinessException`**（支持 6 种语言的 i18n）
- 每个 `update()` / `delete()` 的 where 子句中必须包含 **`tenantId`**
### 预提交钩子
每次提交都会运行 Husky + lint-staged：
1. 对暂存的 `.ts` 文件执行 ESLint
2. TypeScript 类型检查 (`tsc --noEmit`)
3. Prettier 格式化
### 提交约定
通过 commitlint 强制执行约定式提交：`feat:`、`fix:`、`refactor:`、`docs:`、`test:`、`chore:`
标签：AI助手, AI安全平台, AI智能体, BFF架构, FTP漏洞扫描, GPT, MITM代理, NestJS, PostgreSQL, Prisma, Redis, SOAR, TypeScript, UEBA, 全栈安全, 关联分析, 后端开发, 威胁情报, 安全插件, 安全编排, 安全运营中心, 开发者工具, 搜索引擎查询, 案件追踪, 测试用例, 漏洞管理, 网络映射, 自动化响应, 警报管理, 请求拦截