应用接OKX安全扫描：签名前拦截与异常降级

欧易OKX

2026年10月23日

应用接 OKX 安全扫描做签名前拦截，核心逻辑不是"扫了就能过"，而是把扫描返回的 action 字段当作硬性开关。OKX Onchain OS 的安全技能（okx-security）对交易和签名扫描返回三类动作：block、warn、safe（空值）。block 意味着你的应用必须拒绝继续，不能弹一个"仍然继续"的按钮让用户点；warn 才需要用户显式确认。异常降级的关键判断是：扫描失败不等于通过。网络超时、限流、返回格式异常时，默认行为应该是询问用户是否重试，而不是静默放行。

欧易OKX交易所
全球领先的加密货币平台，适合新手与进阶交易者
新手福利：注册即享20% 交易手续费减免！

立即注册 APP下载

签名前拦截：用 tx-scan 还是 sig-scan

tx-scan 用于交易执行前的安全检查，覆盖 EVM 和 Solana；sig-scan 专门检查消息签名请求，目前仅支持 EVM，覆盖 EIP-712 和 personal_sign 类型。如果你的应用在用户签名交易之前做拦截，调用 tx-scan；如果拦截的是登录验证、授权许可（如 Permit2）这类消息签名，用 sig-scan。

两个命令的返回结构一致：顶层 action 字段反映 riskItemDetail 中最高优先级的风险项。优先级顺序是 block > warn 空值/safe。你的代码应该只读这个顶层 action，不要自己去解析底层的 riskLevel 或布尔标签来重新判断——CLI 已经做了分类，客户端重新计算会和官方矩阵产生偏差。

block 对应高风险，行为是不执行，展示详情，建议取消。warn 对应中风险，行为是展示风险细节，要求用户给出明确的 yes/no 确认。空值或 safe 只在扫描成功完成的前提下才表示未检出风险，不能直接等同于"安全"。

异常降级：扫描没跑完，不能当通过

这是接入时最容易写错的地方。官方安全技能的 fail-safe 原则写得很明确：如果扫描因网络错误、超时、限流或返回格式异常而未能完成，你的应用必须做三件事：向用户报告错误、询问是否重试或在不扫描的情况下继续、如果用户选择继续则显示警告并记录这次跳过的扫描。

一个具体的实现判断：把扫描调用包在 try/catch 里，catch 分支不能默认返回 safe 或跳过拦截。正确做法是抛出一个需要用户决策的状态。如果用户坚持继续，日志里要留下记录，方便事后追溯。这和 action: warn 的处理有区别：warn 是扫描完成了、发现了中风险；扫描失败是根本没拿到结果。两者都需要用户确认，但提示文案应该不同——前者说"发现风险，是否继续"，后者说"无法完成安全检查，是否在未验证的情况下继续"。

还有一个细节：如果扫描返回的 warnings 字段非空，说明扫描完成了但部分数据可能不完整。这种情况下仍然应该展示已有的风险信息，而不是因为 warnings 存在就忽略整个结果。

一个容易混淆的点：`token-scan` 不是签名拦截

token-scan 用于代币风险检测（蜜罐、税率、流动性等），返回的 action 取值是 block / pause / warn / safe，和 tx-scan/sig-scan 的 block / warn / safe 不完全一样。token-scan 的 pause 对应高风险买入场景，需要用户显式确认；warn 对应中风险，展示提示后可以继续。如果你在签名前做的是代币层面的预检（比如用户要买一个不熟悉的代币），用 token-scan 并传 --trade-direction buy；如果你检查的是交易本身（接收方地址、调用数据、授权额度），用 tx-scan。不要用 token-scan 的 action 去判断一笔交易是否可以签名，两者的语义和矩阵不同。

降级策略的实际写法

更建议的做法是：扫描失败时默认拦截，而不是默认放行。虽然官方文档在 swap 场景下有一条例外——token-scan 失败时自动继续并警告，避免阻塞时效性强的交易——但这个例外有明确场景限制（swap 上下文），不是通用规则。对于签名前拦截，没有理由在扫描没跑完时自动放行。

如果你的应用面向的是普通用户，warn 的确认界面需要把风险说清楚，而不是只弹一个"是否继续"。OKX 的标签目录里，warn 可能对应的是可 mint、有冻结权限、未放弃所有权这类中等风险，也可能是复合分析标记但无具体标签的情况。直接把 CLI 返回的风险标签列表展示给用户（不带等级前缀），比笼统说"有风险"更有用。