# PRD - 安全测试模块需求文档

> **文档版本**: v1.0
> **创建日期**: 2026-07-21
> **模块类型**: 安全测试
> **优先级**: P1

---

## 一、背景与目标

### 1.1 背景

当前平台已实现 UI 自动化测试功能，支持用例录制、执行和报告生成。但在实际项目交付过程中，还需要进行 API 接口安全测试，确保系统符合安全规范。

参考现有 `ApiSecurityTest` 工具的实现经验，该工具基于 OWASP API Security Top 10 标准，已成功应用于多个项目的安全测试：

- **长安深蓝汽车**: 35个历史漏洞回归验证
- **南山区委**: 渗透测试+XDR告警验证
- **天津海油**: 运维集控系统安全复测
- **厦门银行总行大厦**: 华为Web漏扫集成
- **新统一平台**: HCL AppScan + IAST 报告整合

### 1.2 目标

将安全测试能力集成到现有平台，实现：

1. **统一入口**: 安全测试用例与 UI 用例统一管理
2. **可视化执行**: 前端界面触发安全测试，实时查看进度
3. **标准化报告**: 生成符合 OWASP 标准的安全测试报告
4. **知识库复用**: 历史漏洞回归测试、华为安全红线检查

---

## 二、功能范围

### 2.1 核心功能

| 功能 | 描述 | 优先级 |
|------|------|--------|
| 安全测试模块管理 | 创建/编辑安全测试模块 | P0 |
| 安全测试用例管理 | 基于 OWASP API Top 10 的用例模板 | P0 |
| 安全测试执行引擎 | HTTP 请求 + 签名算法 + 结果判定 | P0 |
| 安全测试报告生成 | Markdown 格式，含漏洞详情和修复建议 | P0 |
| 多账号权限测试 | 支持 superadmin/admin/user 三角色越权测试 | P1 |
| 历史漏洞回归 | 35个历史漏洞的修复验证 | P1 |
| 华为安全红线 | 22项安全红线合规检查 | P1 |
| 知识库管理 | 安全测试载荷、漏洞模式库 | P2 |

### 2.2 OWASP API Security Top 10 覆盖

| 编号 | 安全风险 | 测试要点 | 用例数 |
|------|---------|---------|--------|
| API1 | 对象级别授权失效 | 水平越权、IDOR遍历、company_id篡改 | 8 |
| API2 | 身份认证失效 | Token伪造、NoSQL注入、暴力破解、注销失效 | 13 |
| API3 | 对象属性级别授权失效 | 垂直越权、API成批分配 | 9 |
| API4 | 资源消耗不受限 | 速率限制、文件上传、分页滥用 | 7 |
| API5 | 功能级别授权失效 | 普通用户访问管理员接口 | 8 |
| API6 | 无限制访问敏感业务流 | 批量注册、短信轰炸、NoLogin接口滥用 | 6 |
| API7 | 服务器端请求伪造 | SSRF内网探测（Nacos/Redis/MySQL） | 9 |
| API8 | 安全配置错误 | Nacos未授权、Swagger暴露、SQL注入、安全响应头缺失 | 15 |
| API9 | 库存管理不当 | 隐藏接口、旧版API、内部API暴露 | 8 |
| API10 | 不安全的第三方API集成 | 讯飞/腾讯/钉钉/华为云凭证泄露 | 7 |

**总计**: 90+ 安全测试用例

---

## 三、详细需求

### 3.1 安全测试模块管理

#### 3.1.1 模块类型扩展

现有平台 `Module` 模型已有 `module_type` 字段，需扩展支持：

```python
module_type: Mapped[str] = mapped_column(
    String(20),
    default="standard",
    comment="模块类型: standard(标准模块)/custom(项目定制模块)/security(安全测试模块)"
)
```

#### 3.1.2 安全测试模块预置

系统初始化时预置 10 个 OWASP 模块：

| 模块ID | 名称 | 描述 |
|--------|------|------|
| sec_api01 | API1 - 对象级别授权失效 | 水平越权、IDOR测试 |
| sec_api02 | API2 - 身份认证失效 | Token伪造、注入、暴力破解 |
| sec_api03 | API3 - 对象属性级别授权失效 | 垂直越权、成批分配 |
| sec_api04 | API4 - 资源消耗不受限 | 速率限制、DoS测试 |
| sec_api05 | API5 - 功能级别授权失效 | RBAC绕过测试 |
| sec_api06 | API6 - 无限制访问敏感业务流 | 业务逻辑漏洞 |
| sec_api07 | API7 - 服务器端请求伪造 | SSRF内网探测 |
| sec_api08 | API8 - 安全配置错误 | 配置审计、敏感路径 |
| sec_api09 | API9 - 库存管理不当 | API资产管理 |
| sec_api10 | API10 - 不安全的第三方API集成 | 第三方凭证泄露 |

### 3.2 安全测试用例模型

#### 3.2.1 用例类型扩展

现有 `TestCase` 模型已有 `case_type` 字段，需扩展支持：

```python
case_type: Mapped[str] = mapped_column(
    String(20),
    default="ui",
    comment="用例类型: ui/api/security/deploy/performance/functional"
)
```

#### 3.2.2 安全测试用例结构

安全测试用例的 `steps` 字段采用特殊结构：

```json
{
  "test_type": "api_security",
  "target": {
    "base_url": "https://192.168.5.44",
    "path": "/api/message/getMessageById",
    "method": "GET"
  },
  "auth": {
    "required": true,
    "account": "user",
    "expect_different_account": "superadmin"
  },
  "request": {
    "params": {"id": "${meeting_id}"},
    "headers": {},
    "body": null
  },
  "assertions": [
    {
      "type": "status_code",
      "expect": 200,
      "mode": "should_not_equal",
      "description": "越权访问应被拒绝"
    },
    {
      "type": "response_code",
      "expect": "403",
      "mode": "should_contain",
      "description": "应返回权限不足"
    }
  ],
  "vulnerability": {
    "id": "2.1.1",
    "name": "水平越权访问其他用户会议详情",
    "level": "high",
    "description": "user 使用 Token 成功访问了 superadmin 的会议详情",
    "fix_suggestion": "在接口中增加用户身份校验"
  }
}
```

### 3.3 安全测试执行引擎

#### 3.3.1 执行器架构

```
SecurityExecutor
├── HttpClient（复用参考实现）
│   ├── 自动签名（AES-CBC）
│   ├── Token 管理
│   └── 重试机制
├── AuthHelper
│   ├── 多账号登录
│   └── Token 刷新
└── AssertionEngine
    ├── 状态码断言
    ├── 响应体断言
    └── 业务码断言
```

#### 3.3.2 执行流程

```
1. 初始化 HttpClient（加载配置）
2. 登录测试账号（superadmin/admin/user）
3. 执行前置准备（获取测试数据）
4. 发送测试请求（带签名）
5. 判定漏洞状态
6. 记录结果
7. 生成报告
```

#### 3.3.3 签名算法

沿用现有签名机制（从前端 JS 逆向）：

```
1. x_random = 随机字符串(8-16位)
2. x_timestamp = 当前毫秒时间戳
3. sign_str = timestamp + JSON.stringify(body) + random
4. sign_hash = SHA256(sign_str)
5. aes_key_source = SHA256(bearer_token 或 随机60位)
6. aes_key = aes_key_source[16:32]
7. aes_iv = aes_key_source[0:8] + aes_key_source[-8:]
8. x_sign = AES.encrypt(sign_hash, aes_key, aes_iv) → Base64
```

### 3.4 安全测试报告

#### 3.4.1 报告结构

```markdown
# 接口安全测试总报告

> **生成时间**: 2026-07-21
> **测试目标**: https://192.168.5.44
> **测试标准**: OWASP API Security Top 10 (2019)

## 一、执行概要
- 测试统计总览
- OWASP 覆盖矩阵

## 二、漏洞详情
- 按风险等级排序
- 复现步骤
- 修复建议

## 三、已验证安全项

## 四、风险评估与修复建议

## 五、已知安全问题清单

## 六、历史漏洞回归验证

## 七、华为安全红线合规性检查

## 八、测试环境与工具
```

#### 3.4.2 风险等级

| 等级 | 颜色标记 | 说明 |
|------|---------|------|
| Critical | 🔴🔴🔴 | 严重漏洞，需立即修复（如 NoSQL 注入 CVSS 9.4） |
| High | 🔴 | 高危漏洞，需优先修复 |
| Medium | 🟠 | 中危漏洞，建议尽快修复 |
| Low | 🟡 | 低危漏洞，建议择期修复 |
| Info | 🔵 | 信息类，可作参考 |

### 3.5 知识库模块

#### 3.5.1 历史漏洞回归测试

从参考实现提取 35 个历史漏洞：

| 漏洞ID | 标题 | 来源项目 | 严重等级 |
|--------|------|---------|---------|
| HV-001 | SQL注入 - 会议预定接口 | 长安深蓝汽车 | High |
| HV-005 | Nacos 未授权访问 | 南山区委 | High |
| HV-011 | Nacos serverIdentity 权限绕过 | 长安深蓝汽车 | High |
| HV-016 | JWT弱密钥 | 长安深蓝汽车 | High |
| HV-026 | NoSQL注入 - 登录接口 | 新统一平台 | Critical |
| ... | ... | ... | ... |

#### 3.5.2 华为安全红线检查

22 项华为安全红线检查：

| 检查ID | 类别 | 要求 |
|--------|------|------|
| HW-01 | 加密规范 | 密码存储必须使用加盐哈希 |
| HW-02 | 加密规范 | 密钥不能硬编码在代码中 |
| HW-03 | 传输安全 | 必须使用 HTTPS |
| HW-04 | 传输安全 | TLS 版本不低于 1.2 |
| ... | ... | ... |

#### 3.5.3 测试载荷库

- SQL 注入载荷（21条）
- 敏感路径字典（70+条）
- SSRF 内网探测目标
- NoSQL 注入载荷

---

## 四、非功能需求

### 4.1 性能要求

| 指标 | 要求 |
|------|------|
| 单个用例执行时间 | < 30秒 |
| 90个用例批量执行 | < 15分钟 |
| 报告生成时间 | < 10秒 |

### 4.2 安全要求

- 测试账号密码加密存储
- 报告文件访问需鉴权
- 敏感接口限制内网访问

### 4.3 兼容性

- Python 3.8+
- 支持并发执行（线程池）
- Windows / Linux 跨平台

---

## 五、接口设计

### 5.1 后端 API

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/security/config | 获取安全测试配置 |
| PUT | /api/security/config | 更新安全测试配置 |
| POST | /api/security/executions | 创建安全测试执行 |
| GET | /api/security/executions/{id} | 获取执行详情 |
| GET | /api/security/reports/{id} | 获取安全测试报告 |
| GET | /api/security/knowledge-base | 获取知识库内容 |

### 5.2 WebSocket 推送

```
Topic: /topic/security/{execution_id}

消息格式:
{
  "type": "case_result",
  "data": {
    "case_id": "sec_2.1.1",
    "status": "passed|failed",
    "is_vulnerable": false,
    "duration": 1.23
  }
}
```

---

## 六、数据模型

### 6.1 新增模型

#### SecurityConfig（安全测试配置）

```python
class SecurityConfig(Base):
    __tablename__ = "security_configs"
    
    id: Mapped[str] = mapped_column(String(32), primary_key=True)
    name: Mapped[str] = mapped_column(String(100))
    target_url: Mapped[str] = mapped_column(String(500))
    verify_ssl: Mapped[bool] = mapped_column(default=False)
    timeout: Mapped[int] = mapped_column(default=30)
    
    # 测试账号
    accounts: Mapped[dict] = mapped_column(JSON)
    
    # 认证配置
    auth_config: Mapped[dict] = mapped_column(JSON)
    
    # 限流配置
    rate_limits: Mapped[dict] = mapped_column(JSON)
    
    created_at: Mapped[datetime] = mapped_column(DateTime)
    updated_at: Mapped[datetime] = mapped_column(DateTime)
```

#### VulnerabilityResult（漏洞结果）

```python
class VulnerabilityResult(Base):
    __tablename__ = "vulnerability_results"
    
    id: Mapped[str] = mapped_column(String(32), primary_key=True)
    execution_id: Mapped[str] = mapped_column(String(32), ForeignKey("executions.id"))
    case_id: Mapped[str] = mapped_column(String(32))
    
    # 漏洞信息
    vuln_id: Mapped[str] = mapped_column(String(20))
    name: Mapped[str] = mapped_column(String(200))
    level: Mapped[str] = mapped_column(String(20))  # critical/high/medium/low/info
    description: Mapped[str] = mapped_column(Text)
    
    # 请求/响应信息
    request_info: Mapped[str] = mapped_column(Text)
    response_info: Mapped[str] = mapped_column(Text)
    
    # 结果
    is_vulnerable: Mapped[bool] = mapped_column(default=False)
    fix_suggestion: Mapped[str] = mapped_column(Text)
    
    # 元数据
    metadata: Mapped[dict] = mapped_column(JSON)
    
    created_at: Mapped[datetime] = mapped_column(DateTime)
```

---

## 七、前端设计

### 7.1 页面结构

```
/security
├── 配置管理
│   ├── 目标服务器配置
│   ├── 测试账号配置
│   └── 认证参数配置
├── 用例管理
│   ├── OWASP Top 10 模块
│   ├── 历史漏洞回归
│   └── 华为安全红线
├── 执行中心
│   ├── 新建执行
│   ├── 执行进度
│   └── 实时日志
└── 报告中心
    ├── 报告列表
    ├── 报告详情
    └── 报告导出
```

### 7.2 侧边栏扩展

在现有侧边栏增加"安全测试"入口：

```typescript
const menuItems = [
  { icon: 'Odometer', title: '测试总览', path: '/' },
  { icon: 'Folder', title: '模块管理', path: '/modules' },
  { icon: 'Document', title: '用例管理', path: '/cases' },
  { icon: 'VideoCamera', title: '用例录制', path: '/recorder' },
  { icon: 'CaretRight', title: '执行中心', path: '/execution' },
  { icon: 'DataAnalysis', title: '报告中心', path: '/reports' },
  { icon: 'Shield', title: '安全测试', path: '/security' },  // 新增
  { icon: 'Setting', title: '系统配置', path: '/settings' }
]
```

---

## 八、里程碑

| 阶段 | 内容 | 工期 |
|------|------|------|
| Phase 1 | 后端安全测试引擎开发 | 3天 |
| Phase 2 | 前端安全测试页面开发 | 2天 |
| Phase 3 | OWASP Top 10 用例导入 | 2天 |
| Phase 4 | 报告生成与导出 | 1天 |
| Phase 5 | 知识库集成与测试 | 1天 |

**总工期**: 约 9 个工作日

---

## 九、参考资料

- `临时目录/安全测试/ApiSecurityTest/` - 参考实现
- OWASP API Security Top 10 (2019)
- 华为安全红线规范
- HCL AppScan 报告格式
- IAST 检测报告格式

---

## 十、附录

### 10.1 依赖包

```txt
requests>=2.28.0
pycryptodome>=3.18.0
colorama>=0.4.6
pyyaml>=6.0
```

### 10.2 配置文件示例

```yaml
# security_config.yaml
target:
  base_url: "https://192.168.5.44"
  verify_ssl: false
  timeout: 30

accounts:
  superadmin:
    username: "superadmin"
    password: "Ubains@1357"
  admin:
    username: "admin@aq"
    password: "Ubains@1357"
  user:
    username: "user@aq"
    password: "Ubains@1357"
  captcha: "csba"

limits:
  brute_force_max: 20
  rate_limit_max: 100
  request_interval: 0.5
```

---

*文档结束*