审计 StarkNet/Cairo 合约时系统排查 6…

在审计 StarkNet 上的 Cairo 智能合约（尤其是 L1-L2 跨层桥接与签名验证逻辑）时，按固定清单逐项排查 6 类平台特有安全漏洞并输出完整覆盖表。

适用场景

解决思路

1. 平台识别：确认是 Cairo 语言与 StarkNet 框架，检查 Cairo 版本（Cairo 1.0+ 还是旧版 Cairo 0），定位合约文件（src/*.cairo），识别是否存在 L1-L2 桥接合约。
2. 算术安全扫描：用 rg "felt252" src/ | rg "[-+*/]" 查找 felt252 参与算术运算的位置；用 rg "felt252" src/ | rg "balance|amount|total|supply" 查找用 felt252 存储余额/金额的字段；应优先改用 u128、u256。
3. L1 Handler 分析：对每个 #[l1_handler] 函数检查是否校验 from_address 参数、是否检查地址非零、是否有正确的访问控制、是否发出事件便于监控。
4. 签名验证审查：对基于签名的函数检查是否包含 nonce 跟踪、nonce 是否在使用后递增、domain separator 是否包含 chain ID 与合约地址、签名是否无法被重放。
5. L1-L2 桥接审计：若合约含桥接功能，检查 L1 是否校验地址 < STARKNET_FIELD_PRIME、L1 是否实现消息取消路径、L2 handler 是否校验 from_address、L1 与 L2 的访问控制是否对称、是否测试了完整往返流程。
6. 用 Caracal 静态分析：安装 cargo install --git https://github.com/crytic/caracal --profile release --force（Rust 工具，不在 PyPI 上）；运行 caracal detect src/；可指定检测器如 caracal detect src/ --detectors unchecked-felt252-arithmetic、caracal detect src/ --detectors unchecked-l1-handler-from、caracal detect src/ --detectors missing-nonce-validation。
7. 逐项核对 6 类漏洞模式：1) felt252 算术溢出/下溢（HIGH，felt252 静默回绕，应改用 u128/u256）；2) L1 到 L2 地址转换（HIGH，L1 地址未针对 STARKNET_FIELD_PRIME 校验）；3) L1 到 L2 消息失败（HIGH，消息无法被消费时没有取消路径）；4) L1<->L2 交互过度约束（MEDIUM，耦合可能导致资金被困或流程阻塞）；5) 签名重放保护（HIGH，缺少 nonce，或 domain separator 缺少 chain/contract）；6) L1 Handler 中未校验 from_address（CRITICAL，任意 L1 合约都能驱动该 handler）。
8. 报告格式：在发现项之上先输出覆盖表，必须包含全部 6 行，每行给出 Verdict 与 Evidence；Verdict 只能是 found（引用 file:line 并在下方完整写出发现）、clear（说明搜索过的函数/trait/检查点以便复现）、n/a（用一句话给出不适用的理由，"没看"不算 n/a）；少于 6 行或 Verdict 为空都视为不完整扫描并需如实报告。
9. 按发现模板撰写每个问题：包含标题（含严重级别）、Location（file:line 与函数名）、Description、Vulnerable Code 代码块、Attack Scenario 攻击步骤、Recommendation 修复代码、References 参考链接。
10. 按优先级分级：Critical（需立即修复）——L1 handler 未校验 from_address（无限增发）、L1-L2 地址转换问题（资金发往零地址）；High（部署前修复）——felt252 算术溢出/下溢（余额操纵）、缺少签名重放保护（重放攻击）、L1-L2 消息失败且无取消路径（资金锁定）；Medium（审计中处理）——L1-L2 交互过度约束（资金被困）。
11. 编写单元测试：测试 felt252 算术边界情况；用 #[should_panic] 测试错误 from_address 的 L1 handler 应失败；测试同一签名使用两次应失败。
12. 编写集成测试：测试完整 L1-L2 流程（L1 存款 → 等待 L2 处理 → 验证 L2 余额 → 提现回 L1 → 验证 L1 余额恢复）。
13. 接入 Caracal CI：在 .github/workflows/security.yml 中运行 cargo install --git https://github.com/crytic/caracal --profile release --force 后执行 caracal detect src/ --fail-on high,critical；注意每次会从源码重建，应缓存 ~/.cargo 或固定 release 二进制。
14. 完成审计前核对清单：算术安全（余额/金额不用 felt252，或 felt252 算术有显式边界检查，且测试溢出/下溢场景）；L1 Handler 安全（所有 #[l1_handler] 校验 from_address，与存储的 L1 合约地址比对，无法通过部署替代 L1 合约绕过）；L1-L2 消息（L1 校验地址 < STARKNET_FIELD_PRIME，L1 实现消息取消，L2 handler 检查 from_address，L1↔L2 校验规则对称，测试完整往返）；签名安全（含 nonce 跟踪、用后递增、domain separator 含 chain ID 与合约地址、测试并阻止重放、阻止跨链重放）；工具使用（Caracal 扫描无 critical 发现，单元测试覆盖所有漏洞场景，集成测试验证 L1-L2 流程，主网前先在测试网部署验证，覆盖表含全部 6 行且每行有 found/clear/n/a 及理由）。
15. 拒绝以下合理化借口："合约很小，大多数模式显然不适用"（n/a 只需一句话且可复核，沉默无法与未检查区分）；"Caracal 没报问题所以合约干净"（Caracal 只覆盖这 6 类中的一部分，且完全触及不到逻辑层问题，需说明它覆盖了哪些模式）；"我只检查了对本合约重要的模式"（判断哪些模式重要本身就是扫描的一部分，应在表格完成后按严重性排序，而不是省略行）；"没有发现就没什么可报告"（零发现也要输出完整覆盖表，该表才是交付物）；"Cairo 1 有原生溢出检查所以算术安全"（要指明具体类型，felt252 与定长整数类型行为不同，二者边界正是模式 4 所在）；"L1 那边会校验"（必须引用 L1 合约，跨桥的假设在读过之前都只是假设，未校验的 from_address 是 StarkNet 桥的典型漏洞）。

适用边界 · 注意事项

• 非 StarkNet/Cairo 项目（如以太坊 Solidity、其他链的合约）不适用，本技能针对 Cairo/StarkNet 平台特有漏洞模式。
• 没有 L1-L2 桥接或 L1 handler 的纯 L2 合约，模式 2、3、4、6 通常为 n/a，但仍需在覆盖表中逐行给出理由。
• 仅依赖 Caracal 工具扫描结果作为唯一结论时不适用——Caracal 只覆盖这 6 类中的一部分，逻辑层漏洞需人工逐项排查。