ihabkhaled/auraspear
GitHub: ihabkhaled/auraspear
AuraSpear 是一个基于 Next.js 和 React 构建的多租户 AI 安全运营中心 (SOC) 前端平台，通过集成 Wazuh、MISP 等多种安全工具与大语言模型，提供统一的威胁检测、事件响应与智能自动化管理。
Stars: 0 | Forks: 0
# AuraSpear SOC 平台
一个基于 Next.js 16、React 19 和 TypeScript 5 构建的多租户 **安全运营中心 (SOC)** 平台。集成了 Wazuh、Graylog、Velociraptor、Grafana、InfluxDB、MISP、Shuffle 和 AWS Bedrock，提供跨租户的实时威胁检测、案件管理、威胁狩猎和情报共享功能。
## 目录
- [技术栈](#tech-stack)
- [功能特性](#features)
- [快速开始](#getting-started)
- [环境变量](#environment-variables)
- [项目结构](#project-structure)
- [架构设计](#architecture)
- [页面与路由](#pages--routes)
- [连接器类型](#connector-types)
- [RBAC 与权限](#rbac--permissions)
- [国际化](#internationalization)
- [样式](#styling)
- [代码质量](#code-quality)
- [NPM 脚本](#npm-scripts)
## 技术栈
| 类别 | 技术 | 版本 |
| ------------- | ------------------------------------- | ------- |
| 框架 | Next.js (App Router, webpack dev) | 16.1.6 |
| 语言 | TypeScript (strict mode, all flags) | 5 |
| UI 库 | React + React DOM | 19.2.3 |
| 样式 | Tailwind CSS v4 (CSS-first) | 4 |
| 组件 | shadcn/ui (Radix primitives) | 3.8.5 |
| 服务端状态 | @tanstack/react-query | 5.90 |
| 全局状态 | Zustand | 5.0 |
| 表单 | React Hook Form + Zod | 7.71 |
| 数据验证 | Zod | 4.3 |
| HTTP 客户端 | Axios (with auth/tenant interceptors) | 1.13 |
| i18n | next-intl (EN, ES, IT, FR, AR, DE) | 4.8 |
| 主题 | next-themes (light/dark/system) | 0.4 |
| 图表 | Recharts | 3.7 |
| 图标 | lucide-react | 0.575 |
| PWA | @serwist/next | 9.5 |
| 提示框/对话框 | Sonner + SweetAlert2 | — |
| 代码检查 | ESLint 9 (7 plugins, flat config) | 9 |
| 格式化 | Prettier + tailwindcss plugin | 3.8 |
| Git 钩子 | Husky v9 + lint-staged + commitlint | — |
## 功能特性
- **运营仪表盘** — 基于查询的运营概览面板，用于展示事件状态、案件积压时间、嘈杂规则、连接器同步健康状况、运行时积压、自动化质量及暴露情况摘要
- **仪表盘** — 实时 KPI（警报、关键数量、待处理案件、MTTR），警报趋势（24小时/7天/30天），MITRE ATT&CK 热门技术，热门资产，管道健康状况，近期活动
- **警报** — 全文搜索，严重程度/状态/时间过滤，AI 辅助调查，确认/关闭工作流
- **案件** — 看板和列表视图，案件生命周期 (open → in_progress → closed)，关联警报，笔记，时间线，工件，任务，评论
- **案件周期** — 案件周期跟踪与管理
- **威胁狩猎** — 通过自然语言进行 AI 驱动的交互式会话，逐步推理，事件结果，快捷提示
- **威胁情报** — IOC 搜索（IP、域名、哈希、URL、电子邮件），MISP 事件订阅源，命中数跟踪
- **事件** — 带有时间线和统计信息的事件生命周期管理
- **连接器管理** — 配置并测试 9 种集成，健康测试，加密凭证存储，按租户启用/禁用
- **数据探索器** — 跨 Graylog、Grafana、InfluxDB、Velociraptor、MISP、Shuffle、Logstash 的日志/事件搜索；仪表盘、管道、自动化、同步作业
- **检测规则** — 带有统计信息的检测规则 CRUD
- **关联** — 带条件判断的关联规则引擎
- **规范化** — 日志规范化管道管理
- **攻击路径** — 攻击路径可视化与分析
- **云安全** — 云账户和发现项管理
- **合规性** — 合规框架与控制项跟踪
- **漏洞** — 漏洞跟踪与管理
- **UEBA** — 用户与实体行为分析（异常、实体、ML 模型）
- **SOAR** — Shuffle playbook 管理与执行
- **AI 智能体** — 带有会话的 AI 智能体管理
- **AI 聊天** — 独立的 AI 对话界面，支持 LLM 连接器回退链、用户归因、跨聊天记忆注入和每线程连接器覆盖
- **AI 发现项** — 所有 AI 生成发现项的集中式可搜索工作区，支持全文搜索 (PostgreSQL tsvector)、高级过滤器、可排序 DataTable、跳转分页、KPI 卡片和详情抽屉
- **AI 记忆** — 用户控制的 AI 记忆管理（设置 > AI 记忆），支持搜索、类别过滤和 CRUD 操作。记忆会自动从聊天中提取并注入到未来的对话中
- **报告** — 报告生成与管理
- **管理员 — 系统** — 多租户管理，服务健康状况，审计日志
- **管理员 — 租户** — 用户管理（邀请/编辑/封禁/恢复），RBAC 分配
- **管理员 — 角色设置** — 全复选框矩阵界面，用于配置每个租户的角色权限。带有粘性头部的可折叠模块。GLOBAL_ADMIN 可以查看、编辑和重置权限
- **动态 RBAC** — 数据库支持的权限矩阵，取代了静态角色检查。覆盖所有模块的约 70 个细粒度权限。权限通过 `/auth/me` 轮询每 60 秒自动同步 — 管理员更改权限时无需登出
- **批量警报操作** — 批量确认和关闭警报，带有感知权限的复选框和操作按钮
- **通知** — 带有铃铛指示器的实时 WebSocket 通知
- **个人资料与设置** — 用户资料，密码修改，主题，语言，通知偏好
- **深色模式** — 通过 CSS 自定义属性实现完整的 light/dark/system 主题
- **RTL 支持** — 针对阿拉伯语的双向布局
- **PWA** — 通过 service worker (@serwist/next) 实现的 Progressive Web App，支持离线访问、移动端响应式，并可在移动端和桌面端安装
- **移动端响应式** — 所有页面、对话框、过滤工具栏、滚动容器和聊天面板均针对移动端进行了优化，采用视口相对大小、滑入式面板和响应式网格断点
## 快速开始
### 前置条件
- Node.js >= 18.18, npm >= 9
- AuraSpear 后端运行于 `http://localhost:4000/api/v1`
### 快速启动
```
# 安装依赖
npm install
# 启动开发服务器 (webpack, 通过 Serwist 实现稳定)
npm run dev
```
打开 [http://localhost:3000](http://localhost:3000)。如果已认证将重定向至 `/dashboard`，否则重定向至 `/login`。
### API 模拟
在 `.env.development` 中设置 `NEXT_PUBLIC_ENABLE_MSW=true` 即可在没有后端的情况下运行。MSW 将拦截所有 API 调用。
## 环境变量
为本地开发创建 `.env.development` 文件：
```
BACKEND_API_URL=http://localhost:4000/api/v1
NEXT_PUBLIC_OIDC_AUTHORITY=https://login.microsoftonline.com/common/v2.0
NEXT_PUBLIC_OIDC_CLIENT_ID=
NEXT_PUBLIC_OIDC_REDIRECT_URI=http://localhost:3000/callback
NEXT_PUBLIC_ENABLE_MSW=false
NEXT_PUBLIC_APP_NAME=AuraSpear SOC
NEXT_PUBLIC_APP_ENV=development
```
| 变量 | 必需 | 描述 |
| ------------------------------- | ---- | -------------------------------------------------- |
| `BACKEND_API_URL` | 是 | NestJS 后端 URL (仅限服务器端，不对外暴露) |
| `NEXT_PUBLIC_OIDC_AUTHORITY` | 否 | 用于 SSO 的 Entra ID 授权机构 |
| `NEXT_PUBLIC_OIDC_CLIENT_ID` | 否 | OIDC 客户端 ID；留空则使用 email/password 模式 |
| `NEXT_PUBLIC_OIDC_REDIRECT_URI` | 否 | 登录后重定向 URI |
| `NEXT_PUBLIC_ENABLE_MSW` | 否 | 设为 `true` 启用 Mock Service Worker 以进行离线开发 |
| `NEXT_PUBLIC_APP_NAME` | 否 | 应用显示名称 |
| `NEXT_PUBLIC_APP_ENV` | 否 | `development` / `staging` / `production` |
环境文件：`.env.development`、`.env.staging`、`.env.production`、`.env.docker`
## 项目结构
```
src/
├── app/
│ ├── (auth)/ # Auth routes (no sidebar)
│ │ ├── login/ # Email/password login
│ │ └── callback/ # OIDC callback
│ ├── (portal)/ # Main app (AuthGuard + Sidebar)
│ │ ├── dashboard/ # Executive dashboard
│ │ ├── alerts/ # Alert management
│ │ ├── cases/ # Case list + [id] detail + cycles
│ │ ├── hunt/ # Threat hunting
│ │ ├── intel/ # Threat intelligence
│ │ ├── incidents/ # Incident management
│ │ ├── connectors/ # Connector list + [type] config
│ │ ├── explorer/ # Data explorer (8 sub-pages)
│ │ ├── detection-rules/ # Detection rules
│ │ ├── correlation/ # Correlation rules
│ │ ├── normalization/ # Normalization pipelines
│ │ ├── attack-paths/ # Attack path analysis
│ │ ├── cloud-security/ # Cloud findings
│ │ ├── compliance/ # Compliance tracking
│ │ ├── vulnerabilities/ # Vulnerability tracking
│ │ ├── ueba/ # Behavior analytics
│ │ ├── soar/ # SOAR playbooks
│ │ ├── ai-agents/ # AI agents
│ │ ├── reports/ # Reports
│ │ ├── system-health/ # System monitoring
│ │ ├── admin/system/ # System admin
│ │ ├── admin/tenant/ # Tenant admin
│ │ ├── profile/ # User profile
│ │ └── settings/ # Preferences
│ ├── api/ # Server-side API proxy (156 routes)
│ ├── globals.css # Tailwind v4 theme + status/severity classes
│ ├── layout.tsx # Root layout (i18n, fonts, Toaster, SW)
│ ├── providers.tsx # QueryClient, ThemeProvider, NextIntlClientProvider
│ └── sw.ts # Service worker (PWA)
├── components/
│ ├── ui/ # shadcn/ui primitives (28+ components)
│ ├── common/ # Shared: AuthGuard, RoleGuard, DataTable, PageHeader, etc.
│ ├── layout/ # PortalShell, Sidebar, Topbar, TenantSwitcher, etc.
│ └── / # Domain components (alerts, cases, hunt, intel, etc.)
├── hooks/ # 366+ custom hooks (one file per hook)
├── services/ # 34 singleton API services
├── stores/ # 7 Zustand stores (auth, tenant, filter, hunt, ui, notification, aiConnector)
├── types/ # 34 type definition files
├── enums/ # 38 enum files
├── i18n/ # 6 locale files (en, ar, es, fr, de, it)
├── lib/
│ ├── api.ts # Axios instance with auth/tenant interceptors
│ ├── backend-proxy.ts # proxyToBackend() for API routes
│ ├── constants/ # 25 constant files
│ └── validation/ # 15 Zod validation schemas
```
## 架构设计
### API 代理模式
前端**从不直接调用外部服务**。所有请求都通过 Next.js API 路由代理到 NestJS 后端：
```
Browser → Next.js API Route → NestJS Backend → Wazuh/MISP/etc.
```
- `src/lib/api.ts` — 带有 auth token + 租户 ID 拦截器的 Axios 实例
- `src/lib/backend-proxy.ts` — 服务端 `proxyToBackend()` 工具
- `src/app/api/**` — 156 个 API 路由处理器 (GET, POST, PATCH, DELETE)
### 状态管理
| 层级 | 工具 | 用途 |
| ------------ | --------------- | ------------------------------------ |
| 服务端状态 | React Query | API 数据获取、缓存、失效处理 |
| 全局状态 | Zustand | 认证、租户、过滤器、UI (7 个存储) |
| 表单状态 | React Hook Form | 带有 Zod 数据验证的表单管理 |
| URL 状态 | Next.js Router | 路由参数，搜索参数 |
### 组件架构
```
Page → Domain Components → Common Components → shadcn/ui Primitives
↓
Custom Hooks → Services → Axios → API Routes
```
- **Services** — 单例 API 封装（34 个文件，每个领域一个）
- **Hooks** — 每个文件一个 hook（366+ 个 hook）。页面 hook，数据 hook，组件 hook
- **Types** — 所有接口定义在 `src/types/.types.ts`
- **Enums** — 所有枚举定义在 `src/enums/.enum.ts`
- **Constants** — 所有常量定义在 `src/lib/constants/.ts`
### 模块化
- 所有 UI 组件通过 `@/components/ui` barrel (聚合导出) 文件导出 (28 个组件)
- 所有通用组件通过 `@/components/common` barrel 导出 (28+ 个组件)
- 所有服务通过 `@/services` barrel 导出 (34 个服务)
- 所有 hooks 通过 `@/hooks` barrel 导出 (366+ 个 hooks)
- 所有存储通过 `@/stores` barrel 导出 (7 个存储，包括 `useAiConnectorStore`)
- 所有类型通过 `@/types` barrel 导出
- 所有枚举通过 `@/enums` barrel 导出
- 仅从 barrel 文件导入 — 绝不直接引入子路径（例如，使用 `@/components/ui` 而不是 `@/components/ui/button`）
## 页面与路由
### 门户页面 (41 个页面)
| 路由 | 描述 | 最低角色要求 |
| --------------------- | ---------------------------------- | -------------- |
| `/dashboard` | 带有 KPI 的管理仪表盘 | 所有角色 |
| `/alerts` | 警报搜索与管理 | SOC_ANALYST_L1 |
| `/cases` | 案件列表 (看板 + 表格) | SOC_ANALYST_L1 |
| `/cases/[id]` | 案件详情 (工件，时间线) | SOC_ANALYST_L1 |
| `/cases/cycles` | 案件周期列表 | SOC_ANALYST_L1 |
| `/hunt` | AI 驱动的威胁狩猎 | THREAT_HUNTER |
| `/intel` | 威胁情报 (IOC, MISP) | SOC_ANALYST_L1 |
| `/incidents` | 事件管理 | SOC_ANALYST_L1 |
| `/connectors` | 连接器管理 | TENANT_ADMIN |
| `/connectors/[type]` | 连接器配置 | TENANT_ADMIN |
| `/explorer/*` | 数据探索器 (8 个子页面) | SOC_ANALYST_L1 |
| `/detection-rules` | 检测规则管理 | SOC_ANALYST_L2 |
| `/correlation` | 关联规则引擎 | SOC_ANALYST_L2 |
| `/normalization` | 规范化管道 | SOC_ANALYST_L2 |
| `/attack-paths` | 攻击路径分析 | SOC_ANALYST_L2| `/cloud-security` | 云账户发现项 | SOC_ANALYST_L1 |
| `/compliance` | 合规性跟踪 | SOC_ANALYST_L1 |
| `/vulnerabilities` | 漏洞跟踪 | SOC_ANALYST_L1 |
| `/ueba` | 行为分析 | SOC_ANALYST_L2 |
| `/soar` | SOAR playbook | SOC_ANALYST_L2 |
| `/ai-agents` | AI 智能体管理 | SOC_ANALYST_L2 |
| `/ai-chat` | AI 对话界面 | AI_CHAT_ACCESS |
| `/ai-findings` | AI 发现项搜索与工作区 | AI_AGENTS_VIEW |
| `/reports` | 报告生成 | SOC_ANALYST_L1 |
| `/system-health` | 系统监控 | TENANT_ADMIN |
| `/admin/system` | 系统管理员 (多租户) | GLOBAL_ADMIN |
| `/admin/tenant` | 租户用户管理 | TENANT_ADMIN |
| `/admin/role-settings`| 角色权限矩阵编辑器 | GLOBAL_ADMIN |
| `/profile` | 用户资料 | 所有角色 |
| `/settings` | 主题，语言，通知，AI 记忆 | 所有角色 |
### 认证页面
| 路由 | 描述 |
| ----------- | -------------------- |
| `/login` | 邮箱/密码登录 |
| `/callback` | OIDC 回调处理器 |
## 连接器类型
| 连接器 | 用途 | 功能特性 |
| -------------- | ------------------ | ------------------------------------ |
| Wazuh Manager | SIEM 警报和代理 | 警报摄取，代理管理 |
| Wazuh Indexer | 日志搜索 | 基于 OpenSearch 的事件查询 |
| Graylog | 日志管理 | 日志流，搜索，管道 |
| Velociraptor | EDR / DFIR | 端点检测，取证 |
| Grafana | 仪表盘 | 指标可视化 |
| InfluxDB | 时间序列 | 指标存储与查询 |
| MISP | 威胁情报 | IOC 订阅源，事件关联 |
| Shuffle | SOAR | Playbook 执行，自动化 |
| AWS Bedrock | AI 分析 | AI 驱动的调查 |
## RBAC 与权限
### 角色
| 角色 | 级别 | 访问权限 |
| -------------------- | ---- | ------------------------------------ |
| `GLOBAL_ADMIN` | 1 | 完整平台访问 + 租户切换 |
| `TENANT_ADMIN` | 2 | 完整租户访问 + 用户管理 |
| `SOC_ANALYST_L2` | 3 | 高级分析 + 规则管理 |
| `THREAT_HUNTER` | 4 | 威胁狩猎 + 情报 |
| `SOC_ANALYST_L1` | 5 | 基础警报/案件操作 |
| `EXECUTIVE_READONLY` | 6 | 仅限仪表盘和报告 |
### 动态权限系统
平台采用**数据库支持的权限矩阵**而非静态角色检查。GLOBAL_ADMIN 可以通过角色设置管理页面 (`/admin/role-settings`) 在每个租户的基础上配置哪些角色可以执行哪些操作。
**核心特点：**
- **约 70 个细粒度权限** 覆盖所有模块：警报、案件、事件、连接器、关联、检测规则、威胁狩猎、报告、管理、情报、SOAR、AI 智能体、云安全、合规性、攻击路径、UEBA、规范化、漏洞、数据探索器、通知、个人资料、设置和角色设置
- **自动刷新** — 权限通过 `/auth/me` 轮询每 60 秒同步一次。当管理员更改用户权限时，用户无需登出即可看到更新后的访问权限
- **感知权限的 UI** — 所有页面均根据用户解析后的权限条件性地显示/隐藏创建、编辑和删除按钮。当用户缺少确认/关闭权限时，警报复选框和批量操作会被隐藏。升级按钮同时需要 `ALERTS_ESCALATE` 和 `INCIDENTS_CREATE` 权限
- **案件负责人绕过** — 案件负责人可以编辑、更改状态、添加评论、任务和工件，而无需受限于其角色级别的权限
- **批量警报操作** — 批量确认和关闭警报，其可见性受权限检查控制
### 角色设置管理页面
`/admin/role-settings` 页面提供了一个完整的复选框矩阵，GLOBAL_ADMIN 可以在其中：
- 查看所选租户中所有角色的当前权限状态
- 切换每个角色的个别权限
- 将角色权限重置为系统默认值
- 浏览带有粘性头部的可折叠模块组，以便于扫视
### 权限执行
通过 `` 组件、`useRoleGuard()` hook 以及 `usePermissions()` / `useHasPermission()` hook 进行前端执行。后端通过 `@Roles()` + `RolesGuard` 和权限守卫中间件执行相同的规则。
## 国际化
- **系统**：next-intl v4.8
- **语言环境**：英语、阿拉伯语、西班牙语、法语、德语、意大利语
- **RTL**：对阿拉伯语的完整双向支持
- **使用方法**：`const t = useTranslations('namespace')` → `t('key')`
- **文件位置**：`src/i18n/{en,ar,es,fr,de,it}.json`
- **规则**：严禁硬编码面向用户的文本 — 始终使用 `t()`
## 样式
### Tailwind CSS v4
CSS-first 配置 (无 `tailwind.config.js`)。主题通过 CSS 自定义属性在 `globals.css` 中定义。
### 主题
- `next-themes` 提供 light/dark/system 支持
- 所有颜色使用 HSL CSS 变量：`--background`、`--foreground`、`--primary` 等
- 亮色和暗色调色板均在 `globals.css` 中定义
### 状态与严重程度类
用于保持状态/严重程度样式一致性的预定义实用类：
```
.status-active, .status-inactive, .status-pending
.severity-critical, .severity-high, .severity-medium, .severity-low
```
## 代码质量
### 强制执行规则
- **禁止使用 `any`** — 使用 `unknown`、泛型或合适的类型
- **禁止禁用 ESLint** — 修复根本原因
- **禁止硬编码文本** — 使用来自 next-intl 的 `t()`
- **禁止在组件文件中使用内联类型/枚举/常量**
- **禁止在组件内定义自定义 hooks** — 每个文件一个 hook，置于 `src/hooks/` 中
- **禁止直接使用 ``** — 使用 `