需要生成带漏洞跟踪、实时风险统计和多语言 PDF…

适用于渗透测试或漏洞评估场景，需要结构化记录漏洞、自动统计风险并导出企业级 PDF 报告。

适用场景

解决思路

1. 使用 Docker 快速启动：docker build -t pentestify:latest .；docker run -d -p 8000:8000 -v pentestify_data:/app/data --name pentestify pentestify:latest；访问 http://localhost:8000
2. 手动安装：git clone https://github.com/ccyl13/Pentestify.git；cd Pentestify；python3 -m venv venv；source venv/bin/activate（Windows 用 venv\Scripts\activate）；pip install -r requirements.txt；playwright install chromium；python3 run.py；访问 http://localhost:8000
3. 了解架构：前端 SPA 由 index.html、js/app.js、css/styles.css 组成，通过 HTTP/REST 调用 FastAPI 后端（main.py、models.py、schemas.py、database.py），数据存于 SQLite 的 pentestify.db，包含 reports 和 findings 表
4. 创建报告：POST /api/reports，JSON 包含 client_name、report_date、auditor_name、executive_summary、scope、methodology、language（en 或 es）
5. 获取所有报告：GET /api/reports，返回报告元数据列表
6. 获取单个报告：GET /api/reports/{report_id}，返回完整报告及所有 findings
7. 更新报告：PUT /api/reports/{report_id}，请求体同 POST
8. 删除报告：DELETE /api/reports/{report_id}，级联删除所有关联 findings
9. 添加 finding：POST /api/reports/{report_id}/findings，JSON 包含 title、severity（critical、high、medium、low、info）、cvss_score、description、impact、affected_systems、evidence、remediation、references、order_index
10. 重排 findings：PUT /api/reports/{report_id}/findings/reorder，body 为 { finding_ids: [3,1,2,4] }
11. 删除 finding：DELETE /api/findings/{finding_id}，自动重排剩余 order_index
12. 导出 PDF：GET /api/reports/{report_id}/export/pdf，返回带企业格式的 PDF 下载
13. 数据库备份：GET /api/database/export，返回 pentestify.db 文件
14. 数据库导入：POST /api/database/import，form-data 字段 file 传 pentestify.db
15. 创建自定义漏洞模板：在 backend/models.py 扩展 FindingTemplate 类，字段 id、name、severity、cvss_base、description_template、remediation_template、cwe_id；实现 to_finding(report_id) 方法转换为 Finding
16. 添加认证端点：在 backend/main.py 使用 HTTPBearer 和 verify_token，从环境变量 PENTESTIFY_API_TOKEN 读取期望 token；未配置返回 501，无效返回 401；受保护端点用 dependencies=[Depends(verify_token)]
17. 自定义 PDF 样式：修改 backend/main.py 的 PDF 生成，使用 playwright.async_api，注入 @page A4 margin 20mm、页眉 CONFIDENTIAL - Internal Use Only、severity-critical 等 CSS；调用 page.pdf 参数 format='A4'、print_background=True、display_header_footer=True、header_template、footer_template；最后关闭浏览器
18. 前端调用 API 创建报告：在 js/app.js 用 fetch POST /api/reports，设置 Content-Type application/json，JSON.stringify(reportData)，检查 response.ok，返回 JSON
19. 前端添加 finding：构造 finding 对象，用 getNextOrderIndex 获取 order_index，fetch POST /api/reports/{reportId}/findings
20. 前端导出 PDF：fetch GET /api/reports/{reportId}/export/pdf，获取 blob，创建 URL，设置 a.download 为 pentest-report-{reportId}.pdf，点击下载后 revoke URL
21. 前端加载报告：fetch GET /api/reports/{reportId}，填充表单字段 client-name、report-date，按 order_index 排序 findings 并渲染
22. 实现拖拽排序：监听 dragstart 添加 dragging 类，dragend 移除并调用 saveFindingsOrder，dragover 用 getDragAfterElement 根据 Y 位置插入元素
23. 保存排序：获取所有 .finding-item，映射 dataset.findingId 为整数，获取当前 reportId，fetch PUT /api/reports/{reportId}/findings/reorder，body 为 { finding_ids: findingIds }
24. 自动保存：选择 #report-form 的 input 和 textarea，监听 input 事件，清除 timeout，2000ms 后调用 saveReport 并显示通知
25. saveReport 实现：从表单收集 client_name、report_date、auditor_name、executive_summary、scope、methodology、language，获取 reportId，fetch PUT /api/reports/{reportId}，body 传 JSON
26. 严重性徽章渲染：getSeverityBadge 映射 critical 为 #dc3545、high 为 #fd7e14、medium 为 #ffc107、low 为 #0dcaf0、info 为 #6c757d，返回带样式的 span
27. 实时统计：updateStatistics fetch GET /api/reports/{reportId}，计算 total、critical、high、medium、low、avgCvss，更新 DOM 的 stat-total、stat-critical、stat-high、stat-avg-cvss
28. 运行测试：python -m pytest backend/tests/ -v；python -m pytest backend/tests/test_reports.py -v；python -m pytest backend/tests/ -v --cov=backend --cov-report=html；pytest-watch backend/tests/
29. 编写测试用例：test_add_finding_to_report 用 TestClient POST finding，断言 status_code 200 以及 data 的 title、severity、id；test_reorder_findings 反转 finding_ids，PUT reorder，断言 200，GET 报告验证 order_index 与 new_order 一致
30. 配置环境变量：在 .env 文件中设置 PENTESTIFY_API_TOKEN、PENTESTIFY_DB_PATH、PENTESTIFY_HOST、PENTESTIFY_PORT、PENTESTIFY_LOG_LEVEL
31. Docker 卷管理：docker volume create pentestify_data；备份用 docker run --rm -v pentestify_data:/data -v $(pwd):/backup alpine cp /data/pentestify.db /backup/pentestify_backup.db；恢复用 docker run --rm -v pentestify_data:/data -v $(pwd):/backup alpine cp /backup/pentestify_backup.db /data/pentestify.db
32. 自定义端口：docker run -d -p 9000:8000 -v pentestify_data:/app/data pentestify:latest，访问 http://localhost:9000
33. 修复 PDF 生成失败：若报 Playwright browser not found，执行 playwright install chromium；Docker 中则 docker build --no-cache -t pentestify:latest .
34. 修复数据库锁定：在 backend/database.py 增加 timeout，create_engine(SQLALCHEMY_DATABASE_URL, connect_args={'check_same_thread': False, 'timeout': 30})
35. 修复 findings 不重排：检查 order_index 初始化，实现 fix_missing_order_indexes(db, report_id)，遍历 findings，若 order_index 为 None 则设为 idx，提交
36. 修复 CORS 问题：在 backend/main.py 添加 CORSMiddleware，allow_origins=['http://localhost:3000', 'http://127.0.0.1:8000']，allow_credentials=True，allow_methods=['*']，allow_headers=['*']
37. 修复报告不保存：检查浏览器控制台错误，在 saveReport 加 try/catch，console.error，showNotification 错误
38. CI/CD 集成：.github/workflows/test.yml，on push 和 pull_request，job test 在 ubuntu-latest，步骤 checkout、setup-python 3.9、安装依赖 pip install -r requirements.txt 和 playwright install chromium、运行测试 python -m pytest backend/tests/ -v --cov=backend、构建 Docker 镜像 docker build -t pentestify:test .
39. Nginx 反向代理：/etc/nginx/sites-available/pentestify，server listen 80，server_name pentest.example.com，location / 时 proxy_pass http://localhost:8000，设置 Host、X-Real-IP、X-Forwarded-For 头；location /api/reports/*/export/pdf 时 proxy_pass http://localhost:8000，proxy_read_timeout 120s

适用边界 · 注意事项

• 不适用于非渗透测试或非漏洞评估的通用业务报告。
• 不适用于需要复杂多人协作、细粒度权限或高并发读写的生产环境（SQLite 单文件，仅简单 token 认证）。
• 不适用于无法安装 Docker、Python、Playwright 或不允许使用第三方开源工具的环境。