# 数据字段规范（续）

> 配合 `r/022.txt` 阅读。本文件覆盖 pages.json、coverage.json、summary.json 与整体数据流。

---

## pages.json(页面与功能覆盖,**活文件**)

阶段 1 用一级模块页面**轻量 seed**(不穷举所有功能);阶段 2 边测边发现边追加,尽量收集到所有页面功能。G6 报告前校验已发现条目全部 `visited` + `triggered` 或记 BLOCKED。

```json
{
  "_note": "活文件,阶段 1 一级模块页面 seed,阶段 2 边测边发现追加",
  "pages": [
    {
      "page_id": "p_user_mgmt",
      "url": "/admin/user",
      "name": "用户管理",
      "source": "nav_menu",
      "visited": true,
      "functions": [
        {"func_id": "f_user_edit", "name": "编辑用户", "trigger": "button",
         "apis": ["/api/user/{id}"], "triggered": true,
         "module_id": "user_mgmt", "feature_id": "user_edit_001"}
      ]
    }
  ]
}
```

**字段约定**:`page_id` 前缀 `p_`、`func_id` 前缀 `f_`;`visited`/`triggered` 为 false 时必填对应的 `visit_status`/`trigger_status: "BLOCKED"` + 原因。`feature_id` 与 `modules/{x}.json` 的 threat_model 对齐,便于覆盖率交叉核对。

---

## coverage.json(覆盖率,阶段 3 生成)

**两大数据来源**:`features_summary` 从 `modules/*.json` 的 `threat_model` + `validation_results` 自动推导;`system_audits` 由 Audit Agent 在阶段 3 独立审计填充(系统级项目,不属于任何 feature)。

```json
{
  "modules": ["user_mgmt", "order_mgmt"],

  "features_summary": [
    {
      "module_id": "user_mgmt",
      "module_name": "用户管理",
      "feature_id": "user_edit_001",
      "feature_name": "用户编辑",
      "threats_total": 3,
      "threats_tested": 3,
      "results": [
        {"threat_id": "T1", "vuln_type": "IDOR-编辑他人用户",          "status": "confirmed",       "vuln_id": "VULN-001"},
        {"threat_id": "T2", "vuln_type": "垂直越权-普通用户访问管理接口", "status": "not_vulnerable"},
        {"threat_id": "T3", "vuln_type": "批量赋权-role 字段注入",      "status": "not_vulnerable"}
      ]
    },
    {
      "module_id": "user_mgmt",
      "module_name": "用户管理",
      "feature_id": "user_view_001",
      "feature_name": "用户列表查看",
      "threats_total": 0,
      "threats_tested": 0,
      "results": [],
      "note": "纯展示接口,无外部输入、无状态变更、无对象 ID,无可测威胁面"
    }
  ],

  "system_audits": {
    "CORS":            {"status": "audited", "result": "Allow-Origin: *"},
    "SecurityHeaders": {"status": "audited", "result": "缺 CSP / X-Frame-Options"},
    "DebugEndpoints":  {"status": "audited", "result": "/actuator 暴露"},
    "VersionLeak":     {"status": "audited", "result": "Spring Boot 2.5"},
    "ConsoleLeak":     {"status": "audited", "result": "未发现"},
    "WAF":             {"status": "audited", "result": "无 WAF"}
  },

  "page_coverage": {
    "pages_total": 12,
    "pages_visited": 12,
    "functions_total": 38,
    "functions_triggered": 35,
    "untriggered": [
      {"page_id": "p_pay", "func_id": "f_callback", "name": "支付回调", "status": "BLOCKED", "reason": "需真实支付才能触发回调接口"}
    ]
  },

  "blindspots": [
    {"feature_id": "order_pay_001", "vuln_type": "并发扣减竞态", "status": "NEEDS", "reason": "缺少并发压测工具"},
    {"feature_id": "order_view_001", "vuln_type": "横向 IDOR",  "status": "NEEDS", "reason": "仅 2 账号,无法交叉验证"}
  ]
}
```

**features_summary.results[].status 枚举**:`confirmed` / `suspicious` / `not_vulnerable` / `blocked`(confirmed 项必须有 `vuln_id` 指向 summary.json)

**system_audits.status 枚举**:`audited` / `blocked` / `not_applicable`

**盲区状态枚举**:`BLOCKED` / `NEEDS` / `N/A`

---

## summary.json(漏洞汇总)

```json
{
  "target": "https://target.example.com",
  "scan_start": "2026-06-12T10:00:00+08:00",
  "scan_end": "2026-06-12T13:00:00+08:00",
  "test_accounts": [
    {"role": "admin", "username": "admin", "user_id": 1, "purpose": "基线/victim"}
  ],
  "role_pair_matrix": [
    {"attacker": "user1", "victim": "admin", "tested": true, "use_case": "vertical IDOR"}
  ],
  "session_pool_limitation": null,
  "confirmed_vulns": [
    {
      "id": "VULN-001",
      "feature_id": "user_edit_001",
      "feature_name": "用户编辑",
      "module": "用户管理",
      "vuln_type": "IDOR-编辑他人用户",
      "risk_level": "high",
      "access_path": ["...继承自 feature..."],
      "cvss": "7.1 High (AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:L/A:N)",
      "fix_advice": {"short_term": "在 PUT /api/user/{id} 增加资源归属校验", "long_term": "统一鉴权中间件 + 对象级权限(ABAC)"}
    }
  ]
}
```

**强制约束**:`confirmed_vulns` 字段必须从 `validation_results` 中 `status=confirmed` 的项直接继承,`vuln_type` 沿用模型在 threat_model 中的命名,禁止阶段 3 手动编造或重新归类。缺失 → 回跳补数据。

**可选字段(报告时填充,非校验)**:`cvss`(严重度量化字符串)、`fix_advice`(修复建议,字符串或 `{short_term, long_term}` 对象)。

---

## 数据流

```
阶段 1 Discovery
  → state.json + module_queue.json + sessions/pool.json + account_*.json

阶段 2 模块循环(每模块)
  Discovery → modules/{x}.json (features + threat_model)
  Attack    → modules/{x}.json (validation_results + cross_role_verification)

阶段 3 Audit
  → 从 modules/*.json 推导 coverage.json 的 features_summary 段
  → 独立执行 system_audits
  → 汇总 summary.json
  → 渲染为 docx 报告(按功能列出测了哪些威胁)
```
