Engagement Manager

Engagement Manager 是一个用于跟踪攻击性安全项目的 Web 应用程序。它采用现代 UI，基于 Next.js、Prisma 和 PostgreSQL 构建。该应用包含日历、项目、客户、联系人、发现和操作员。

• Lee Baird @discoverscripts
• Jay "L1ghtn1ng" Townsend @jay_townsend1

截图

目录

• 截图
• 编写发现并生成 PDF 报告
  • 报告安全与部署
  • 验证
• 先决条件
• 环境配置
• 数据库设置
  • 开发
  • 生产
• 安装
  • 自动化设置（Ubuntu）
    • 加固设置与备份的升级说明
  • 手动设置
• 运行应用程序
• 生产部署
  • 要求
  • 部署步骤
  • 生产检查清单
• 默认凭据
• 服务器迁移（备份 / 恢复 / 重置）
• 实施计划与架构
  • 技术栈
  • 数据库模式
  • 添加新字段
  • 安全架构

编写发现并生成 PDF 报告

• 编写工作区： 打开发现的 Write & review 链接，进行 Markdown 编辑和安全预览。私有草稿在 15 秒无操作后或按需保存；它们存储在服务器上，而非浏览器本地存储中。重新打开后可显式恢复草稿。冲突保存会保留编辑器中的文本，并要求与当前修订版本进行比较。文本修订版本可以查看和恢复；恢复不会恢复已删除的证据。
• 可复用模板： 按标题、类别或严重性搜索已批准的措辞。用户可以提议模板；管理员负责整理和批准。应用模板会创建一个独立的项目发现，其中观察结果、受影响主机和证据均为空，从而防止意外复用其他项目的证明。
• 证据： 最多可同时上传或粘贴四张 PNG/JPEG 图像，添加说明文字，并在编写工作区中编辑说明文字/顺序。图像会被解码、剥离元数据、调整大小至最多 2000 × 2000 像素，并保存为 PNG。如果需要原始字节或元数据，请单独保留原始取证证据。
• 审查： 将完整的发现从 Draft/Changes Requested 发送至 Ready。除当前作者外，指定的审查者或管理员可以批准或请求更改。管理员分配审查者。文本、证据和恢复修订版本的更改会清除批准状态。审查队列、评论、就绪检查清单和修订历史支持交接。
• PDF 报告： 在 Reports 中选择一个项目，编写其执行摘要，选择/排序发现并保存设置。草稿 PDF 会被明显标记。只有管理员可以签发最终 PDF，并且每个选定的发现都必须已批准并通过就绪检查。每个签发的版本都会存储其 PDF、明确的内容快照和 SHA-256 摘要；后续编辑不会重新生成它。删除父项目仍会通过现有生命周期删除其报告。
• 扫描器导入： 预览导出内容，选择发现，然后确认。导入绝不会执行扫描或联系目标。服务器端指纹识别会跳过同一项目中匹配的发现；所有新记录都以 Draft 开始，必须由操作员检查。

每次导入的导出内容限制为 2 MB 和 500 个发现，并设有每用户预览和确认速率限制。应用程序在手动创建、模板和扫描器导入中总共最多接受 10,000 个发现，单个项目最多 500 个。全局 Findings 列表每页加载 100 行，项目/报告发现查询受相同的每项目限制约束。未知布局会明显失败，而不会被静默视为成功导入。扫描器严重性仅为建议：批准前请审查其上下文。引用的 URL、HTML 和嵌入的远程图像不会被获取或执行。

报告允许 1–100 个发现、最多 100 张证据图像（每张 5 MB，总输入 20 MB）、500 页和 25 MB 输出。签发限制为每个项目 50 个版本，整个应用程序已签发 PDF 总计 1 GB。预览和签发设有每用户速率限制，并且每个应用程序进程一次只允许一个 PDF 渲染。发现最多保留 1000 个修订版本和 500 条评论；达到限制时会失败，而不会覆盖历史记录。DejaVu 字体及其再分发许可证包含在 assets/fonts 中；部署必须保留这些资产（Next 输出追踪会包含它们）。

Next.js Server Actions 共享单个 25mb 请求体大小限制（在 next.config.ts 中设置），用于证据上传。登录使用专用的同源 URL 编码路由，在身份验证或数据库操作之前设有 4 KB 流式限制。

报告安全与部署

这保留了现有的共享已认证工作区，而非新的按客户租户模型。所有新页面、操作和 PDF 下载都会检查当前由数据库支持的会话。草稿限定于其所有者；审查、模板批准和签发权限在服务器端强制执行。机密 PDF 响应为 private/no-store。最终 PDF 仅包含明确的报告字段允许列表，绝不包含私有草稿、审查评论或无关项目。

该实现使用 OWASP Top 10:2025 检查清单：访问检查（A01）、私有响应和现有 CSP/CSRF 控制（A02）、固定依赖项和 CI（A03）、现有会话/密钥保护以及报告完整性检查（A04/A08）、惰性 Markdown/XML 和参数化数据库访问（A05）、有界处理和独立审查（A06）、实时会话检查（A07）、无内容审计事件（A09），以及失败时清理的事务性更改（A10）。摘要可检测意外损坏；它不是数字签名，也不能防御数据库管理员。这不是合规认证。生产环境仍然需要 HTTPS、受保护的数据库/备份存储以及对审计输出的运营监控。

在部署此升级之前，请进行常规应用程序备份，并使用 npm run db:migrate 应用附加的 20260904221808_reporting_workflow 和 20260906194500_add_revocable_sessions 迁移，然后重新生成 Prisma Client 并重新构建。现有发现从版本 1 的 Draft 开始，现有浏览器 cookie 必须重新登录，以便获得由服务器支持的会话 ID。不要重置现有数据库。备份通过现有的全数据库导出包含新表和已签发 PDF。

验证```bash

npm test npm run lint npx tsc --noEmit --noUnusedLocals --noUnusedParameters npm run build npm audit

`npm test` 使用 Node 的非隔离测试模式配合 `tsx`，以便各个 TypeScript 测试用例真正执行，而不仅仅是报告文件子进程成功。在 CI 中保持显式的断言总数可见。

数据库和浏览器回归测试需要一个**名为 `reporting_tests` 的专用本地数据库**，并已应用迁移。它们会创建并删除自己的夹具行；切勿将这些测试指向应用程序数据库。将 `REPORTING_TEST_DATABASE_URL` 设置为该测试数据库，然后运行：```bash
DATABASE_URL="$REPORTING_TEST_DATABASE_URL" npx prisma migrate deploy
npm run test:reporting
npx playwright install chromium
npm run test:browser

浏览器测试套件会在端口 3317 上启动自己的回环开发服务器，并使用仅用于测试的会话密钥；它拒绝复用已有的服务器。如有需要，可将 REPORTING_TEST_BROWSER 设置为已安装的 Chromium 可执行文件。它测试草稿隐私、冲突编辑、证据上传、独立审查、PDF 权限/不可变性、无需 JavaScript 的模板创建，以及选择性去重导入。集成测试会演练实际的事务冲突和回滚。这些测试套件不能替代远程局域网、Safari 或生产部署验证。

先决条件

此应用程序设计为在 Ubuntu 上运行，并需要以下内容：```bash sudo apt update && sudo apt install -y nodejs npm postgresql postgresql-client postgresql-contrib zip

`postgresql-client` 提供 `pg_dump`、`pg_restore` 和 `psql`；`zip` 用于创建备份归档。恢复提取由应用程序处理，并带有严格的条目和大小验证。

安装软件包并不总是会让 PostgreSQL 保持运行。在创建角色或启动应用之前，请启动并启用该服务：```bash
sudo systemctl enable --now postgresql
sudo systemctl status postgresql --no-pager

如果应用之后报错 Can't reach database server at 127.0.0.1:5432，请运行 sudo systemctl start postgresql，并用 pg_isready -h 127.0.0.1 -p 5432 确认。

该应用需要 Node.js ^22.12.0 或 >=24.0.0（参见 package.json 中的 engines）。如果操作系统软件包版本较旧，请从可信的软件包源安装受支持的版本，并在运行 setup.sh 之前验证其签名。

环境配置

在运行 Prisma 或应用之前，请在项目根目录中创建 .env 文件：```bash cat > .env << 'EOF' DATABASE_URL="postgresql://em_admin:em_pass@localhost:5432/engagement_manager?schema=public" JWT_SECRET="replace-with-a-long-random-secret-at-least-32-characters" EOF chmod 600 .env

| 变量 | 必需 | 说明 |
|----------|----------|-------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串。Prisma 使用 `schema=public` 查询参数。备份和恢复使用仅所有者可访问的临时 pgpass 文件，因此密码不会出现在子进程参数中。 |
| `JWT_SECRET` | 生产环境必需 | 必须至少为 **32 个字符**。生产环境中若缺少此变量，应用将拒绝启动。轮换此密钥会使所有现有会话失效。 |
| `TRUST_PROXY` | 否 | 仅当应用位于反向代理之后，且该代理会**覆盖** `X-Forwarded-For` / `X-Real-IP` 和 `X-Forwarded-Host` 时，才设置为 `1`（或 `true`）。在此模式下，登录来源检查会在存在 `X-Forwarded-Host` 时使用它；该值必须包含一个公共主机名，使用时若端口非默认端口也需包含。否则，代理必须保留公共 `Host` 头。这是实现准确的按来源登录限制所必需的生产拓扑。未设置时，请求头将被忽略以防止欺骗，登录使用更高的每分钟共享回退预算，这样单个客户端就无法造成 15 分钟的全局锁定。 |
| `ALLOWED_DEV_ORIGINS` | 否 | **仅限开发环境。** 允许加载 `/_next` 资源的额外主机名（逗号分隔）。服务器当前的局域网 IPv4 地址会自动允许。用于稳定的 DNS 名称。生产构建会忽略此项。 |

生成强密钥：```bash
openssl rand -base64 32

数据库设置

请确保 PostgreSQL 已首先运行（参见先决条件）。自动化脚本 ./setup.sh 会为你启动该服务；以下手动步骤假定服务已启动。

开发环境

运行以下命令以创建 PostgreSQL 数据库和用户：```bash sudo -u postgres createuser --pwprompt em_admin sudo -u postgres psql -c "ALTER USER em_admin CREATEDB;" sudo -u postgres createdb --owner=em_admin engagement_manager sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE engagement_manager TO em_admin;"

### 生产环境

使用具有**最小权限**的专用数据库用户——不要授予 `CREATEDB` 或超级用户权限：```bash
sudo -u postgres createuser --pwprompt em_app
sudo -u postgres createdb --owner=em_app engagement_manager

将 DATABASE_URL 设置为使用 em_app（或你选择的用户名）。迁移通过 npm run db:migrate 以该用户身份运行。

注意： 数据库文件存储在 PostgreSQL 数据目录中（通常为 /var/lib/postgresql/<version>/main/）。

安装

自动安装（Ubuntu）

在仓库根目录下，运行：```bash chmod +x setup.sh ./setup.sh

该脚本会安装先决条件，启动并启用 PostgreSQL 服务，提示输入数据库用户名和密码，写入一个 `chmod 600` 的 `.env` 文件，创建 PostgreSQL 角色和数据库，应用迁移，并初始化默认管理员账户。生产模式还会完成 `npm run build`，并仅打印生产启动命令。它不会从远程 shell 脚本安装 Node.js；请先安装受支持的 Node.js 版本。

对于无头或 CI 使用：```bash
sudo install -d -m 700 -o "$USER" /secure
openssl rand -base64 24 > /secure/db-password
chmod 600 /secure/db-password
./setup.sh -y --db-user=em_admin --db-pass-file=/secure/db-password

运行 ./setup.sh --help 查看所有选项。

加固设置与备份的升级说明

• --db-pass=... 已被移除，因为命令行中的密钥对其他进程可见。请将密码放入仅所有者可读的文件中，并将旧参数替换为 --db-pass-file=/secure/db-password；上面的自动化设置示例可直接复制粘贴使用。
• setup.sh 不再安装 Node.js。请在运行前从可信的软件包源安装受支持的 Node.js 版本（^22.12.0 或 >=24.0.0）。
• 依赖安装现在使用 npm ci，因此 package-lock.json 必须存在并与 package.json 保持同步。
• 旧版 .sql 备份无法恢复。在停用旧服务器之前，请将其升级到能够创建结构化应用程序备份的版本，并将数据重新导出为 .zip。

手动设置

1. 安装 Node.js 依赖： ```bash npm ci
   root@kitploit:~

2. 运行数据库迁移以构建表： ```bash npx prisma migrate dev
   root@kitploit:~

3. 初始化数据库以创建默认管理员账户： ```bash npx prisma db seed
   root@kitploit:~

运行应用程序

在项目目录中，一条命令即可安装软件包更新、在 PostgreSQL 停止时启动它，并启动应用程序：```bash ./run.sh

让那个窗口保持打开。使用它打印出的 Local 或 Network 地址。

若要自行启动：PostgreSQL 必须正在运行（如有需要，执行 `sudo systemctl start postgresql`）。然后启动开发服务器：```bash
npm run dev

启动时会同时打印一个回环地址和本机的局域网地址：```

• Local: http://localhost:3000
• Network: http://192.168.1.20:3000

`npm run dev` 和 `npm start` 绑定 `0.0.0.0`，因此 Network URL 可在局域网中访问。请仅在受信任网络的实验环境中使用局域网访问。开发模式未针对公共互联网进行安全加固。

如果你通过**主机名**（而非 IP）打开应用，且远程浏览器显示空白白页，请将该名称添加到 `.env` 并重启：```bash
ALLOWED_DEV_ORIGINS=dev.office.example

生产部署

要求

• Node.js ^22.12.0 或 >=24.0.0（参见 package.json 中的 engines）
• PostgreSQL，使用最小权限的应用用户（参见数据库设置）
• 应用前置 HTTPS（反向代理，如 nginx 或 Caddy）。生产环境中会话 cookie 标记为 Secure。
• uploads/ 目录（发现截图）需要持久化存储

部署步骤

1. 克隆仓库并安装依赖： ```bash npm ci

   root@kitploit:~

2. 创建包含生产环境值的 .env 文件（DATABASE_URL、JWT_SECRET ≥ 32 个字符）。

3. 应用数据库迁移： ```bash npm run db:migrate

   root@kitploit:~

4. 运行部署前检查： ```bash npm run audit npm run typecheck npm run build

   root@kitploit:~

5. 使用 NODE_ENV=production 启动应用程序： ```bash NODE_ENV=production npm run start

   root@kitploit:~

对于真实服务器，请在进程管理器（systemd、PM2 等）下运行此服务，并在前面放置反向代理以终止 TLS。

6. 通过数据库种子（仅限开发环境）或从备份恢复来创建第一个管理员账户。在向用户开放应用之前，立即更改临时种子密码。

生产环境检查清单

• JWT_SECRET 至少为 32 个字符，且未提交到 git
• 为运行中的进程设置了 NODE_ENV=production
• 已配置 HTTPS；HTTP 重定向到 HTTPS
• 数据库用户没有 CREATEDB 或超级用户权限
• uploads/ 位于持久化磁盘上并包含在备份中
• 如果管理员使用备份功能，backups/ 位于持久化磁盘上
• 如果管理员将使用备份/恢复功能，pg_dump、pg_restore 和 zip 可用

默认凭据

播种数据库后，你可以使用生成的临时管理员账户登录：

• 用户名：admin
• 密码：由 npx prisma db seed / npm run db:seed 一次性写入仅所有者可读的 initial-admin-credentials.txt

注意： 首次登录时，系统将要求你更改此临时密码。之后请立即删除 initial-admin-credentials.txt。所有密码必须至少为 16 个字符，并包含大写字母、小写字母、数字和符号。

服务器迁移（备份 / 恢复 / 重置）

• 侧边栏在本地存储每个浏览器的日期格式和时区偏好。时区可以跟随查看者的操作系统，或以 UTC 显示时间戳；约定日程日期保持为不变的日历日期。
• 管理员可以从 Admin 页面（/dashboard/users）备份和恢复完整的应用数据。
• 在从旧服务器迁移到新服务器时使用此功能：在新主机上克隆应用，然后从旧主机恢复备份。

在 Admin 页面上，Database 面板显示 Backup、Restore 和 Reset 按钮。Users 面板列出账户，并提供 New User 按钮用于添加用户。Appearance 面板允许管理员选择应用范围内的高亮颜色。

Backup 需要你的管理员密码，然后将名为 em-backup-YYYY-MM-DD-HHMM.zip 的 .zip 文件保存到应用目录下的 backups/（engagement-mgr/backups/）。成功导出后，在 Admin 页面上使用 Download。一个短期有效的签名授权保存在 HttpOnly cookie 中，且仅对创建该备份的管理员有效。

• 时间戳使用运行应用的服务器的本地时间，不包含秒。示例：em-backup-2026-06-02-1430.zip。

• Restore 仅接受由 Backup 创建的 .zip 文件，并替换当前数据库和 uploads/ 文件夹。浏览器恢复限制为 8 MB，因此解压缩不会独占 Web 进程。对于更大的归档文件，请停止应用，并以应用用户身份运行 npm run db:restore -- /absolute/path/to/em-backup.zip。离线命令从工作目录加载 .env，并要求 .env 或环境中具有非空的 DATABASE_URL。它接受最大 500 MB 的常规文件，并通过其展开大小限制流式处理每个归档条目。数据库恢复在一个事务中运行；在安装文件之前，会验证归档条目数量、路径、压缩比和展开大小。备份、恢复、重置和截图文件更改共享一个独占维护锁，因此数据库提交和文件系统交换不会重叠。需要你的管理员密码进行确认。
• Reset 会清除所有应用数据，恢复默认的红色高亮颜色，并重新创建 admin。需要输入 RESET 并重新输入确认管理员的当前密码。该密码将成为重新创建账户的临时密码，必须在首次登录时更改。

旧服务器

1. 以 Admin 用户身份登录。
2. 打开 Admin 并点击 Backup（在 Database 下）。
3. 保存 .zip 文件并将其复制到新服务器（例如使用 scp 或 rsync）： ```bash scp em-backup-2026-06-02-1430.zip user@new-server:/path/to/
   root@kitploit:~

新服务器

1. 安装先决条件并克隆仓库。
2. 创建包含 DATABASE_URL 和 JWT_SECRET 的 .env 文件（参见环境配置）。
3. 创建一个空的 PostgreSQL 数据库和用户（参见数据库设置）。
4. 安装依赖：npm ci。
5. 运行迁移并执行一次种子数据填充，以便管理员可以登录。恢复操作会用备份数据替换此引导数据。
6. 在生产模式下构建并启动应用（参见生产部署）： ```bash npm run build NODE_ENV=production npm run start
   root@kitploit:~

7. 使用仅限所有者访问的 initial-admin-credentials.txt 以 admin 身份登录，更改临时密码，并删除该凭据文件。
8. 打开 Admin（/dashboard/users），点击 Restore（位于 Database 下），选择来自旧服务器的 .zip 文件，输入你的管理员密码，然后确认。
9. 如果应用已在运行，请重启应用，以便其加载恢复的数据。

注意事项

• 敏感操作： Backup、Restore 和 Reset 均需要重新确认管理员密码。Restore 和 Reset 还会替换现有数据库行并覆盖 uploads/ 目录。
• JWT_SECRET： 在新服务器上可能不同；来自旧服务器的现有浏览器会话不会被迁移。用户需使用导入数据库中的账户重新登录。
• 应用程序代码： 在新服务器上使用 git clone（或部署相同的修订版本），以便应用与备份所期望的 schema 匹配。如果旧服务器运行的 schema 比克隆的代码更新，请在导入前对齐版本。
• 工具： 备份和恢复需要安装 Prerequisites 中列出的 CLI 工具。

实施计划与架构

本节记录了 Engagement Manager 应用程序的架构、数据库 schema、安全措施以及已完成的开发阶段。

技术栈

• 全栈框架：Next.js 16+（React），使用 App Router。
• 数据库：PostgreSQL。
• ORM：Prisma。
• 身份验证：使用严格会话 cookie（浏览器关闭时清除）和 Argon2id 进行密码哈希的自定义实现。密码强制要求至少 16 个字符，且必须包含符号、数字和大小写混合字母。
• 样式：页面面板采用带有玻璃拟态深色模式美学的原生 CSS；模态框通过 Modal.tsx 和 globals.css 中的 .modal-panel 实现完全不透明。

数据库 Schema

报告相关新增内容：Finding 还存储 version、reviewStatus、authorId、reviewerId、templateId 和 importFingerprint；Screenshot 存储 sortOrder。FindingTemplate 保存经过审核的可复用措辞；FindingRevision 保存不可变的文本修订；FindingDraft 保存每个用户的私有草稿及其冲突版本；FindingComment 记录审核讨论；EngagementReport 保存报告标题、执行摘要和有序的 finding ID；IssuedReport 为每个已发布版本存储不可变的 PDF、内容快照和 SHA-256 摘要。用户作者/审核者关系使用 SetNull；当用户被删除时，其私有草稿也会被移除。报告记录遵循其父 engagement/finding 的生命周期。

• User：id、username、passwordHash、role（Admin、User）、lastPasswordChange、lastLogin、sessions、createdAt、updatedAt。
• Session：id、userId、expiresAt、createdAt — 服务端记录使每个已签名的登录会话在注销时可单独撤销。
• LoginRateLimit：key、count、 — 原子化的来源和密码确认尝试预留。密码验证还具有有界并发限制。

添加新字段

要向现有模型添加新字段（例如，向 Engagement 添加 focus）：

1. 打开 prisma/schema.prisma，将字段添加到所需模型： ```prisma model Engagement { id String @id @default(uuid()) codeName String focus String? // new field ... }
   root@kitploit:~

2. 每次对 prisma/schema.prisma 的更改都必须紧随以下操作： ```bash npx prisma migrate dev --name describe_your_change
   root@kitploit:~

这会创建一个迁移、更新数据库，并重新生成 Prisma Client 类型。

3. 根据需要更新任何受影响的 UI 组件、表单、验证逻辑或服务器操作。

安全架构

1. 身份验证与账户：默认的 admin 账户通过 Prisma seed 生成。Admin 角色对所有记录拥有完整的创建/编辑/删除权限。User 角色可以创建、编辑和删除 findings 和 screenshots；所有其他实体（engagements、clients、contacts、operators）对用户而言为只读。每个仪表板页面在读取机密数据之前都会针对数据库刷新会话。只有管理员可以访问 Admin 页面（/dashboard/users）、管理账户、更改应用程序范围的高亮颜色，以及备份、恢复或重置数据库。备份、恢复和重置需要重新确认密码。创建备份是一个 Server Action；浏览器下载使用 GET /api/db/backup?file=…，需携带 Admin 会话以及一个存储在 HttpOnly cookie 中的五分钟签名授权。
2. 会话管理：会话使用存储在 HttpOnly、SameSite=Lax cookie 中的 jose JWT，以及一个匹配的服务器端 Session 行，注销时会撤销该行。有意省略 cookie 过期时间以保持浏览器会话行为；签名令牌和数据库记录均在一天后过期。事务性准入每个账户最多保留十个活动会话。
3. 应用程序安全：
   • Next.js Edge Proxy（src/proxy.ts）对所有受保护路由强制执行会话检查和 90 天密码轮换。
   • Next.js Server Actions 通过内置的同源保护降低 CSRF 风险。
   • Prisma 通过参数化所有查询自动缓解 SQL 注入。
   • React 通过在渲染时自动转义 HTML 元素来缓解 XSS。
   • Screenshots 以仅所有者权限存储，并设有聚合/按 finding 的有界配额。删除使用可恢复的待处理标记；仪表板启动、上传和备份会根据数据库引用对磁盘文件进行核对，清理失败会记录在审计输出中，详细错误记录在服务器日志中，并向管理员显示警告。失败的仪表板核对每个进程每分钟最多重试一次；上传和备份仍会立即验证存储。经过身份验证的 路由可防止 IDOR 并返回 响应。