简介：这是一套面向渗透测试团队与安全初学者的报告管理与自动化扫描工具，采用 JavaScript 与 Python 混合实现，重点解决测试范围登记、重复扫描执行和成果归档三类问题，适合安全服务交付、教学演练与报告规范化参考。压缩包共 109 个文件、约 90.93MB，包含 26 个 js 前端与业务脚本、16 个 py 动作模块、11 个 css 样式、10 个 sh 启动脚本，以及 docx 报告样例、dockerfile、md 说明和图片素材，目录按前端、动作、配置与文档分层，便于按模块检索。目前已有 416 人学习。工具支持维护参与列表与可自定义属性、自动执行 nmap、dirb、showmount、EyeWitness、nikto 等初始扫描并留存 Web 截图；发现项可分级描述、附加证据，并通过可自定义模板导出 docx 报告；实验性知识模块还能利用已知 SSH 凭据演示横向移动。内部以 NodeJS+React、动作容器与 MongoDB 三容器协作，覆盖从范围定义、扫描取证到报告输出的完整链路，可减少重复劳动并沉淀可复用的检查清单与证据材料。

1. 报告写不完的那一晚：我为什么把渗透测试报告当成工程来做

凌晨两点，授权测试收尾，扫描器吐出的原始结果、抓包记录、手工验证的截图散在四个目录里，交付时间在早上九点。那晚我第一次认真去找一个渗透测试报告工具，翻到了 pentest-report，一个用 JavaScript 写、把「结构化数据」和「报告呈现」拆开处理的项目。后来我把它跑通、按团队模板改了一遍，报告从熬一整夜变成跑一条命令。这篇写的是落地过程：五条评判维度、一份 finding 字段表、两段可复现的转换与脱敏脚本，还有五处我真实翻过车的地方。做授权评估的同行、被报告格式折磨过的安全工程师、刚入行不知道怎么把发现写清楚的新人，都能直接抄作业。

2. 先定评判维度：渗透测试报告工具该满足的五条硬指标

判断一个报告工具好不好，我一般不看模板漂不漂亮。某次给一家客户交付六十多页报告，事后沟通才发现，技术负责人只翻了「复现步骤」那几节，业务负责人只看了第一页的风险分布，剩下五十页没人打开过。这说明报告天然有多条阅读路径，工具的价值在于能不能用一份数据同时喂饱这些路径，而不是能不能做出花哨的封面。下面三条小节，讲的是我怎么把「好看」翻译成「可验收」。

2.1 三类读者倒推出来的功能清单

一份渗透报告至少有三类读者，诉求完全不同。客户的技术负责人要的是「我能照着复现、能定位到具体配置项」；客户的业务或管理层要的是「风险有多大、影响哪些业务、先修哪个」；复测人员往往是半年后的另一个人，甚至是你团队里没参与过这个项目的新同事，他要的是「当时打的是哪个环境、用了什么前提、预期结果是什么」。三类读者对应三种信息密度，任何一类被牺牲，报告的实际价值就打折。

从这三条诉求倒推，一个合格的报告工具至少要满足五件事。第一，一份数据源能出两种视图，管理层摘要和技术详情不能是两份文档各自维护。第二，每条 finding 有稳定可寻址的编号，复测时能一一对应上，不能靠「第三条高危」这种描述定位。第三，证据可以挂载，请求响应、命令输出、截图要跟着 finding 走，而不是散在附录里靠人工对照。第四，模板可改但不触碰数据，换客户换封面不该动到漏洞描述。第五，输出格式至少两种，Markdown 给内部评审和版本管理，PDF 给正式交付。

这张表里最容易被忽略的是第二行和第三行。可复现性决定了报告是「证据」还是「故事」，分级一致性决定了客户信不信你的判断。我见过一份报告，摘要写「高危」，详情页的 CVSS 向量算出来是 5.3 中危，客户当场就问了句「到底哪个算数」。这种问题不是写作水平问题，是工具没有把「分数」和「文字」绑在同一个计算链上。

2.2 数据与呈现分离：一条 finding 只能有一个真相源

早期我是拿文档模板直接写的。一条注入漏洞，摘要里写「某接口存在注入」，详情里写「参数未做过滤」，附录的修复建议里又重复一遍「应使用参数化查询」。同一个事实出现三次，改一次忘两处。有一次交付前夜临时把一条中危改成高危，摘要改了，详情页的标签忘了动，客户对着两个级别问了一下午。这就是没有单一真相源的代价，跟工具无关，跟组织方式有关。

把 finding 抽成独立数据之后，逻辑变成：数据层只存事实（标题、级别、向量、受影响资产、复现步骤、证据、修复建议），呈现层只负责把这些事实摆到不同位置。摘要页读的是 severity 字段，详情页读的也是 severity 字段，附录的风险统计还是读这个字段。改一处，三处同步。这件事听起来很基础，但真正落地的时候，绝大多数人卡在「描述怎么写」上，因为自然语言的描述没法复用。

我的处理办法是把描述拆成三段固定结构：一段事实（什么组件、什么位置、什么条件下触发），一段影响（能读到什么、能改到什么、影响哪个业务），一段证据指向（对应哪几个证据文件）。三段都存成独立字段，渲染时再拼。这样同一条 finding 在摘要视图里只取第一段，在详情视图里拼三段，在复测视图里只取第三段和状态字段。数据没变，视图变了。

提示：判断工具有没有真正做到分离，最简单的办法是问一句「换一套模板，需要动数据文件吗」。需要动，就说明还粘在一起。

2.3 JavaScript 栈的三条路：手写文档、自研脚本、现成工具

做报告这件事，行业里实际上有三条路。第一条是纯手写，用文档软件套模板，灵活但不可复用，项目一多就是体力活。第二条是自研脚本，拿 Python 或 Node 写一堆字符串拼接，前期快，后期模板一复杂就变成维护地狱。第三条是用现成的报告工具，把数据和模板交给它，自己只维护内容和少量定制。pentest-report 属于第三条，用 JavaScript 写成，这意味着它跑在 Node 上，不需要额外起服务，也能塞进流水线里。

JavaScript 这条路有它的代价，得说清楚。好处是生态成熟，模板引擎、Markdown 解析、HTML 渲染都有现成轮子，团队里做过前端的人上手几乎没有门槛；同构能力也让 HTML 预览变得简单，改完模板刷新一下就能看效果。代价在导出环节，PDF 一般要走无头浏览器渲染，中文字体得单独配，长表格的分页和表头重复需要额外处理，批量导出几十份的时候内存占用也要盯着。这些都不是致命问题，但如果你打算把它塞进流水线自动跑，得提前留出调试时间。我选它的理由很朴素：团队里 JavaScript 的人最多，谁都能改，工具不会变成某个人的私有财产。

3. 把发现做成数据：finding 字段设计与转换脚本

从这一章开始动手。整条链路是「原始输出 → 归一化 → 结构化 finding → 渲染」，每一段都能单独跑、单独验。我一般会先把字段定死再写模板，反过来做的话，模板写到一半一定会发现缺字段，然后回头改数据结构，前面写好的渲染逻辑全得重来。这个顺序的血泪经验，比任何工具选型都值钱。

3.1 一条 finding 的字段表

字段设计的原则是：凡是会影响阅读、影响复测、影响统计的信息，都必须是一等字段，不能塞进自由文本里。比如「受影响资产」如果写进描述段落，就没法自动生成资产维度的统计表；「复测状态」如果写在备注里，就没法一键筛出未修复项。

severity和cvss_vector这两个字段要特别说。很多人习惯手填级别再手填分数，结果是两者对不上。正确做法是只填向量，分数由脚本算，级别由分数按固定区间映射。这样改向量的时候，分数和文字一起变，不会出现摘要高危、详情中危的尴尬。CVSS 的计算本身有公开公式，写个几十行的实现就够，关键是别让人去手算。

steps用数组而不是一段文本，是为了渲染时能自动编号。报告里的步骤编号一旦手写，中间插一步就要全部重排，这是最典型的翻车点之一。数组渲染出来的编号永远连续，插入删除都不用心算。

3.2 证据与复现步骤怎么组织才经得起复测

复测是报告价值的分水岭。半年后另一个人拿着你的报告去验证，如果步骤写的是「用抓包工具改包，如图 7」，他大概率要花半小时才能还原你当时的操作。我的写法是每一步都必须包含三个要素：做了什么操作、输入是什么（可以是占位符）、预期看到什么结果。第三个要素最容易被漏掉，但它是判断「漏洞是否仍然存在」的唯一依据。

证据的挂载方式我一般用相对路径加一句说明，而不是把图片全塞进报告正文。原因是正文里塞大图会让分页彻底失控，而且复测的人更需要原始请求响应文件，不是截图。具体做法是在 finding 里存一个 evidence 数组，每项包含文件路径、类型（请求响应 / 命令输出 / 截图）和一句话说明，渲染时正文只放缩略图和文件名，完整内容作为附件目录随报告一起交付。

{ "id": "F-003", "title": "订单查询接口参数拼接导致注入", "severity": "high", "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:L/A:N", "assets": ["order-api /api/v2/order/query 参数 orderNo"], "description": "接口在拼接查询条件时未对 orderNo 做类型校验，单引号输入触发语法异常。", "impact": "测试环境下可读取同库内其他订单表的部分字段，生产环境影响范围需结合库权限评估。", "steps": [ { "do": "以普通账号登录，抓取查询请求", "input": "orderNo=正常单号", "expect": "返回当前账号订单" }, { "do": "将 orderNo 替换为单引号结尾的探测值", "input": "orderNo=<探测值>", "expect": "返回 500 并暴露数据库错误页" }, { "do": "对比正常请求与异常请求的响应差异", "input": "同上", "expect": "异常响应中含 SQL 语法片段" } ], "evidence": [ { "path": "evidence/F-003/req.txt", "type": "request", "note": "原始请求，已脱敏 Cookie" }, { "path": "evidence/F-003/resp.txt", "type": "response", "note": "异常响应，含错误堆栈" } ], "remediation": "将 orderNo 改为参数化绑定，并在入口处做长度与字符集白名单校验。", "status": "open", "found_at": "2024-05-11" }

这段结构里没有一处自由文本承担「结构」职责，描述和影响是纯内容，步骤和证据是数组。渲染层拿到它，可以生成摘要卡片、详情页、复测清单三种视图，不需要额外加工。这就是前面说的单一真相源落地后的样子。

3.3 从扫描器原始输出到结构化数据的归一化脚本

真实项目里，finding 不可能全靠手敲。扫描器导出的结果、自己写的小工具输出、手工补录的条目要合并到一起，格式各不相同。我一般写一个归一化脚本，把各种来源统一成上一节那个结构，再交给报告工具渲染。这个脚本不需要多聪明，关键是幂等：同一份原始数据跑两次，输出必须完全一致，否则版本管理就没法用。

// normalize.js —— 把扫描器导出结果归一化成 finding 结构 const fs = require('fs'); const path = require('path'); // 不同来源的级别用词不一样，先统一到五档 const SEVERITY_MAP = { critical: 'critical', high: 'high', medium: 'medium', low: 'low', info: 'info', informational: 'info', warn: 'medium', error: 'high' }; // 分数区间到级别的映射，保证文字和分数同源 function scoreToSeverity(score) { if (score >= 9.0) return 'critical'; if (score >= 7.0) return 'high'; if (score >= 4.0) return 'medium'; if (score > 0) return 'low'; return 'info'; } function normalize(rawList, sourceName) { let seq = 0; return rawList.map((raw) => { seq += 1; // id 用来源前缀 + 序号，跨来源不冲突，重跑结果稳定 const id = `F-${sourceName.toUpperCase()}-${String(seq).padStart(3, '0')}`; const score = Number(raw.cvss_score || 0); return { id, title: raw.name || raw.title || '未命名发现', severity: scoreToSeverity(score), cvss_vector: raw.cvss_vector || '', assets: Array.isArray(raw.affected) ? raw.affected : [raw.host || ''], description: raw.detail || '', impact: raw.impact || '', steps: (raw.repro || []).map((s) => ({ do: s, input: '', expect: '' })), evidence: [], remediation: raw.fix || '', status: 'open', found_at: raw.found_at || new Date().toISOString().slice(0, 10) }; }); } // 入口：读一个来源，写一个归一化结果，文件名固定便于比对 const [, , inputFile, sourceName] = process.argv; const raw = JSON.parse(fs.readFileSync(inputFile, 'utf8')); const out = normalize(raw.findings || raw, sourceName || 'src'); fs.writeFileSync( path.join('data', `findings-${sourceName}.json`), JSON.stringify(out, null, 2) ); console.log(`normalized ${out.length} findings from ${sourceName}`);

几个参数得说明白。sourceName决定 id 前缀，多来源合并时靠它区分，别用随机数或时间戳，否则每次重跑 id 都变，复测记录全断。scoreToSeverity的区间是 CVSS 3.1 的通用分档，如果你的客户有自己的分档标准，改这一个函数就够，不要去改渲染层。padStart(3, '0')保证序号定宽，排序和查找都方便。脚本最后把结果写到data/目录，文件名固定，配合版本管理能直接看出两次跑出来的差异。

跑法很简单：

node normalize.js raw/scan-20240510.json scan node normalize.js raw/manual-notes.json manual

两条命令产出两份结构化数据，后面渲染时一起读进来。手工补录的那份用同样结构写，就能和扫描器结果混合排序，不会出现「机器发现排在前面、人工发现散在最后」这种阅读体验。

4. 渲染层复现：模板分层、脱敏检查与多格式输出

数据齐了之后，渲染层要解决三个问题：结构怎么分层、敏感信息怎么拦住、多种格式怎么一次出完。这三件事如果混在一起做，最后一定是一团乱麻——模板里写脱敏逻辑，脱敏规则又依赖输出格式，改一处崩三处。分开做，每层只管一件事。

4.1 模板分三层：骨架、章节、组件

我一般把模板拆成三层。骨架层决定整份报告的章节顺序和目录，通常是一个配置文件，改顺序不用碰任何模板代码。章节层决定每一节长什么样，比如「风险概览」是一张统计表加一段文字，「漏洞详情」是若干条 finding 的循环。组件层是最小的可复用单元，比如一个严重级别标签、一个证据缩略图块、一个复现步骤列表。

分层的直接好处是加内容不动结构。客户临时要求加一节「测试范围与方法」，只需要在骨架配置里插一行，指向一个已有的章节模板，其余不动。反过来，如果要改严重级别标签的配色，只动组件层一个文件，全篇生效。我见过太多报告项目把这三层糊在一个大模板里，改一个标签颜色要全文搜索替换，替换完还漏两处。

排序规则也要放在配置里，不能写死。默认按严重级别降序，同级按发现时间升序，这两条规则写在骨架配置的一个字段里，改排序不用改代码。分类维度的统计表则从category字段动态聚合，新增分类不用改模板。

4.2 脱敏与红线检查：交付前必须过的机器关卡

脱敏靠人眼盯，迟早出事。我吃过一次亏：报告正文里的测试账号都处理了，附录的原始请求文件里还留着完整的会话凭据，交付前半小时才发现。从那以后我把脱敏做成脚本，输出前强制跑一遍，不通过就不允许生成最终文件。

规则的设计思路是「宁可多拦，不可漏放」。内网地址、会话凭据、测试账号口令、真实业务数据样本，这四类必须有对应规则。规则写成数组，每条包含名称、正则和替换文本，跑的时候逐条扫，命中就替换并记一条日志，最后输出一份「替换了多少处、分别在哪几个文件」的清单。这份清单本身也是交付物的一部分，客户看到你主动做了脱敏，信任度完全不一样。

// scrub.js —— 输出前的脱敏关卡，命中即替换并记录 const RULES = [ { name: '内网地址', // 覆盖三段常见私网段，避免只拦 192.168 漏掉 10 段 re: /\b(?:10\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])|192\.168)\.\d{1,3}\.\d{1,3}\b/g, to: '[内网地址已脱敏]' }, { name: '会话凭据', // 只匹配请求头里的值，避免误伤正文里的普通长串 re: /((?:Cookie|Authorization|X-Token)\s*:\s*)[^\r\n]+/gi, to: '$1[凭据已脱敏]' }, { name: '测试账号口令', re: /(pass(?:word)?\s*[=:]\s*)["']?[^\s"',]{4,}/gi, to: '$1[口令已脱敏]' } ]; function scrub(text) { let hits = []; let out = text; for (const rule of RULES) { out = out.replace(rule.re, (...args) => { hits.push(rule.name); return typeof rule.to === 'function' ? rule.to(...args) : rule.to; }); } return { text: out, hits }; } module.exports = { scrub, RULES };

这段代码有几个细节值得说。re带g标志且每次调用前不能复用同一个正则对象，否则lastIndex会残留，导致第二次扫描漏匹配——这是个很隐蔽的坑，我在批量处理时踩过。替换文本里用$1保留字段名，只脱敏值，这样复测的人还能看出这里原本是个 Cookie 头。hits数组记录命中次数，最后汇总成清单，谁在哪个环节加的规则一目了然。

注意：脱敏要在「生成最终文件之前」跑，不能对已生成的文件做后处理。后处理会破坏目录页码、图片引用和附件索引，改完还得重新排版。

4.3 一条命令出三种格式：参数怎么配

三种格式的定位要分清。Markdown 用于内部评审和版本管理，diff 友好，改一句话能看出改了哪。HTML 用于预览和发给客户看在线阅读，样式可控，图片和表格不会崩。PDF 用于正式交付和归档，分页固定，打印出来不会变形。

# 生成三种格式，输入是归一化后的数据目录 node render.js \ --data data/ \ --config config/report.yaml \ --out dist/ \ --formats md,html,pdf \ --title "某系统授权评估报告" \ --client-code "CLIENT-A"

--data指向归一化后的目录，脚本会把目录下所有findings-*.json合并，按 id 排序去重。--config是骨架配置，章节顺序和封面信息都在里面。--out是输出目录，三种格式各自建子目录，附件按 finding id 分文件夹，方便单独拷贝。--formats支持逗号分隔，调试时只出 md，快得多。--client-code会写进页脚，多客户并行时避免拿错文件。

PDF 环节要单独留时间调试。中文字体必须在配置里显式指定，不能靠默认字体，否则导出后中文变方块，这几乎是所有人第一次用无头浏览器渲染都会遇到的现象。长表格要在样式里设表头重复，不然跨页之后读者不知道每一列是什么。图片按容器宽度等比缩放，别用固定像素，否则不同分辨率的证据截图会撑破版心。

5. 避坑与常见问题：五处最容易翻车的地方

这一章列的都是我或同行真实遇到过的。每一条按「现象、原因、解决」写，照着排查能省下不少返工。

5.1 输出环节的三处翻车

PDF 里中文全部变成方块。现象是导出的 PDF 打开一看，所有汉字都是方框，英文和数字正常。原因通常有两个：一是无头浏览器所在的运行环境没有装中文字体，二是样式里指定的字体名在系统里不存在，渲染器回退到了不含中文字形的默认字体。解决分两步，先在环境里装一套中文字体并刷新字体缓存，再在报告样式里把font-family显式写成已安装的字体名，并在其后保留通用回退。验证方法是导出一页含中英文混排的测试页，别拿完整报告试。

表格跨页后表头消失，读者看不懂列。现象是长表格翻到第二页，第一行直接是数据，不知道每列对应什么。原因是样式里没有设置表头重复，或者表格被包在一个不允许分页的容器里导致整块被推到下一页、中间留大片空白。解决是把表头行设为跨页重复，同时给表格容器加上允许内部断页的属性，行级别再加一条禁止单行被拆开的规则。改完一定要用一份超过三页的表格实测，短表格测不出来。

同一份数据导出两次，PDF 页码对不上。现象是内部评审版和交付版内容一样，但目录页码差了一两页。原因通常是封面或附录里有动态内容，比如生成时间戳占了额外一行，或者图片加载顺序不稳定导致排版高度变化。解决是把所有可能影响布局的动态内容固定成模板变量，图片统一指定宽高比并预加载，导出前先渲染一次 HTML 确认总页数，再出 PDF。

5.2 数据与流程环节的两处翻车

复测时对不上号，不知道哪条修了哪条没修。现象是半年后复测，报告里的编号和当时记录的对不上，有的编号被复用，有的条目消失了。原因是 id 用序号自动生成且在每次归一化时重排，新增一条就把后面的全顶掉。解决是把 id 的生成规则改成「来源前缀加稳定序号」，并且在合并多来源数据时保留原始 id，绝不因为排序而重新编号。已经交付的报告，id 一旦定下就不能再变，这条要写进团队约定里。

报告里的严重级别和 CVSS 分数互相打架。现象是摘要写高危，详情页的向量算出来是中危。原因是级别和分数是两个人分别填的，或者一个人填完向量又手动改了级别。解决是把级别变成派生字段，只允许填向量，分数由脚本算、级别由分数映射，渲染时不允许覆盖。人工判断有偏差时，不去改级别，而是在 finding 里加一个「调整理由」字段，写明为什么在实际业务背景下要上调或下调，这样既保留了专业判断，又不破坏数据一致性。这个字段在客户质疑时特别有用，它把「我觉得」变成了「有依据的调整」。

6. 交付前的十二项自查：我会强制走一遍的那张表

报告工具跑通之后，最后一道关卡还是人。我现在的习惯是交付前拿出固定的一张表逐项过，不管项目多小，一项不落。这张表不是流程装饰，它是被返工逼出来的——有一次漏查附件目录，客户收到的压缩包里少了三份证据文件，补发的过程比重新做一遍还麻烦。

这十二项里，第 3 项和第 11 项最费时间，但也最能体现专业度。第 3 项我一般会拉一个没参与项目的同事，随机抽一条中危，让他只看报告不看别的，走一遍复现流程；他卡在哪一步，那一步就是报告要改的地方。第 11 项的判断标准很土：把修复建议单独发给一个不做安全的开发，问他知不知道改哪个文件，答不上来就说明写得太虚。

一条命令把这套检查跑一半：

# 交付前的机器检查：编号唯一、引用存在、脱敏日志 node check.js --data data/ --evidence evidence/ --report dist/report.md

脚本会输出三类结果：重复或跳号的 id、指向不存在文件的证据引用、以及脱敏命中的汇总。剩下的一半靠人，字体、分页、目录页码这些机器判断不了「读起来对不对」。

回过头看，那晚熬到两点真正的问题不是工具不好用，是我把报告当作文档在写，而不是当作数据在管。从那以后我每次开新项目，第一件事就是把 finding 字段表定下来，第二件事是把脱敏脚本接进流程，报告模板反而是最后才动的。顺序对了，返工就少了。希望帮到你。

本文还有配套的精品资源，点击获取