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

| 扫描器/导出系列 | 接受的导出格式 |
|---|---|
| Burp Suite | Issues XML,包括惰性内部 schema DTD |
| Nessus / Tenable | Nessus v2 XML(.nessus) |
| Nmap | XML;开放端口及其脚本输出会成为信息性观察记录,而非推断出的漏洞 |
| OpenVAS / Greenbone | 原生 XML 报告或 GMP get_reports_response |
| OWASP ZAP | 包含站点和警报的传统 JSON 报告 |
| Nuclei | JSON Lines(-jsonl) |
| Qualys | 扫描结果 XML(SCAN/IP 结构),而非单独的主机检测 API 格式 |
| Semgrep / CodeQL 及其他 SARIF 生成器 | SARIF JSON 运行、规则和结果 |
每次导入的导出文件限制为 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 的草稿状态开始,现有浏览器 Cookie 必须重新登录,以便获得由服务端支持的会话 ID。不要重置现有数据库。备份通过现有的全数据库导出包含新表和已签发的 PDF。
npm test
npm run lint
npx tsc --noEmit --noUnusedLocals --noUnusedParameters
npm run build
npm audit
npm test 使用 Node 的非隔离测试模式并配合 tsx,以便各个 TypeScript 测试用例真正执行,而不仅仅是报告文件子进程成功。请在 CI 中保持显式的断言总数可见。
数据库和浏览器回归测试需要一个名为 reporting_tests 的专用本地数据库,并已应用迁移。它们会创建并删除自己的 fixture 行;切勿将这些测试指向应用程序数据库。将 REPORTING_TEST_DATABASE_URL 设置为该测试数据库,可以在 shell 中导出,或在 .env 中设置(测试命令仅从中读取 REPORTING_TEST_DATABASE_URL 和 REPORTING_TEST_BROWSER),然后运行:
DATABASE_URL="$REPORTING_TEST_DATABASE_URL" npx prisma migrate deploy # needs the variable exported in your shell
npm run test:reporting
npx playwright install chromium
npm run test:browser
浏览器测试套件会在端口 3317 上启动自己的回环开发服务器,并使用仅用于测试的会话密钥;它拒绝复用已有的服务器,而 Next.js 每个项目只允许一个 next dev,因此请先停止任何正在运行的 npm run dev。如有需要,可将 REPORTING_TEST_BROWSER 设置为已安装的 Chromium 可执行文件。它测试草稿隐私、冲突编辑、证据上传、独立审查、PDF 权限/不可变性、无需 JavaScript 的模板创建,以及选择性去重导入。集成测试会实际触发事务冲突和回滚。这些测试套件不能替代远程局域网、Safari 或生产部署验证。
本应用程序设计为在 Ubuntu 上运行,并需要以下条件:
sudo apt update && sudo apt install -y nodejs npm postgresql postgresql-client postgresql-contrib zip
postgresql-client 提供 pg_dump、pg_restore 和 psql;zip 用于创建备份归档。恢复时的解压由应用程序处理,并带有严格的条目和大小校验。
安装这些软件包并不总会让 PostgreSQL 保持运行。在创建角色或启动应用之前,请先启动并启用该服务:
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 文件:
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 名称。生产构建会忽略此项。 |
UPLOADS_DIR | 否 | 用于存放证据截图的文件夹;默认为应用程序根目录下的 uploads/(相对路径从该目录解析)。每个数据库需要自己的文件夹:截图清理会删除其数据库未引用的文件。浏览器测试套件使用 .browser-test-uploads/。 |
生成一个强密钥:
openssl rand -base64 32
请先确保 PostgreSQL 正在运行(参见先决条件)。自动化脚本 ./setup.sh 会为你启动该服务;下面的手动步骤假设它已经启动。
运行以下命令以创建 PostgreSQL 数据库和用户:
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 或超级用户权限:
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/)。
在仓库根目录下运行:
chmod +x setup.sh
./setup.sh