第 94 章 报告与图表生成（docs-generator / diagram-generator）
分析的最终交付物是报告和图表：逆向报告、渗透报告、CTF writeup、攻击路径图、架构图。本章讲"怎么写好安全文档"和"怎么画好安全图表"——分析占一半，呈现占一半。
📍 知识点地图 | 主题：报告与图表 | 前置：全书 | 后续：— | 核心概念：渐进披露、证据完整、Mermaid、Graphviz
94.1 安全文档写作原则（docs-generator）
三大核心原则
1. 渐进披露（Progressive Disclosure）:
先给结论，再给细节（读者按需深入）
→ 摘要 → 关键发现 → 详细步骤 → 附录
2. 面向任务（Task-Oriented）:
每节回答一个"读者要做什么"的问题
→ 不堆砌信息，聚焦决策点
3. 展示而非讲述（Show, Don't Tell）:
用命令/输出/截图/图表证明，不空口描述
→ 每条结论都有证据
文档结构规范
安全报告标准结构:
1. 执行摘要（决策者: 结论+风险等级）
2. 范围与方法（做了什么/没做什么）
3. 发现列表（按严重性排序）
4. 每个发现: 复现步骤+证据+影响+修复
5. 攻击路径（红队: 完整链）
6. 时间线（取证/IR 报告）
7. 附录（IOC/工具/完整输出）
CTF writeup 结构:
1. 题目信息（类型/难度）
2. 思路（从哪入手）
3. 解题步骤（带命令和输出）
4. Flag + 验证
5. 复盘（学到了什么）
常见反模式（避免）
□ 大段无证据的猜测（"可能"没验证）
□ 只给结论不给复现（无法核实）
□ 术语堆砌（读者看不懂）
□ 截图模糊/命令不全（证据不完整）
□ 没有修复建议（报告=半成品）
□ 严重性判断夸大（失去可信度）
94.2 报告模板速查（security-report-templates）
# [漏洞标题]: [类型] @ [位置]
## 严重性: 高危 / 中危 / 低危
## 摘要
一句话说明漏洞和影响
## 复现步骤
1. 请求: POST /api/xxx（完整请求头+体）
2. 响应: （完整响应）
3. 截图: （关键证据）
## 影响
- 能做什么（读数据/执行/越权）
- 影响范围
## 修复建议
一句话可执行建议（参数化/白名单/最小权限）
## 参考
- 相关 CWE/CVE
94.3 图表生成（diagram-generator）
工具选型决策表
| 需求 | 工具 | 说明 |
|---|---|---|
| 流程图/时序图 | Mermaid | 最简单，文本驱动 |
| 复杂图布局 | Graphviz DOT | 自动布局，适合大图 |
| UML 重 | PlantUML | 类图/用例/时序 |
| 精确控制 | SVG | 手写，最可控 |
安全场景常用图
□ 攻击路径图（Mermaid flowchart）: 入口→每步→目标
□ 网络拓扑（Graphviz）: 内网结构
□ 时序图（Mermaid sequence）: 认证/协议流程
□ 数据流图（Mermaid flowchart）: 恶意软件行为
□ 架构图（Mermaid/Graphviz）: 系统组件
□ 时间线（Mermaid gantt）: 事件序列
Mermaid 示例（攻击路径图）
flowchart TD
A[Web 漏洞 RCE] --> B[内网 shell]
B --> C{提权}
C -->|SeImpersonate| D[SYSTEM]
C -->|弱口令| E[数据库]
D --> F[Mimikatz 拿哈希]
E --> F
F --> G[PtH 横向]
G --> H[域控]
94.4 写作检查清单
□ 渐进披露（摘要→细节）
□ 面向任务（每节有目的）
□ 证据完整（命令/输出/截图）
□ 严重性分级合理
□ 修复建议可执行
□ 术语解释（对读者）
□ 无未验证猜测
□ 图表清晰（路径/流程）
□ 格式统一（模板）
动手练习
- 把你最近一次分析（逆向/渗透）写成完整报告（按 94.1 结构），补充缺失的证据。
- 用 Mermaid 画一个攻击路径图（从入口到目标的完整链）。
- 练习"反模式改写法"：把一段"只给结论"的报告改写成"证据完整"的报告。
- 用 Graphviz 画一个内网拓扑图（主机/服务/信任关系）。
深入阅读
- 仓库：
skills/docs-generator/SKILL.md（文档写作方法论） - 仓库：
skills/docs-generator/references/security-report-templates.md（安全报告模板） - 仓库：
skills/diagram-generator/SKILL.md（图表生成决策表+语法） - 仓库：
skills/diagram-generator/references/diagram-patterns.md（图表模式） - 仓库：
skills/field-journal/_template.md（复盘模板）