rust-web-security

Rust Web 安全交付

先明确攻击者、资产和信任边界，再选择 crate 和中间件。Rust 的内存安全并不会自动提供身份验证、授权、协议强制执行或业务逻辑安全；默认拒绝所有请求，并通过负向测试证明控制措施有效。

确认安全约定

修改前：

• 识别服务暴露面、调用方、浏览器/API/服务间流量以及管理端点；
• 确定 TLS 终止位置、受信任的代理，以及客户端 IP/主机/方案的来源；
• 定义身份提供方、身份验证协议、令牌/会话类型及生命周期；
• 明确角色、作用域、对象所有权、租户边界和敏感业务操作；
• 管理 Cookie、密码、API 密钥和 Webhook 的密钥存储/续期；
• 配置 CORS、CSRF、重定向、上传、出站 URL 和 Webhook 场景；
• 根据请求正文大小/并行度/超时要求，定义速率限制预算和抗滥用策略；
• 制定审计事件定义、隐私标准、合规需求和事件响应流程；
• 锁定 axum、tower、rustls、cookie crate 的版本以及 Rust MSRV。

如果安全要求不完整，请明确说明假设和未覆盖的风险。不要通过弱化测试来绕过验证，以达到通过/失败结果。

工作流

1. 确定攻击面和基线

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -e features
cargo test --all-targets

枚举所有路由、方法、提取器、中间件、代理、回调、管理端点和出站请求。识别身份验证上下文的建立点、授权决策点、会话/令牌存储位置、密钥加载位置和审计日志记录位置。运行现有的代码库安全检查；安装或升级安全工具必须遵守项目约束。

2. 编写威胁模型和授权矩阵

至少记录：

Asset -> Entry Point -> Trust Boundary -> Attacker Capability -> Control -> Verification Evidence

针对每项敏感操作，构建主体 × 操作 × 资源 × 租户 × 上下文矩阵。身份验证只能证明“你是谁”；授权必须在每次请求中验证用户是否可以对该对象执行此操作。默认拒绝；不要只依赖登录检查或前端按钮的可见性。

对象级、属性级和基于租户的授权详情请参阅威胁模型与授权。

3. 在单一边界建立身份

• 使用成熟的 IdP/协议和持续维护的 crate；不要自行发明令牌/密码协议；
• 将身份验证结果转换为最精简的 Principal/声明上下文；
• 身份验证中间件发生故障时必须终止请求，不得回退到匿名身份而静默降级；
• 缺少凭据或凭据无效时返回 401；身份已知但权限不足时返回 403；
• 管理、内部和用户身份需要使用不同的受众、作用域或凭据；
• 对需要重新身份验证、MFA 或交易确认的高风险操作，不要依赖过期会话。

4. 正确验证令牌、会话和密码

JWT 验证必须强制使用固定的允许算法，并验证签名、签发者、受众、过期时间、生效时间以及令牌类型／范围要求；不同令牌类型需要采用互斥的验证规则，并妥善处理 JWKS 缓存和续期。解码标头／声明不等于有效身份验证。

Cookie 会话应包含 Secure、HttpOnly 标志，并根据威胁模型设置 SameSite，使用最小范围的 Path；通常应省略范围过宽的 Domain。登录和权限提升后应轮换会话 ID；定义注销或撤销时的服务端失效机制以及绝对／空闲过期时间。

密码哈希应使用维护良好的密码哈希 API，并采用类似 Argon2id 的参数，按部署规模进行测量；避免使用通用的快速哈希。高开销 KDF 不得阻塞异步运行时工作线程。API 密钥／令牌应仅显示一次，并以可验证的形式存储，同时包含范围前缀、过期时间和续期功能。有关 OAuth/OIDC/JWT/会话／密码／API 密钥的详情，请参阅身份验证令牌和会话。

5. 在每个资源边界进行授权

• 授权输入包括可信主体、操作、实际资源属性和租户；
• 先按租户查询，再检查对象／字段权限，以防止 BOLA/IDOR 攻击；
• 管理角色必须具有明确的范围；不要将 is_admin 当作全局豁免通道；
• 批量操作应逐个对象授权，或采用等效的数据库策略；
• 写入 DTO 使用允许列表，防止批量赋值敏感字段，例如角色、租户和所有者；
• 缓存的授权结果应包含策略版本、主体、资源、操作和过期时间。

数据库行级安全（RLS）可提供纵深防御，但不能取代应用层策略和测试。

6. 强化浏览器和传输边界

• 全面强制使用 HTTPS，并配置 HSTS、证书、mTLS 和 TLS 策略；在实际终止层验证这些配置；
• 仅信任由可信代理明确注入的转发标头，以避免主机／协议／IP 欺骗；
• CORS 定义的是浏览器读取策略，而非服务端访问控制；存在凭据时，应使用精确的来源允许列表； 在会话 Cookie 身份验证端点中实施 CSRF 令牌防护；仅当 SameSite Cookie 的防护符合特定威胁模型时，才依赖该机制。

设置与响应正文类型相匹配的内容安全策略（CSP）、框架、内容类型、来源和缓存标头。对正文大小、标头处理、上传、分页、并行度、超时和高开销操作应用速率限制。通过限制用户可控的 URL／webhook 来防止 SSRF：限制协议／主机／端口；解析所有地址以屏蔽专用网络／元数据目标；重定向后重新验证。

出站响应也应受到大小／类型／时间限制。具体检查项请参阅浏览器传输和输入。

7. 保护机密并建立审计机制

• 通过受控配置／机密管理器向代码注入机密；不得将其写入镜像层、错误信息或日志；使用 secrecy 类型减少通过 Debug 序列化意外暴露机密的风险，但不要声称其具备等同的内存隔离能力；
• 明确规定密钥 ID、所有者、用途、算法以及创建／过期／续期／取消策略；
• 在跟踪日志记录前标记／清理敏感正文内容；审计登录失败、权限拒绝、策略／角色／密钥变更和高风险操作。

审计记录必须包含操作者、操作、目标、结果、请求 ID 和时间戳，且不得包含机密。限制攻击者可控标签的数量，以防止日志注入攻击。轮换或撤销生产密钥、会话、用户和令牌会改变外部状态；只有经过明确授权的操作才能执行这些变更。

8. 通过负向测试验证控制措施

至少覆盖：

1. 未认证或已过期的请求，以及签发者、受众、算法或令牌类型无效的请求；
2. 租户级权限缺失（同一租户与跨租户）、对象所有权，以及字段级权限提升；
3. 会话固定、注销/撤销场景、绝对过期/空闲过期策略；
4. 针对恶意来源和 Cookie 属性的 CSRF/CORS 预检攻击；
5. 通过专用网络、IPv6、DNS 多地址解析、重定向和非 HTTP 协议进行的 SSRF；
6. 超大请求体、慢速请求、高并发成本和耗时较高的身份验证流程；
7. 错误响应泄露跟踪 ID 或审计日志机密；
8. 依赖项漏洞以及功能/加密后端变更。

有关测试/审计/供应链文档，请参阅 机密信息审计与测试。

常见门禁

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo audit

cargo audit 需要相应工具和公告数据可用。如果其中任一项不可用，应报告未运行审计，而不能声称审计通过。根据仓库策略，使用 cargo deny、DAST、代理/TLS 配置测试和授权矩阵验证进行补充。

完成标准

• 明确威胁模型、信任边界和授权矩阵；
• 所有敏感路由默认拒绝所有访问，并验证对象/租户/操作的所有权；
• 令牌/会话/密码/API 密钥使用成熟协议并经过完整验证；
• TLS/代理/CORS/CSRF/标头/资源限制与实际部署配置一致；
• 响应/日志中不出现机密信息；明确轮换/撤销策略；
• 负向测试和依赖项审计通过；未验证的 IdP、代理、TLS 或生产配置均明确标注。

交接边界

主要职责	负责人
路由器、提取器、处理程序、中间件、关闭逻辑	rust-web
用户/会话/租户/API 密钥持久化和事务	rust-database
异步 KDF 隔离、超时、取消并发限制	rust-concurrency
测试分层、模糊测试覆盖率/性能门禁	rust-testing
依赖项功能、加密后端、构建/发布配置	rust-cargo-build
密码学/FFI/不安全实现审查	rust-unsafe-ffi

按需资源

• 威胁模型与授权：设计权限、租户边界和敏感业务流程时阅读。
• 身份验证令牌与会话：实现期间了解 OIDC/JWT/Cookie 会话/密码/API 密钥。
• 浏览器传输与输入：部署服务时配置 TLS/代理/CORS/CSRF/标头/上传/SSRF 检查。
• 机密信息审计与测试：实现期间处理机密信息、日志、负向测试和依赖项审计。
• 加密依赖边界：选择 AEAD/KDF/恒定时间/清理用 crate；实现加密功能时审查 nonce/转录/WASM 或协议版本。
• 示例场景：阅读端到端任务分解模板，了解需要生产就绪示例的场景。

examples/golden-authorization/：此处提供默认拒绝/对象/租户授权黄金测试的离线编译与验证。