# 【安全测试】报告格式对齐 - 计划执行文档

> **文档类型**: 计划执行文档
> **创建日期**: 2026-07-21
> **关联需求**: `_PRD_安全测试报告格式对齐_需求文档.md`
> **预计工作量**: 小（1 个文件核心修改，2 个文件微调）

---

## 一、执行概要

将 `security_report_service.py` 的报告输出格式对齐到参考实现 `report_generator.py`，涉及章节编号调整、OWASP 矩阵列数对齐、历史漏洞表格补列、服务器信息补架构、新增参考资料章节。

---

## 二、修改范围

| 文件 | 修改类型 | 说明 |
|------|---------|------|
| `backend/app/services/security_report_service.py` | **核心修改** | 报告格式对齐全部改动在此文件 |
| `backend/app/models/security_config.py` | 微调 | 可选：新增 `server_arch` 字段 |

---

## 三、分阶段执行计划

### Phase 1: OWASP 覆盖矩阵对齐

**目标**: 将 6 列（含严重）改为 5 列，critical 合并到 high

**修改点** — `security_report_service.py`:

1. **`_get_summary()`**: 将 `critical` 计入 `high`
   ```python
   # 修改前
   summary = {"critical": 0, "high": 0, ...}
   for r in results:
       if r.is_vulnerable:
           if r.level in summary:
               summary[r.level] += 1
   # 修改后
   summary = {"high": 0, "medium": 0, "low": 0, "info": 0, "safe": 0, "vuln_total": 0, "total": 0}
   for r in results:
       if r.is_vulnerable:
           mapped_level = "high" if r.level == "critical" else r.level
           if mapped_level in summary:
               summary[mapped_level] += 1
           summary["vuln_total"] += 1
       else:
           summary["safe"] += 1
   summary["total"] = len(results)
   ```

2. **`_get_module_stats()`**: 同样将 critical 合并到 high

3. **覆盖矩阵表头**: 去掉"🔴严重"列
   ```markdown
   | 编号 | 安全风险 | 用例数 | 🔴高危 | 🟠中危 | 🟡低危 | 🔵信息 | 🟢安全 |
   ```

4. **统计总览表**: 去掉"🔴🔴🔴 严重"行

5. **`LEVEL_MAP`**: 移除 critical 或标记为合并到 high
   ```python
   LEVEL_MAP = {
       "critical": ("严重(高危)", "🔴"),  # 合并显示
       "high": ("高危", "🔴"),
       "medium": ("中危", "🟠"),
       "low": ("低危", "🟡"),
       "info": ("信息", "🔵"),
   }
   ```

---

### Phase 2: 章节编号对齐

**目标**: 历史漏洞/红线/测试环境/参考资料编号与参考实现一致

**修改点** — `_generate_markdown()` 方法：

| 原编号 | 新编号 | 章节 |
|--------|--------|------|
| `## 六、历史漏洞回归验证` | `## 五.五、历史漏洞回归验证` | 历史漏洞 |
| `## 七、华为安全红线合规性检查` | `## 五.六、华为安全红线合规性检查` | 华为红线 |
| `## 八、测试环境与工具` | `## 六、测试环境与工具` | 测试环境 |
| 无 | `## 七、参考资料` | **新增** |

---

### Phase 3: 历史漏洞表格补"详情"列

**目标**: 与参考实现一致，6 列表格

**修改点** — `_generate_markdown()` 中历史漏洞回归部分：

```markdown
| 编号 | 漏洞来源 | 测试项 | 当前状态 | 风险等级 | 详情 |
|------|---------|--------|---------|---------|------|
```

对每条结果：
```python
desc_short = r.description[:80] + "..." if len(r.description) > 80 else r.description
level_name, _ = LEVEL_MAP.get(r.level, (r.level, ""))
lines.append(f"| {r.test_id} | {source} | {r.name} | {status} | {level_name} | {desc_short} |")
```

---

### Phase 4: 服务器信息补架构 + 新增参考资料

**目标**: 服务器显示 `192.168.5.44 (X86架构-欧拉)`，新增参考资料章节

**修改点 1** — 新增常量：

```python
# 默认服务器架构信息
DEFAULT_SERVER_ARCH = "X86架构-欧拉"

# 参考资料（内网盘路径）
REFERENCE_MATERIALS = [
    "华为安全红线资料：[Z:\\deploy\\18其它系统\\安全测试\\01安全测试资料]",
    "以往漏洞报告资料：[Z:\\deploy\\18其它系统\\安全测试\\02项目漏洞资料]",
    "Nginx配置文件：[Z:\\deploy\\18其它系统\\安全测试\\03Nginx配置文件]",
]
```

**修改点 2** — `_generate_markdown()` 测试环境部分：

```python
lines.append(f"| 目标服务器 | {server_ip} ({DEFAULT_SERVER_ARCH}) |")
```

**修改点 3** — `_generate_markdown()` 末尾新增：

```python
# ========== 七、参考资料 ==========
lines.append("## 七、参考资料\n")
for ref in REFERENCE_MATERIALS:
    lines.append(f"- {ref}")
lines.append("")
```

**可选扩展** — `SecurityConfig` 新增 `server_arch` 字段：
- 若后续需要配置化架构信息，在 `SecurityConfig` 加 `server_arch: str` 字段
- 报告生成时优先用配置值，无则用默认值
- **本阶段暂不实现**，仅用常量，避免数据库迁移

---

### Phase 5: 验证

**验证步骤**：

```bash
cd backend
PYTHONIOENCODING=utf-8 python -c "
import asyncio, sys, os
sys.path.insert(0, '.')
async def main():
    from app.database import async_session_maker
    from app.services.security_report_service import SecurityReportService
    async with async_session_maker() as db:
        service = SecurityReportService()
        markdown = await service.get_report_content('exec_686280e0d43b40cda9508e7d023044a9', db)
        print(markdown)
asyncio.run(main())
" 2>&1
```

**验收检查点**：

1. ✅ OWASP 矩阵表头为 `编号|安全风险|用例数|🔴高危|🟠中危|🟡低危|🔵信息|🟢安全`
2. ✅ 统计总览无"严重"行
3. ✅ 历史漏洞编号为 `五.五`
4. ✅ 华为红线编号为 `五.六`
5. ✅ 测试环境编号为 `六`
6. ✅ 参考资料编号为 `七`
7. ✅ 历史漏洞表格有 6 列（含"详情"）
8. ✅ 服务器信息含 `(X86架构-欧拉)`
9. ✅ API 启动无报错

---

## 四、风险评估

| 风险 | 概率 | 影响 | 缓解 |
|------|------|------|------|
| critical 用例的等级显示变化 | 低 | 低 | 漏洞详情标题仍显示"严重"，仅矩阵统计合并 |
| 参考资料路径硬编码 | 低 | 低 | 用常量，后续可配置化 |
| 数据库无新字段 | 无 | 无 | 本阶段不新增 SecurityConfig 字段 |

---

## 五、涉及文件汇总

| 文件 | 操作 |
|------|------|
| `backend/app/services/security_report_service.py` | 修改（核心） |
| `Docs/PRD/需求文档/_PRD_安全测试报告格式对齐_需求文档.md` | 新增 |
| `Docs/PRD/需求文档/_PRD_安全测试报告格式对齐_计划执行.md` | 新增 |

---

*本文档为安全测试报告格式对齐的计划执行文档。*