TITeee/heretix-management
GitHub: TITeee/heretix-management
基于Next.js的软件资产漏洞管理控制台，支持CVE追踪、EPSS/KEV enrichment和告警生命周期管理。
Stars: 0 | Forks: 0
# heretix-management
一个漏洞管理控制台，用于导入由 [heretix-cli](../heretix-cli) 收集的服务器软件包信息，并利用 heretix-api 检测、跟踪和管理漏洞。
[日本語版 README](./README.ja.md)
## 技术栈
| 角色 | 技术 |
|---|---|
| 框架 | Next.js 16 (App Router) |
| 语言 | TypeScript |
| UI | Tailwind CSS + shadcn/ui (base-ui) |
| 图表 | Recharts |
| 表格 | TanStack Table |
| 认证 | Auth.js v5 (NextAuth) — Credentials Provider |
| ORM | Prisma 7 |
| 数据库 | PostgreSQL |
| 包管理器 | pnpm |
## 功能特性
- **仪表盘** — 双标签页布局：概览 / 标签
- **概览** — 资产与警报总数、严重等级摘要、标签严重等级甜甜圈图（生产环境 / 开发环境 / 预发布环境及颜色指示器）、8周警报趋势、Top 10 漏洞资产与软件包、KEV (Known Exploited Vulnerabilities) 高亮
- **标签** — 与标签关联的软件包和资产卡片，按严重等级进行颜色编码。严重软件包卡片（点击跳转至警报列表），生产环境 / 开发环境 / 预发布环境资产卡片（带有 Host / Docker Image 图标，点击跳转至警报列表）
- **资产管理** — 导入 `inventory.json`（增量更新）、资产列表及详情视图、编辑与删除
- **手动资产注册** — 通过 GUI 直接注册网络设备和防火墙
- **手动软件包管理** — 添加、编辑和删除在包管理器之外安装的软件。Advisory 标签页支持通过下拉菜单选择 Fortinet 和 Palo Alto Networks 的产品
- **软件包变更历史** — 在导入时查看每个资产的软件包新增/更新/移除历史
- **漏洞扫描** — 通过 heretix-api 批量搜索检测漏洞并记录警报（仅创建新警报；不更新或自动解决现有警报）
- **警报管理** — 状态跟踪（Open / In Progress / Resolved / Ignored）、筛选器（资产 / 状态 / 严重等级，多值）、通过复选框选择进行批量状态更新
- **自动解决警报** — 当软件包在导入期间升级时，自动将旧版本的警报标记为 Resolved
- **警报元数据刷新** — 从 heretix-api 重新获取所有 Open/In Progress 警报的最新 CVSS 分数、严重等级、EPSS 和 KEV 数据（不创建新警报）
- **刷新运行日志** — 仅在发生更改时记录执行历史。通过警报页面上的 **View History** 按钮查看运行时间戳、更新计数及前后详情
- **警报详情面板** — 点击行可打开侧滑面板，包含概览（基本信息、备注、解决原因）、NVD 标签页（CVSS 详情、CWE、CISA KEV、参考链接）、OSV 标签页（描述、受影响版本、参考资料）和时间线标签页（响应历史）
- **警报时间线** — 自动在时间线标签页中记录检测、状态变更、备注保存、CVSS 分数变更、严重等级变更及 KEV 新增
- **漏洞搜索** — 直接通过软件包名称、版本和 ecosystem 进行搜索
- **用户管理** — 添加、编辑和删除用户（仅限管理员角色）
- **设置** — 配置 heretix-api URL 和 API token，连接测试
- **定时任务** — 服务器启动时，node-cron 注册每日任务：刷新元数据（默认 12:00 UTC）→ 为所有资产运行扫描（默认 13:00 UTC）。可通过 `CRON_REFRESH` / `CRON_SCAN` 环境变量覆盖
- **结构化日志** — 扫描进度（开始、完成、失败）和认证事件（登录成功/失败）以 JSON 格式记录到 stdout。在 Docker 部署中使用 `docker logs` 收集
## 设置
### 前置条件
- Node.js 20+
- pnpm
- PostgreSQL（已创建 `heretix_management` 数据库）
- [heretix-api](../heretix-api) 正在运行（默认：`http://localhost:5000`）
### 环境变量
创建 `.env.local`：
```
DATABASE_URL="postgresql://postgres:password@localhost:5432/heretix_management?schema=public"
AUTH_SECRET="your-secret-key"
AUTH_URL="http://localhost:3000"
# heretix-api URL 和 token 也可以通过 UI 中的 Settings 页面进行配置
HERETIX_API_URL="http://localhost:5000"
HERETIX_API_KEY="your-api-token"
# Scheduled job 时间（cron 语法，UTC）。默认值：refresh 12:00，scan 13:00
CRON_REFRESH="0 12 * * *"
CRON_SCAN="0 13 * * *"
```
### 安装与运行
```
# 安装 dependencies
pnpm install
# 生成 Prisma client
pnpm exec prisma generate
# 应用 DB schema
pnpm exec prisma db push
# 创建 admin 用户（仅限首次）
pnpm seed
# 默认值：admin@example.com / changeme
# 自定义：SEED_EMAIL=you@example.com SEED_PASSWORD=yourpass pnpm seed
# 启动开发服务器
pnpm dev
```
打开 `http://localhost:3000` 并登录。
## Docker 部署
### 前置条件
- Docker
- Docker Compose
### 设置
在项目根目录创建 `.env`：
```
# 必需
AUTH_SECRET="your-secret-key" # Generate with: openssl rand -base64 32
AUTH_URL="http://your-server-ip:3000" # Set to the actual server IP/domain
POSTGRES_PASSWORD="changeme"
# 可选（也可以通过 Settings 页面设置）
HERETIX_API_URL="http://localhost:5000"
HERETIX_API_KEY=""
# Scheduled jobs（cron 语法，UTC）。默认值：refresh 12:00，scan 13:00
CRON_REFRESH="0 12 * * *"
CRON_SCAN="0 13 * * *"
```
### 构建并运行
```
docker compose build
docker compose up -d
docker compose logs -f app
```
数据库迁移将在容器启动时自动应用。
### 初始设置（仅限首次）
```
# 创建 admin 用户
docker compose exec app node_modules/.bin/tsx prisma/seed.ts
# 默认值：admin@example.com / changeme
# 自定义：SEED_EMAIL=you@example.com SEED_PASSWORD=yourpass docker compose exec app node_modules/.bin/tsx prisma/seed.ts
```
### 常用命令
```
# 停止
docker compose down
# 停止并删除 database volume（完全重置）
docker compose down -v
# 查看日志
docker compose logs -f app
```
## 使用说明
### 1. 注册资产
**服务器与虚拟机（通过 heretix-cli）：**
1. 在侧边栏前往 **Assets** → **Import inventory.json**
2. 上传由 heretix-cli 生成的 `inventory.json`
3. 软件包以增量方式导入（重新导入时仅处理新增、更新和移除）
4. 重新导入时会保留手动添加的软件包
**网络设备与防火墙（手动注册）：**
1. 在侧边栏前往 **Assets** → **Add Manually**
2. 输入名称、主机名和类型，然后点击 **Create Asset**
3. 在资产详情页面，点击 **Add Package** → **Advisory tab**
- 从下拉菜单中选择供应商（Fortinet / Palo Alto Networks）和产品，然后输入版本
4. 点击 **Run Scan** 检测漏洞（使用 heretix-api Vendor Advisory 数据）
5. 固件升级后，点击软件包上的 **Edit** 更改版本并重新扫描
### 2. 添加手动软件包
1. 在资产详情页面的软件包表右上角点击 **Add Package**
2. 选择一个标签页并填写详情：
- **General** — 软件包名称、版本和 ecosystem（Linux, npm, PyPI 等）
- **Advisory** — 从下拉菜单中选择供应商（Fortinet / Palo Alto Networks）和产品，输入版本（用于网络设备和防火墙）
- **CPE** — 直接输入 CPE 2.3 字符串
3. 带有 `manual` 标记的软件包可以编辑或删除
4. 点击警报列中的标记可跳转至该软件包的警报列表
### 3. 漏洞扫描
1. 打开资产详情页面
2. 点击 **Run Scan**
3. heretix-api 检查所有软件包（包括手动添加的）并生成警报
### 4. 管理警报
1. 在侧边栏的 **Alerts** 下查看警报列表
2. 使用 **filters**（资产 / 状态 / 严重等级）缩小结果范围（支持多值）
3. 通过复选框选择多个警报 → 可进行批量状态更新
4. 点击警报行以打开详情面板：
- **Overview** 标签页 — 基本信息、状态变更、备注、自动解决原因
- **NVD** 标签页 — CVSS 详细分数、CWE、CISA KEV 信息、参考链接
- **OSV** 标签页 — 描述、受影响版本、参考链接
5. 通过更改状态跟踪进度：`Open` → `In Progress` → `Resolved` / `Ignored`
6. 点击 **Refresh Metadata** 从 heretix-api 同步最新数据
### 5. 漏洞搜索
使用侧边栏中的 **Search** 直接通过软件包名称、版本和 ecosystem 进行搜索。
## 目录结构
```
heretix-management/
├── app/
│ ├── (console)/ # Authenticated console screens
│ │ ├── layout.tsx # Sidebar + topbar
│ │ ├── page.tsx # Dashboard (Overview / Tags tabs)
│ │ ├── assets/ # Asset list, detail, import, manual registration
│ │ ├── alerts/ # Alert list
│ │ ├── users/ # User management (admin only)
│ │ ├── search/ # Vulnerability search
│ │ └── settings/ # Settings
│ ├── api/ # API routes
│ │ ├── assets/
│ │ ├── alerts/
│ │ ├── users/
│ │ ├── search/
│ │ └── settings/
│ └── login/ # Login page
├── components/
│ ├── ui/ # shadcn/ui components (including severity-badge)
│ ├── layout/ # Sidebar & topbar
│ ├── data-table/ # Shared DataTable & facet filters
│ ├── dashboard/ # Dashboard chart components (critical-packages-card, production-assets-card, etc.)
│ └── assets/ # Asset column definitions
├── instrumentation.ts # Initializes scheduler on server start
├── lib/
│ ├── auth.ts # Auth.js configuration
│ ├── db.ts # Prisma client
│ ├── severity.ts # Severity & status color constants and helpers
│ ├── heretix-api.ts # heretix-api client
│ ├── logger.ts # Structured JSON log utility
│ ├── scan.ts # Scan logic (shared by route handler & scheduler)
│ ├── refresh.ts # Metadata refresh logic (shared)
│ └── scheduler.ts # node-cron schedule definitions
├── prisma/
│ ├── schema.prisma
│ └── seed.ts
└── middleware.ts # Auth guard
```
## API 端点
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | `/api/assets` | 列出资产 |
| POST | `/api/assets` | 创建/更新资产 (inventory.json 增量导入) |
| GET | `/api/assets/[id]` | 资产详情 |
| PATCH | `/api/assets/[id]` | 更新资产信息 (name / hostname / osName / osVersionId) |
| DELETE | `/api/assets/[id]` | 删除资产 |
| POST | `/api/assets/[id]/scan` | 运行漏洞扫描 |
| POST | `/api/assets/[id]/packages` | 添加手动软件包 |
| PATCH | `/api/assets/[id]/packages/[pkgId]` | 编辑手动软件包 |
| DELETE | `/api/assets/[id]/packages/[pkgId]` | 删除手动软件包 |
| GET | `/api/alerts` | 列出警报 |
| PATCH | `/api/alerts/[id]` | 更新警报状态 / 备注 |
| GET | `/api/alerts/[id]/events` | 列出警报事件历史 |
| POST | `/api/alerts/refresh` | 从 heretix-api 批量刷新警报元数据 |
| GET | `/api/alerts/refresh-log` | 列出刷新元数据运行历史 |
| GET | `/api/search` | 漏洞搜索 (heretix-api 代理) |
| GET | `/api/settings` | 获取设置 |
| PATCH | `/api/settings` | 更新设置 |
| POST | `/api/settings/test` | 测试 heretix-api 连接性 |
| GET | `/api/users` | 列出用户（仅限管理员） |
| POST | `/api/users` | 创建用户（仅限管理员） |
| PATCH | `/api/users/[id]` | 更新用户（仅限管理员） |
| DELETE | `/api/users/[id]` | 删除用户（仅限管理员） |
标签：CISA项目, CVE追踪, EPSS评分, GPT, IT资产管理, KEV已知被利用漏洞, NVD集成, OSV数据库, PostgreSQL, Prisma, SBOM, SecOps, shadcn/ui, Tailwind CSS, TypeScript, Web报告查看器, 云安全架构, 安全仪表盘, 安全合规, 安全插件, 安全运营, 扫描框架, 无线安全, 测试用例, 漏洞管理, 硬件无关, 网络代理, 网络安全, 网络安全审计, 网络设备管理, 自动化攻击, 请求拦截, 资产安全管理, 跌倒检测, 软件物料清单, 防火墙管理, 隐私保护