H3ConuMS-v2/docs/整改计划.md

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 仍待密钥服务与发布窗口确认。