简介资源围绕小红书蒲公英平台接口调用中的x-sign签名参数展开面向需要逆向分析或模拟客户端请求的Python、Node.js开发者。zip压缩包共8个文件包含5个JavaScript脚本和3个Python脚本分别覆盖前端加密逻辑解析、服务端签名生成示例及辅助工具脚本整体仅76KB便于快速查阅。已有850人下载学习。通过学习包内代码可掌握HMAC-SHA256签名流程、参数排序规则以及xhs-x-s等相关请求头字段的配合方式适合用于API调试、爬虫开发或接口安全研究。1. x-sign 参数是什么为什么每个请求都要带一段会变的签名第一次在抓包里看到蒲公英这类 App 内测分发平台的接口请求时很多人下意识会把 x-sign 当成一个固定的 token复制到下一个请求里直接用结果换一个接口就报 403。实际上 x-sign 是由当前请求的方法、路径、时间戳、随机串、请求体加密钥一起推出来的摘要值每次请求都在变。它要解决两件事一是请求参数被别人改掉时能及时发现二是旧请求被人原样重放时能被拦住。如果你是要对接这类签名接口的后端、给自家接口加防刷机制的开发者或者正在排 sign mismatch 的运维这篇笔记会把签名参数的构成、一套可复现的校验服务、以及 5 个高频坑讲透。这里只讨论接口签名机制的正常设计与排错不涉及任何绕过接口风控的操作。2. 从抓包样本拆解 x-sign 的字段组成4 个必看参数2.1 一次请求里和签名强相关的四个字段内测分发平台的接口请求头里通常会有一串类似x-sign: 0f2f6d...、x-time: 1690000001、x-nonce: 7f3a9c...、x-app: com.example.debug这样的键值。很多人只盯着 x-sign其实另外三个字段才是它能不能通过校验的关键。x-sign 的值是一串 64 位的十六进制字符串至少从表面上看不出任何规律但这刚好说明它是由其它字段参与计算的结果而不是服务端下发的固定凭证。请求头字段是否每次变化典型值在签名中的作用x-sign是64 位十六进制字符串最终签名摘要服务端重新计算后比对x-time是1690000001秒级时间戳决定请求是否仍在窗口内x-nonce是7f3a9c...随机串防止同一秒内重放x-app基本不变com.example.debug客户端标识服务端用它找到对应密钥x-app 的作用更像一把钥匙的编号。服务端收到请求后先看 x-app 知道该用哪一把密钥再用 x-time、x-nonce、请求路径、请求体重新算一次摘要最后和 x-sign 做对比。如果两边算出来的结果一致说明请求没有被改过如果不一致说明参数在中间被动了手脚。这里的关键点是x-time 和 x-nonce 都必须出现在待签串里否则签名就变成了一个静态值重放攻击几乎等于零成本。怎么从抓包里确认这些字段常见做法是直接用抓包工具右键复制 cURL然后在本地慢慢拆。在抓包工具里定位目标接口请求右键复制为 cURL 命令。在命令行执行这条 cURL确认能复现成功或失败。把请求头里的 x-sign、x-time、x-nonce 单独摘出来记录请求路径、query 和 body。手动把 body 里某个字段改掉后再重放观察返回是否变成 sign mismatch。如果改了 body 后签名校验失败说明 body 参与了签名如果返回值没变化说明 body 没参与。通过这种方式可以快速判断出参与签名的字段范围。2.2 为什么同一个接口刷新两次签名完全不同这个现象背后其实只有两个原因时间戳变了、随机串变了。第一次请求的 x-time 是 1690000001第二次是 1690000002x-nonce 又是每次随机生成只要这两处有一个变化HMAC 摘要的输出就会完全不同。所以 x-sign 表面上是“每次请求一个值”实际上它是在对“当前这次请求的完整特征”做摘要。服务端校验的顺序也值得关注。我一般会按时间、随机串、摘要的顺序来做而不是先算摘要。先检查 x-time 是否在允许窗口内能挡掉大部分过期请求再查 x-nonce 是否用过能挡掉同窗口内的重放最后才做 HMAC 计算避免每一个垃圾请求都逼着服务端做一次耗时计算。这个顺序看起来是小事但线上被扫描时区别非常大。这里需要顺便说一下精度问题x-time 必须统一使用秒级还是毫秒级。有的客户端只在初始化时取一次时间之后所有请求复用同一个 x-time结果在窗口内可能没问题一旦用户操作超过窗口就大量过期。常见处理是所有请求生成时实时取int(time.time())不要缓存。如果服务端和客户端时间偏差较大与其把窗口调得很大不如在客户端启动时做一次时间校准把时间差缓存在本地签名时用校正后的时间。2.3 怎么确认哪些请求字段参与了签名判断方法很简单离线复制一条请求改动某个参数然后观察服务端是否报 sign mismatch。不参与签名的字段随便改都不会影响校验结果参与签名的字段哪怕多一个空格都会失败。用对照实验跑一遍比看文档更快。实践中常见的参与范围如下表参与要素是否常参与容易踩的坑method是必须统一用大写比如 POSTpath是只取 /api/v1/apps不要带域名和端口query视实现而定排序规则必须前后端一致常见按 key 的 ASCII 升序body视实现而定空 body 按空字符串处理不要写成 nullts / nonce是类型必须一致别一边传字符串一边传整数Host / User-Agent一般不参与参与后会导致代理层一改头就签名失败这里最容易翻车的其实是 query 排序。抓包工具显示的是原始顺序但很多服务端框架会先把 query 解析成字典再重新序列化顺序就变了。如果签名时不先对 query 排序同一个请求在客户端和服务端就会算出两个不同的摘要。为了避免这个问题我一般约定所有参与签名的 query 先按 key 的字节序排序再拼成k1v1k2v2空值也要保留等号。3. 用 Python 在服务端实现一套可校验的 x-sign 签名3.1 生成侧按固定顺序拼出待签串不要指望下面这套代码能直接算出现网某个平台的实际值它不来自任何官方文档而是这一类签名接口最通用的骨架。照着这个结构你可以把密钥、算法、参与字段换成自己项目的规则跑通后再扩展成完整服务。import hashlib import hmac import time import secrets # 模拟项目X 的签名密钥发布前务必换成独立随机值 SECRET_KEY bdev-secret-please-change-32bytes def build_payload(method: str, path: str, query: str, body: str, ts: int, nonce: str) - str: return .join([ method.upper(), path, query or , body or , str(ts), nonce, ]) def build_x_sign(method: str, path: str, query: str, body: str, ts: int, nonce: str) - str: payload build_payload(method, path, query, body, ts, nonce) return hmac.new(SECRET_KEY, payload.encode(utf-8), hashlib.sha256).hexdigest() ts int(time.time()) nonce secrets.token_hex(16) sign build_x_sign(POST, /api/v1/apps, channeltest, {name:demo}, ts, nonce) print(sign)这段代码的核心是build_payload里的拼接顺序。method 放在第一段是为了让 GET 和 POST 即使 path 相同也不会算出同一个签名nonce 放在最后是为了让随机串尽可能影响摘要的尾部。这里没有把 x-app 放进去因为 x-app 只是用来选密钥的密钥本身已经隐含了客户端身份再放一遍意义不大。参数说明SECRET_KEY 建议不少于 32 字节可以用secrets.token_bytes(32)生成不要用肉眼可读的短密码query 传入前必须先按 key 排序不然服务端一解析字典顺序就变body 为空时必须传空字符串不能传 None否则body or 会把它变成空串但如果调用方传的是null签名串会原样带出这四个字符这又是一处经典的不一致。3.2 校验侧先查时间、再查摘要、最后查 nonce生成侧跑通之后校验侧才是真正决定线上能不能用的关键。下面的代码实现了完整的三段式校验。_seen_nonce: set[str] set() WINDOW 300 def verify_request(method: str, path: str, query: str, body: str, ts: int, nonce: str, sign: str): # 1. 时间窗口检查先挡住过期请求 if abs(int(time.time()) - int(ts)) WINDOW: return False, expired # 2. 摘要比对用恒定时间比较避免时序攻击 expected build_x_sign(method, path, query, body, ts, nonce) if not hmac.compare_digest(expected, sign): return False, sign mismatch # 3. nonce 去重防止同一个请求被重复使用 if nonce in _seen_nonce: return False, replay _seen_nonce.add(nonce) return True, ok校验顺序是刻意安排的。时间窗口检查只做一次整数减法成本最低所以放最前面摘要计算要跑一次 HMAC成本高放中间nonce 检查要查集合如果在摘要之后做攻击者随便丢垃圾包也能逼服务端做大量 HMAC 计算。把计算量大的步骤往后放是这类签名服务的基本素养。参数说明WINDOW 我一般设 300 秒内测分发场景足够宽容同时又能挡住大部分过期重放。如果客户端和服务端时钟差异确实大可以放宽到 600 秒但超过 1800 秒就别考虑了那已经不是容差是给攻击者留窗口。nonce 集合必须清理_seen_nonce只加不删会出现两个问题内存一直涨清空之后同一个旧请求反而能二次通过。生产环境建议用 Redis 的 SETEXkey 设计成nonce:{ts//300}:{nonce}过期时间等于 WINDOW这样每个窗口的 nonce 天然淘汰。3.3 三组必调参数与两个线上调试技巧参数建议值说明SECRET_KEY32 字节以上随机串用 secrets.token_bytes(32) 生成不要用固定字符串WINDOW300 秒客户端时钟不可控时可放宽到 600但不要超过 1800签名算法HMAC-SHA256比 MD5 安全速度足够待签串编码UTF-8中文参数很容易在这里翻车前后端必须统一nonce 去重TTL 缓存有效期等于 WINDOW过期自动删除第一个调试技巧是打印待签串。把客户端的待签串和服务端重新拼出来的待签串原样打进日志逐字符对比。大多数 mismatch 都能在第一步看出来要么少了一个空 body要么 query 顺序不同要么中文被编码成了不同的百分号。第二个技巧是给每个请求加一条透传的 trace_id让客户端把 trace_id、x-time、nonce 一起传给服务端服务端校验失败时把 trace_id 记到错误日志里。这样线上排查时不需要让用户复现直接按 trace_id 捞日志就能定位是哪个环节算错了。还有一点要注意密钥不要写死在代码仓库里。常见做法是放在环境变量或配置中心按 x-app 区分多套密钥。一旦发现某把密钥可能泄漏只轮换这一个 x-app 对应的密钥不影响其它客户端。这里的取舍是参与签名字段越少调试越容易但安全性越差字段越多越难被篡改但客户端和服务端必须维护一张完全一致的字段清单。我的建议是从一个最小集开始比如 method path ts nonce跑通后再按业务需要加 query 和 body。4. 对接 x-sign 时最容易踩的 5 个坑现象、原因、解决4.1 一换环境就签名失败现象本地调试怎么发都对代码一上测试环境就全是 sign mismatch而且换到生产环境也报同样的错。原因最常见的是待签串里的 query 没有排序。本地客户端手写的拼法是按业务顺序来的服务端框架拿到后按字典序重组两边算出来的摘要自然不一致。另一个常见原因是 body 在网关层被解压过参与签名的内容变成了“解压后的 body”而客户端签名时用的是“压缩前的原始 body”。解决统一约定 query 先按 ASCII 升序排序再拼串body 用服务端最终解析出来的字符串参与签名如果中间有压缩/解压环节明确签名在解压前还是解压后做。我一般会把上面的结论写进接口文档并给出一段参考代码避免两边各猜各的。4.2 高并发下突然出现一批 expired 报错现象单条请求测试全通过一上压测或者活动流量进来日志里突然多出一大片“expired”但用户侧看只是正常的连续操作。原因时间窗口设置得太紧加上客户端和服务器时钟不是同一套时间源。比如客户端取的是秒级时间戳服务端取的是毫秒级两边算出来的差值可能是 0.5 秒到 1 秒如果窗口只有 5 秒网络抖动或者请求排队一久就会整批过期。解决统一时间戳精度为秒服务端各实例使用同一时间源window 不要直接给 5 秒这种极值。我在模拟项目X里的经验是把 WINDOW 定为 300 秒同时客户端不缓存 x-time每次请求实时取这样既能防重放又不会误伤。4.3 nonce 集合越来越大会有副作用现象线上偶尔出现“replay”拒绝但业务方确认没有重放同时节点内存慢慢涨隔几天需要重启。原因nonce 去重集合只加不删或者多实例各存一份一个实例清空了另一个没清空导致同一个请求在一台机器上通过、在另一台上被判重放。解决把 nonce 放进带过期时间的存储里比如 Redis 的 SETEX每个 nonce 的过期时间等于 WINDOW单机内存实现也要定期按时间戳清理不要用一个无限增长的 set。这里有个细节nonce 的 key 最好带上时间窗口比如nonce:{ts//300}:{nonce}这样过期后自然淘汰也方便按窗口批量清理。4.4 流量经过网关后签名必挂现象客户端直连服务端全部正常加了一台反向代理或者 API 网关之后签名校验失败率接近 100%。原因网关层往往会对请求做“规范化”比如把 URL 里重复的斜杠合并、把 query 参数重新排序、把 body 里的空格重新编码。客户端签名时用的是原始形态服务端接收到的是规范化形态两边待签串不一致。解决参与签名的 path 和 query 必须用稳定形态。常见做法是签名前先把 path 统一规范化query 排序后拼接body 尽量不要在网关层做改写如果必须改写要么让网关同步修改签名要么把 body 摘要放到独立 header 里。排查时打开网关的 access log对比它收到的原始 query 与签名侧的 query一眼就能看出哪里变了。4.5 业务加字段后两边都改了还是失败现象产品要求加一个 request_id 字段客户端和服务端都加了但联调时仍然 sign mismatch。原因参与签名的字段清单没有同步。客户端把 request_id 放进了待签串服务端校验时没有把它考虑进去或者两边都加入了但插入待签串的位置不同。解决把“参与签名的字段及顺序”当作一份契约新增字段必须按固定顺序追加到末尾而不是随意插到中间。每次改动后端接口时先更新契约文档和示例签名再让客户端照着实现。这个坑最容易在版本迭代时出现因为签名代码通常散落在各个客户端漏改一处要到联调阶段才暴露。5. 从静态 x-sign 升级到动态 challenge防重放与防刷的实践5.1 静态签名的边界到底在哪前面的实现已经能防“参数被篡改”和“旧请求重放”但它有一个明显的边界密钥一旦泄漏x-sign 就可以被任意伪造。拿到密钥的人只要按同一套规则拼串就能算出任何合法签名时间戳、nonce、路径、body 全都可以自己造。更麻烦的是静态签名的请求本身看起来都合法服务端无法区分这是真客户端发的还是脚本发的。所以那些把签名密钥埋在客户端安装包里的场景风险尤其高因为安装包可以被解开、密钥可以被提取。动态 challenge 的思路就是把“一次性挑战值”引入签名。客户端在发起关键业务请求前先向服务端申请一个随机挑战值只有同时持有本地密钥和这个挑战值才能算出正确的 x-sign。服务端校验通过后会立刻作废这个挑战值同一挑战值不能再用第二次。这相当于把“签名”从静态计算变成了有状态的握手即使攻击者抓到了完整请求也没用因为下一次挑战值已经变了。5.2 一套可落地的动态 challenge 实现流程可以分成四步客户端请求 challenge、服务端生成并缓存、客户端拼进待签串、服务端消费并校验。下面这段代码模拟了核心逻辑可以直接在模拟项目X里跑通。import secrets import time import hashlib import hmac # 假设的缓存对象生产环境替换为 Redis class TTLDict: def __init__(self): self._data {} self._expire {} def set(self, key, value, ex60): self._data[key] value self._expire[key] time.time() ex def get(self, key): if key not in self._data: return None if time.time() self._expire[key]: del self._data[key] del self._expire[key] return None return self._data[key] def delete(self, key): self._data.pop(key, None) self._expire.pop(key, None) cache TTLDict() def issue_challenge(app_id: str) - str: challenge secrets.token_hex(16) cache.set(fchallenge:{app_id}, challenge, ex60) return challenge def verify_dynamic(app_id, challenge, method, path, query, body, ts, sign): saved cache.get(fchallenge:{app_id}) if saved is None or saved ! challenge: return False, challenge mismatch cache.delete(fchallenge:{app_id}) expected build_x_sign(method, path, query, body, ts, challenge) if not hmac.compare_digest(expected, sign): return False, sign mismatch return True, ok这段代码的关键改动是把原来的 nonce 替换成服务端下发的 challenge并且 challenge 只能被消费一次。逻辑说明第一步先校验 challenge 是否匹配匹配后立即删除删除之后同样一个请求再发过来会因为 challenge 不存在而失败第二步才做摘要计算避免把计算量放到无效请求上。参数说明challenge 的有效期 60 秒比较合适太短会导致弱网客户端体验差太长又会给攻击者留下更长的使用窗口TTLDict 里用time.time()判断过期多实例场景必须替换成 Redis 这类共享存储否则客户端从 A 机器拿到 challenge请求却被负载均衡转发到 B 机器B 机器没有这份缓存就会误判。5.3 动态 challenge 的缓存选型与三个必记字段缓存选型取决于规模。单机自测用 TTL 字典没有问题一旦服务端有多实例就必须把 challenge 放到 Redis并且用 app_id 作为 key 的一部分。这里还有一个隐藏问题客户端对关键业务接口会重试重试时如果还在拿同一个 challenge第二次必然失败所以客户端要在收到 challenge mismatch 后重新申请 challenge再发一次而不是把错误直接抛给用户。日志层面至少要记三个字段方便事后反查字段记录原因出现什么信号时需要注意app_id定位到具体客户端单一 app_id 高频出现 challenge 过期大概率是客户端时钟异常或脚本在抓取challenge_id串起一次完整挑战大量“已消费却再次使用”说明有重放或重试逻辑没写对ts时间窗口判断依据偏差超过窗口的请求比例升高说明客户端时间源有问题为什么不要记签名本身和密钥因为日志一旦泄露等于把“如何验证签名”的完整样本给了攻击者。我一般只记挑战值的前 8 位和签名摘要的前 8 位够区分一次请求就够了完整值留在请求上下文里出错时再临时开启完整日志。这个习惯能省不少运维麻烦。6. 三个技巧快速验证签名组件靠不靠谱6.1 把服务端时间拨偏 5 分钟在测试环境把服务进程所在机器的系统时间往后调 5 分钟然后用客户端发一个正常请求。如果签名服务真的读取了本地时间并参与校验这个请求应该被判为 expired调回时间后请求恢复通过。如果拨偏之后仍然全部正常说明时间窗口形同虚设或者服务端根本没读本地时间。注意不要在业务高峰做这个实验最好在独立测试环境里验证。6.2 把 x-sign 末尾改掉一个字符把抓到的合法请求复制一份将 x-sign 的最后一个字符改成别的字母原样发出去。服务端应该立刻返回 sign mismatch而且这次校验不应该触发任何数据库查询因为摘要比对在业务处理之前。如果它不但通过而且业务正常执行说明服务端根本没有校验签名只是把参数解析出来就算完了。6.3 同一请求原样发两次把同一个带正确签名的请求连续发送两次第二次必须被拒。这里要注意第一次发送后nonce 或 challenge 已经被消费第二次会失败这才是正确行为。如果两次都成功说明服务端没做 nonce 去重签名只挡了篡改、没挡重放。我第一次写这类校验时把 WINDOW 设成了 3600 秒结果非业务时段的重放拦截日志刷了好几页后来改成“正常窗口 300 秒 短暂容差 60 秒”才消停。别贪窗口大窗口越大后悔药越难吃。希望帮到你。本文还有配套的精品资源点击获取