4.8 KiB
4.8 KiB
规则:安全与可靠性 —— 可信边界、故障路径、可观测
类型:硬约束(rules) · 状态:生效 2026-06-19 · 门禁:现有测试/契约/边界门禁 + 代码评审兜底 上位:
verification-and-anti-false-green.md、engineering-conventions.md来源:蒸馏docs/dev-baseline/global/05-安全开发规范.md、06-日志与可观测性规范.md,并吸收项目当前“真实后端/真实 PG/外部依赖 fail-closed”经验。
一、可信边界
- 认证、授权、租户隔离、数据归属校验必须在后端可信边界执行;前端隐藏按钮或本地状态不算安全控制。
/admin-api/**与/app-api/**必须保持调用身份隔离;管理员能力不得经 app API 暴露,普通用户能力不得依赖 admin 端兜底。- 查询和写入必须带可信的
tenant_id/user_id/ owner 条件;不得信任前端传来的 owner、tenant 或权限声明。 - AI runtime 不得自授权。授权事实必须来自授权/权限端口或已验证的快照,运行时只能消费;当前由
AiGrantRuntimeBoundaryArchTest守住 runtime/任务执行侧不得直接依赖ToolGrant写模型,完整 grant/runtime 物理包拆分另行推进。
二、输入、文件与数据保护
- 所有外部输入必须校验:HTTP 请求、文件上传、SSE/WebSocket 消息、异步事件、外部回调都算外部输入。
- 优先使用框架校验与结构化解析;禁止用字符串拼接 SQL,禁止用正则/字符串切割代替可靠 parser。
- 文件路径、文件类型、文件大小、内容签名/格式都要校验;只看扩展名不够。写文件必须考虑部分写入、清理和路径穿越。
- 密码、token、API key、PG 密码、临时签名、授权快照不得写入代码、提交记录、日志、响应或错误信息。
- 用户隐私字段必须脱敏后展示或记录;完整手机号、邮箱、证件号、银行卡号不得进入普通日志。
三、外部依赖与异步可靠性
- 涉及外部服务、模型调用、对象存储、支付、通知、消息队列、异步任务时,必须设计超时、失败、重试、幂等、补偿和审计路径。
- 外部依赖未配置时必须 fail-closed:拒绝执行并给出可追踪错误,不得静默降级成假成功。
- 写路径必须有幂等键或命令记录;重试不得重复扣费、重复发放权益、重复创建投影或重复发送不可撤销通知。
- 异步投影必须有源事件、处理状态、重放或补偿策略;只写一侧而无法读回的设计不得声称端到端完成。
- 事务边界必须明确:跨 BC 写入优先通过端口/事件/投影,不得用跨域 DAL 拼接一个大事务。
四、日志、审计与追踪
- 关键业务状态变更、管理员操作、安全敏感操作、外部调用必须留下可追踪记录:who、what、when、where、result、commandId/traceId。
- ERROR 日志必须包含异常堆栈和足够定位的上下文;WARN 用于可恢复异常、降级、重试;INFO 记录关键业务事件;DEBUG 只用于开发诊断。
- 日志禁止输出大段正文、完整 prompt、完整 token、完整密钥、完整隐私字段。AI prompt 只记录模型、token 数、任务 ID、摘要性上下文。
- 前端请求应携带请求 ID 或等价关联信息;SSE/长连接需有 connectionId 关联事件流。
- 审计日志不得被业务普通删除路径修改或清除;敏感操作需要记录变更前后关键值或可重建来源。
五、故障处理与回滚
- 发现安全漏洞、数据错写、权限绕过、外部依赖异常时,先止血并保留证据,再修复;不得用“刷新缓存/重跑脚本”掩盖根因。
- 不可简单回滚的动作(删数据、发通知、扣费、授权发放、第三方永久写入)必须有人类确认、备份或补偿方案。
- 数据迁移必须可验证:迁移前后行数/关键约束/抽样数据有证据;大批量迁移要分批、可中断、可恢复。
- 配置变更应可独立回滚;敏感配置只通过仓库外环境或密钥系统注入。
六、机械门禁与人工评审边界
| 约束 | 机械落点 |
|---|---|
| 跨 BC 不直连他域实现 / DAL | BcBoundaryArchTest |
| AI runtime 不得自授权 / 不得直连 Tool Grant 写模型 | AiGrantRuntimeBoundaryArchTest |
| API/DB 契约与迁移卫生 | ContractFirstGateTest + openapi-diff |
| completed 必须有测试证据 | P1rApiCoverageReportTest |
| 真实 PG / 外部依赖 fail-closed 证据 | P1r*IT 与总账证据 |
.agents 规则索引 |
AgentsInfraIntegrityTest |
目前尚无全量静态密钥扫描、SAST、依赖漏洞扫描门禁。涉及密钥、权限、支付、对象存储、模型调用、通知、生产数据迁移的变更,在补机械门禁前必须作为人工评审高风险项处理。