84 lines
11 KiB
Markdown
84 lines
11 KiB
Markdown
# H3C ONU 设备管理系统研发规范整改计划
|
||
|
||
## 1. 审查基线
|
||
|
||
- 审查日期：2026-07-28
|
||
- 审查版本：`5b07ec6df0448bd43966260b1b7b70532c1d552b`（`main`）
|
||
- 审查范围：Vue/Vite 前端、FastAPI 后端、PostgreSQL/Redis/Celery、Docker Compose 与仓库交付物。
|
||
- 目标等级：**C1（待项目负责人确认）**。未分类项目按 C1 基线审查，依据《总体规范》2.1。
|
||
- 说明：本计划只将原文标明 C1/C2/C3/C4 或“【强制】”的内容标为规范要求；其余安全加固按工程风险处置。
|
||
|
||
## 2. 整改优先级与工作包
|
||
|
||
### P0：上线前阻断项（安全）
|
||
|
||
| 编号 | 整改项 | 主要证据 | 验收标准 | 依据 |
|
||
| --- | --- | --- | --- | --- |
|
||
| SEC-01 | 删除日志中的令牌片段，并建立统一日志脱敏器。脱敏范围至少覆盖 `Authorization`、token、password、secret、corpsecret、客户端凭据及请求体嵌套字段。 | `backend/app/middleware/permission_middleware.py:70` 写入 token 前 20 位；审计中间件仅脱敏三个精确字段名。 | 自动化测试证明日志中不出现任一敏感值或其可复用片段。 | 《安全分册》3.1.1【强制】 |
|
||
| SEC-02 | 停用 iMC 调用中的 MD5 Digest 实现，优先接入 iMC 支持的 Digest SHA-256、OAuth 或受控网关认证；如设备仅支持 MD5，须形成例外审批、隔离边界和替代改造计划。 | `backend/app/services/imc_service.py:82-87` 使用 `hashlib.md5`。 | 代码与扫描结果不再出现 MD5；或已具备批准的临时例外和退役日期。 | 《安全分册》3.1.2【强制】 |
|
||
| SEC-03 | 修复“关于”页存储型 XSS：Markdown 渲染后使用白名单 HTML 清洗，限制 URL 协议；为所有 `v-html` 建立受信来源约束。 | `frontend/src/views/About.vue:14,30` 将管理员可写 Markdown 直接插入 DOM。 | 恶意 `script`、事件属性和 `javascript:` URL 均不能执行；新增前端测试。 | 《安全分册》3.2.1.4【强制】 |
|
||
| SEC-04 | 认证回调验证 Casdoor 返回 JWT 的签名、发行者、受众、有效期和 nonce/state；失败默认拒绝。 | `backend/app/api/v1/auth.py:18-24,50` 明确“不验签”后使用 `sub` 建立本地会话。 | 伪造、过期、错误 issuer/audience 的令牌均被拒绝；通过真实 OIDC 回调回归。 | 《安全分册》2.1.10、2.2.2；《总体规范》4.5.1（C1） |
|
||
| SEC-05 | 生产环境强制 TLS 校验，禁止 `IMC_API_VERIFY_SSL=false` 默认值；为内部 CA 配置证书链。 | `backend/app/core/config.py:51` 与两份 `.env.example` 默认关闭校验。 | 非开发环境启动时拒绝关闭 TLS 校验；HTTPS 证书错误请求失败。 | 《安全分册》2.2.4、2.3.1 |
|
||
| SEC-06 | 统一异常处理：对外返回错误码与通用信息，内部以脱敏日志记录关联 ID；禁止透出异常文本、堆栈和上游响应正文。 | 多处 `detail=str(e)`，如 `devices.py:442`、`check.py:87,102`、`auth.py:82`；任务结果含 traceback。 | 500 响应不含路径、凭据、堆栈或上游报文；异常日志可按关联 ID 检索。 | 《安全分册》3.2.2.1【强制】 |
|
||
| SEC-07 | 对需要复用的 OLT SSH 密码实施加密（密钥由受控密钥服务或部署密钥注入），完成历史数据迁移、轮换和审计。 | `backend/app/models/device.py:14` 原以明文 `Text` 存储设备密码。 | 数据库备份、查询和审计日志均无明文密码；迁移可回滚、轮换可执行。 | 工程安全整改；密钥方案待确认（规范未指定具体 KMS 实现）。 |
|
||
|
||
### P1：C1 研发交付链整改
|
||
|
||
| 编号 | 整改项 | 验收标准 | 依据 |
|
||
| --- | --- | --- | --- |
|
||
| ENG-01 | 在内部研发平台配置 CI：后端依赖安装、pytest、前端 `npm ci && npm run build`、SAST、依赖/SCA 扫描、镜像构建。为失败设置合入门禁并归档报告。 | 每次代码更新均有可追溯构建、单测和安全扫描结果；阻断级问题不可合入或发布。 | 《总体规范》4.5.1、4.5.3（C1）；《流水线分册》2.3.2、3.2 |
|
||
| ENG-02 | 补齐测试策略、用例、测试报告与缺陷闭环；优先增加认证验签、权限隔离、审计脱敏、文件上传、XSS、iMC TLS、OLT 密码加密迁移的自动化测试。 | 测试计划、评审记录、执行报告、缺陷清单齐全；安全整改均有回归用例。 | 《总体规范》4.5.1、4.6、5.5.7（C1）；《测试管理分册》3.2-3.5、6 |
|
||
| ENG-03 | 将第三方依赖改为可复现、可审核来源：固定后端所有直接依赖版本，使用内部统一制品库代理，生成依赖清单与许可证/漏洞扫描报告。 | `requirements` 无无上限版本；构建只从批准镜像/依赖源获取依赖，扫描报告可追溯。 | 《制品管理分册》4.1（C1）；《总体规范》4.5.5（C1） |
|
||
| ENG-04 | 建立版本、制品与部署追溯：镜像标签包含应用版本与 commit ID；测试/生产只从统一制品库拉取已扫描制品，保留版本、测试、部署与回退记录。 | 任一生产版本能反查 commit、制品、扫描/测试结果和部署记录；禁止可变标签发布。 | 《制品管理分册》2.5、2.6、3.1（C1）；《部署管理分册》2.2-2.3（C1） |
|
||
| ENG-05 | 补齐 C1 最小交付物：需求编号及变更记录、概要设计、安全设计/威胁分析、测试计划/报告、部署实施与回退方案；建立需求—用例—代码/制品—版本追踪表。 | 文档受版本控制，且每次发布可对应需求、测试与制品版本。 | 《总体规范》4.1、4.2、4.3、4.4（C1）；《代码管理分册》2.3（C1） |
|
||
| ENG-06 | 在远端仓库核验并固化治理配置：仓库管理员不超过 3 人、最小权限、离职回收、主干保护、发布 tag；补全仓库描述中的项目编号、项目名称和子项目名称。 | 导出远端权限、保护分支和 tag 证据；README 与根 `.gitignore` 保持合规。 | 《代码管理分册》2.2-3.1（C1） |
|
||
|
||
### P2：运行与可维护性改进
|
||
|
||
| 编号 | 整改项 | 验收标准 | 属性 |
|
||
| --- | --- | --- | --- |
|
||
| OPS-01 | 统一部署脚本与实际 Compose 服务、端口和健康检查；补充发布前检查、回退演练、备份恢复验证。 | 部署、备份和恢复在预发环境演练成功，并记录证据。 | 规范要求（部署材料，C1） |
|
||
| OPS-02 | Docker 构建使用固定基础镜像摘要、非 root 用户、最小镜像和健康检查；为容器设置资源与网络边界。 | 镜像安全扫描通过，运行身份和暴露端口可审计。 | 工程建议 |
|
||
| OPS-03 | 清理 Pydantic/SQLAlchemy 弃用用法，增加 lint/format/type-check；建立代码所有者与评审清单。 | CI 中无新增高等级质量问题，弃用告警清零。 | 工程建议 |
|
||
|
||
## 3. 实施顺序与里程碑
|
||
|
||
1. **M0：范围确认（0.5 天）**：确认项目等级、数据分级、iMC 支持的认证方式、内部制品库/CI/密钥服务和生产发布窗口。
|
||
2. **M1：安全止血（3-5 天）**：完成 SEC-01 至 SEC-06，补充回归测试；SEC-07 先输出密钥与迁移设计，禁止新增明文凭据。
|
||
3. **M2：凭据迁移与测试（3-5 天）**：实施 SEC-07，完成历史数据加密、密钥轮换演练和核心接口测试。
|
||
4. **M3：研发交付链（3-5 天）**：实施 ENG-01 至 ENG-04，接入内部流水线、制品库、SAST/SCA 与可追溯发布。
|
||
5. **M4：文档与上线验收（2-3 天）**：实施 ENG-05、ENG-06、OPS-01，完成预发演练、测试报告、部署审批材料和复审。
|
||
|
||
## 4. 当前证据缺口与需确认事项
|
||
|
||
- 未获得远端仓库的成员、权限、保护分支、合并评审和流水线运行记录，不能据此断言其合规性。
|
||
- 未获得研发云、制品库、SAST/SCA、测试管理、缺陷管理和生产部署平台的证据。
|
||
- 本地测试尝试因当前运行环境未安装 `paramiko` 而在收集阶段中断；前端构建因工作环境没有 npm 未执行。应由 CI 使用锁定工具链和依赖后重跑。
|
||
- 需项目负责人确认：项目 C 级、数据分级、iMC 接口可支持的认证算法、密钥托管产品和发布窗口。
|
||
|
||
## 4.1 SEC-07 发布前操作（待发布授权）
|
||
|
||
1. 在受控密钥服务中生成并保管 `CREDENTIAL_ENCRYPTION_KEY`；不得写入仓库、镜像、部署脚本或审计日志。
|
||
2. 备份数据库并完成恢复演练；记录备份版本和操作人。
|
||
3. 将密钥仅注入 backend、celery-worker、celery-beat 运行环境，部署新版代码后执行 `python scripts/migrate_olt_credentials.py`。
|
||
4. 以数据库管理员账户核验 `olt_devices.password` 全部为 `enc:v1:` 前缀；通过应用的 OLT 扫描、重启和端口管理回归测试确认可解密使用。
|
||
5. 如迁移异常，先停止后续发布，使用已验证的数据库备份回退；密钥泄露时按应急流程轮换密钥并重新加密所有凭据。
|
||
|
||
## 4.2 SEC-02 iMC 认证能力核验（2026-07-28）
|
||
|
||
- 已在部署服务器上对 iMC REST 接口发起未认证的只读请求。服务端返回 `401` 及 `Digest realm="iMC RESTful Web Services", qop="auth"`，未声明 `algorithm` 参数；现网项目的 iMC 客户端亦按 MD5 Digest 计算认证摘要。
|
||
- 受控浏览器因 iMC 使用不受信任的 TLS 证书而拒绝建立连接，未绕过证书校验；因此不能把“浏览器能访问”作为验收证据。
|
||
- 目前未发现 Digest SHA-256、OAuth/OIDC 或令牌认证的可用证据。SEC-02 不能以修改客户端代码的方式单独关闭：须向 iMC 厂商/平台管理员取得当前版本 REST API 的认证能力说明并确认升级路径。
|
||
- 若确认该版本仅支持 MD5 Digest，则上线前应提交安全例外审批，至少限定 iMC 为受控内网目标、使用专用最小权限账户、启用有效 TLS 证书与证书校验、禁止记录 `Authorization`/nonce/响应敏感数据，并明确 iMC 升级或网关替代方案的责任人和退役日期。
|
||
|
||
## 4.3 ENG-01、ENG-03 当前落实情况（2026-07-28）
|
||
|
||
- 已新增 GitLab CI 基线：统一依赖源检查、后端单元测试与 JUnit 报告、前端 `npm ci` 构建、Python 组件漏洞扫描和容器构建校验。详见 `docs/CI实施说明.md`。
|
||
- 已锁定后端直接依赖中原本使用下限约束的 `aiohttp`、`PyJWT`、`requests`；前端已存在 `package-lock.json`，流水线与 Docker 构建均使用 `npm ci`。
|
||
- Dockerfile 不再固定第三方镜像站；CI 通过 `INTERNAL_PYPI_URL`、`INTERNAL_NPM_REGISTRY`、`INTERNAL_CONTAINER_PROXY` 三个受保护变量接入企业代理。变量、受保护 Runner、合并门禁和统一制品库推送尚需由平台管理员配置后才能验收。
|
||
- 本地环境没有可用的 Docker、pytest 及项目运行依赖；已通过 Python 语法编译与 `git diff --check`，完整测试、镜像构建、依赖扫描和 GitLab CI Lint 均待在配置完成的内部流水线执行。
|
||
|
||
## 5. 下一项可执行动作
|
||
|
||
由 GitLab/制品库管理员先配置 `INTERNAL_PYPI_URL`、`INTERNAL_NPM_REGISTRY`、`INTERNAL_CONTAINER_PROXY` 与隔离的 Docker Runner；随后将本整改分支推送到 GitLab，确认 VerifyCI 全绿并将 `main` 设置为“合并请求评审 + 成功流水线”门禁。SEC-02 保持例外审批依赖，SEC-07 仍待密钥服务与发布窗口确认。
|