Cairo/StarkNet 智能合约漏洞扫描器 | 6大安全模式检测与静态分析

cairo-vulnerability-scanner by trailofbits/skills

1,100 周安装量

3,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/trailofbits/skills --skill cairo-vulnerability-scanner

开发区块链安全

🇨🇳中文介绍

Cairo/StarkNet 漏洞扫描器

1. 目的

系统性地扫描 StarkNet 上的 Cairo 智能合约，查找与算术运算、跨层消息传递和加密操作相关的平台特定安全漏洞。此技能编码了 6 个 Cairo/StarkNet 生态系统独有的关键漏洞模式。

2. 使用场景

审计 StarkNet 智能合约（Cairo）
审查 L1-L2 桥接实现
StarkNet 应用程序上线前的安全评估
验证跨层消息处理
审查签名验证逻辑
评估 L1 处理函数

3. 平台检测

文件扩展名及标识

Cairo 文件：.cairo

语言/框架标记

// Cairo 合约标识
#[contract]
mod MyContract {
    use starknet::ContractAddress;

    #[storage]
    struct Storage {
        balance: LegacyMap<ContractAddress, felt252>,
    }

    #[external(v0)]
    fn transfer(ref self: ContractState, to: ContractAddress, amount: felt252) {
        // Contract logic
    }

    #[l1_handler]
    fn handle_deposit(ref self: ContractState, from_address: felt252, amount: u256) {
        // L1 message handler
    }
}

// 常见模式
felt252, u128, u256
ContractAddress, EthAddress
#[external(v0)], #[l1_handler], #[constructor]
get_caller_address(), get_contract_address()
send_message_to_l1_syscall

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

4. 技能工作原理

调用时，我将：

搜索您的代码库以查找 Cairo 文件
分析每个合约是否存在 6 种漏洞模式
报告发现的问题，包含文件引用和严重性
为每个识别出的问题提供修复建议
检查 L1-L2 交互是否存在消息传递漏洞

当发现漏洞时，您将收到类似以下的报告：

=== CAIRO/STARKNET VULNERABILITY SCAN RESULTS ===

5. 漏洞模式（6 种模式）

我检查 6 种 Cairo/Starknet 独有的关键漏洞模式。有关详细的检测模式、代码示例、缓解措施和测试策略，请参阅 VULNERABILITY_PATTERNS.md。

未检查的算术运算 ⚠️ 严重 - felt252 中的整数溢出/下溢
存储冲突 ⚠️ 严重 - 存储变量哈希冲突
缺少访问控制 ⚠️ 严重 - 敏感函数上无调用者验证
不正确的 Felt252 边界 ⚠️ 高危 - 未验证 felt252 范围
未经验证的合约地址 ⚠️ 高危 - 使用不受信任的合约地址
缺少调用者验证 ⚠️ 严重 - 无 get_caller_address() 检查

有关包含代码示例的完整漏洞模式，请参阅 VULNERABILITY_PATTERNS.md。

5. 扫描工作流程

步骤 1：平台识别

验证 Cairo 语言和 StarkNet 框架
检查 Cairo 版本（Cairo 1.0+ 与旧版 Cairo 0）
定位合约文件（src/*.cairo）
识别 L1-L2 桥接合约（如果适用）

步骤 2：算术安全性扫描

# 查找算术运算中的 felt252 使用
rg "felt252" src/ | rg "[-+*/]"

# 查找使用 felt252 的余额/金额存储
rg "felt252" src/ | rg "balance|amount|total|supply"

# 应优先使用 u128, u256 代替

步骤 3：L1 处理函数分析

针对每个 #[l1_handler] 函数：

验证 from_address 参数
检查地址不为零
具有适当的访问控制
发出事件以供监控

步骤 4：签名验证审查

针对基于签名的函数：

包含 nonce 跟踪
nonce 在使用后递增
域分隔符包含链 ID 和合约地址
无法重放签名

步骤 5：L1-L2 桥接审计

如果合约包含桥接功能：

L1 验证地址 < STARKNET_FIELD_PRIME
L1 实现消息取消
L2 在处理函数中验证 from_address
L1 ↔ L2 对称访问控制
测试完整的往返流程

步骤 6：使用 Caracal 进行静态分析

# 运行 Caracal 检测器
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

## [严重] L1 处理函数中未检查的 from_address

**位置**：`src/bridge.cairo:145-155` (handle_deposit 函数)

**描述**：
`handle_deposit` L1 处理函数未验证 `from_address` 参数。任何 L1 合约都可以向此函数发送消息并为任意用户铸造代币，从而绕过预期的 L1 桥接访问控制。

**易受攻击的代码**：
```rust
// bridge.cairo, 第 145 行
#[l1_handler]
fn handle_deposit(
    ref self: ContractState,
    from_address: felt252,  // 未验证！
    user: ContractAddress,
    amount: u256
) {
    let current_balance = self.balances.read(user);
    self.balances.write(user, current_balance + amount);
}

攻击者部署恶意的 L1 合约
恶意合约调用 starknetCore.sendMessageToL2(l2Contract, selector, [attacker_address, 1000000])
L2 处理函数处理消息而不检查发送者
攻击者无需存入任何资金即可获得 1,000,000 个代币
协议遭受无限铸造漏洞

建议：根据授权的 L1 桥接验证 from_address：

#[l1_handler]
fn handle_deposit(
    ref self: ContractState,
    from_address: felt252,
    user: ContractAddress,
    amount: u256
) {
    // 验证 L1 发送者
    let authorized_l1_bridge = self.l1_bridge_address.read();
    assert(from_address == authorized_l1_bridge, 'Unauthorized L1 sender');

    let current_balance = self.balances.read(user);
    self.balances.write(user, current_balance + amount);
}

building-secure-contracts/not-so-smart-contracts/cairo/unchecked_l1_handler_from
Caracal 检测器：unchecked-l1-handler-from

严重（需要立即修复）

L1 处理函数中未检查的 from_address（无限铸造）
L1-L2 地址转换问题（资金发送到零地址）

高危（部署前修复）

Felt252 算术溢出/下溢（余额操纵）
缺少签名重放保护（重放攻击）
L1-L2 消息失败但未取消（资金锁定）

中危（审计中处理）

过度约束的 L1-L2 交互（资金被困）

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_felt252_overflow() {
        // Test arithmetic edge cases
    }

    #[test]
    #[should_panic]
    fn test_unauthorized_l1_handler() {
        // Wrong from_address should fail
    }

    #[test]
    fn test_signature_replay_protection() {
        // Same signature twice should fail
    }
}

集成测试（与 L1）

// 测试完整的 L1-L2 流程
#[test]
fn test_deposit_withdraw_roundtrip() {
    // 1. Deposit on L1
    // 2. Wait for L2 processing
    // 3. Verify L2 balance
    // 4. Withdraw to L1
    // 5. Verify L1 balance restored
}

# .github/workflows/security.yml
- name: Run Caracal
  run: |
    pip install caracal
    caracal detect src/ --fail-on high,critical

Building Secure Contracts：building-secure-contracts/not-so-smart-contracts/cairo/
Caracal：https://github.com/crytic/caracal
Cairo 文档：https://book.cairo-lang.org/
StarkNet 文档：https://docs.starknet.io/
OpenZeppelin Cairo 合约：https://github.com/OpenZeppelin/cairo-contracts

10. 快速参考清单

完成 Cairo/StarkNet 审计前：

算术安全性（高危）：

余额/金额未使用 felt252（使用 u128/u256）
或者 felt252 算术运算具有显式的边界检查
已测试溢出/下溢场景

L1 处理函数安全性（严重）：

所有 #[l1_handler] 函数都验证 from_address
from_address 与存储的 L1 合约地址进行比较
无法通过部署替代的 L1 合约来绕过

L1-L2 消息传递（高危）：

L1 桥接验证地址 < STARKNET_FIELD_PRIME
L1 桥接实现消息取消
L2 处理函数检查 from_address
L1 ↔ L2 对称验证规则
已测试完整的往返流程

签名安全性（高危）：

签名包含 nonce 跟踪
nonce 在每次使用后递增
域分隔符包含链 ID 和合约地址
已测试并防止签名重放
已防止跨链重放

Caracal 扫描完成，无严重发现
单元测试覆盖所有漏洞场景
集成测试验证 L1-L2 流程
主网上线前已在测试网部署测试

🇺🇸English

Cairo/StarkNet Vulnerability Scanner

1. Purpose

Systematically scan Cairo smart contracts on StarkNet for platform-specific security vulnerabilities related to arithmetic, cross-layer messaging, and cryptographic operations. This skill encodes 6 critical vulnerability patterns unique to Cairo/StarkNet ecosystem.

2. When to Use This Skill

Auditing StarkNet smart contracts (Cairo)
Reviewing L1-L2 bridge implementations
Pre-launch security assessment of StarkNet applications
Validating cross-layer message handling
Reviewing signature verification logic
Assessing L1 handler functions

3. Platform Detection

File Extensions & Indicators

Cairo files : .cairo

Language/Framework Markers

// Cairo contract indicators
#[contract]
mod MyContract {
    use starknet::ContractAddress;

    #[storage]
    struct Storage {
        balance: LegacyMap<ContractAddress, felt252>,
    }

    #[external(v0)]
    fn transfer(ref self: ContractState, to: ContractAddress, amount: felt252) {
        // Contract logic
    }

    #[l1_handler]
    fn handle_deposit(ref self: ContractState, from_address: felt252, amount: u256) {
        // L1 message handler
    }
}

// Common patterns
felt252, u128, u256
ContractAddress, EthAddress
#[external(v0)], #[l1_handler], #[constructor]
get_caller_address(), get_contract_address()
send_message_to_l1_syscall

Project Structure

src/contract.cairo - Main contract implementation
src/lib.cairo - Library modules
tests/ - Contract tests
Scarb.toml - Cairo project configuration

Tool Support

Caracal : Trail of Bits static analyzer for Cairo
Installation: pip install caracal
Usage: caracal detect src/
cairo-test : Built-in testing framework
Starknet Foundry : Testing and development toolkit

4. How This Skill Works

When invoked, I will:

Search your codebase for Cairo files
Analyze each contract for the 6 vulnerability patterns
Report findings with file references and severity
Provide fixes for each identified issue
Check L1-L2 interactions for messaging vulnerabilities

5. Example Output

When vulnerabilities are found, you'll get a report like this:

=== CAIRO/STARKNET VULNERABILITY SCAN RESULTS ===


---

## 5. Vulnerability Patterns (6 Patterns)

I check for 6 critical vulnerability patterns unique to Cairo/Starknet. For detailed detection patterns, code examples, mitigations, and testing strategies, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).

### Pattern Summary:

1. **Unchecked Arithmetic** ⚠️ CRITICAL - Integer overflow/underflow in felt252
2. **Storage Collision** ⚠️ CRITICAL - Conflicting storage variable hashes
3. **Missing Access Control** ⚠️ CRITICAL - No caller validation on sensitive functions
4. **Improper Felt252 Boundaries** ⚠️ HIGH - Not validating felt252 range
5. **Unvalidated Contract Address** ⚠️ HIGH - Using untrusted contract addresses
6. **Missing Caller Validation** ⚠️ CRITICAL - No get_caller_address() checks

For complete vulnerability patterns with code examples, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).
## 5. Scanning Workflow

### Step 1: Platform Identification
1. Verify Cairo language and StarkNet framework
2. Check Cairo version (Cairo 1.0+ vs legacy Cairo 0)
3. Locate contract files (`src/*.cairo`)
4. Identify L1-L2 bridge contracts (if applicable)

### Step 2: Arithmetic Safety Sweep
```bash
# Find felt252 usage in arithmetic
rg "felt252" src/ | rg "[-+*/]"

# Find balance/amount storage using felt252
rg "felt252" src/ | rg "balance|amount|total|supply"

# Should prefer u128, u256 instead

Step 3: L1 Handler Analysis

For each #[l1_handler] function:

Validates from_address parameter
Checks address != zero
Has proper access control
Emits events for monitoring

Step 4: Signature Verification Review

For signature-based functions:

Includes nonce tracking
Nonce incremented after use
Domain separator includes chain ID and contract address
Cannot replay signatures

Step 5: L1-L2 Bridge Audit

If contract includes bridge functionality:

L1 validates address < STARKNET_FIELD_PRIME
L1 implements message cancellation
L2 validates from_address in handlers
Symmetric access controls L1 ↔ L2
Test full roundtrip flows

Step 6: Static Analysis with Caracal

# Run Caracal detectors
caracal detect src/

# Specific detectors
caracal detect src/ --detectors unchecked-felt252-arithmetic
caracal detect src/ --detectors unchecked-l1-handler-from
caracal detect src/ --detectors missing-nonce-validation

6. Reporting Format

Finding Template

## [CRITICAL] Unchecked from_address in L1 Handler

**Location**: `src/bridge.cairo:145-155` (handle_deposit function)

**Description**:
The `handle_deposit` L1 handler function does not validate the `from_address` parameter. Any L1 contract can send messages to this function and mint tokens for arbitrary users, bypassing the intended L1 bridge access controls.

**Vulnerable Code**:
```rust
// bridge.cairo, line 145
#[l1_handler]
fn handle_deposit(
    ref self: ContractState,
    from_address: felt252,  // Not validated!
    user: ContractAddress,
    amount: u256
) {
    let current_balance = self.balances.read(user);
    self.balances.write(user, current_balance + amount);
}

Attack Scenario :

Attacker deploys malicious L1 contract
Malicious contract calls starknetCore.sendMessageToL2(l2Contract, selector, [attacker_address, 1000000])
L2 handler processes message without checking sender
Attacker receives 1,000,000 tokens without depositing any funds
Protocol suffers infinite mint vulnerability

Recommendation : Validate from_address against authorized L1 bridge:

#[l1_handler]
fn handle_deposit(
    ref self: ContractState,
    from_address: felt252,
    user: ContractAddress,
    amount: u256
) {
    // Validate L1 sender
    let authorized_l1_bridge = self.l1_bridge_address.read();
    assert(from_address == authorized_l1_bridge, 'Unauthorized L1 sender');

    let current_balance = self.balances.read(user);
    self.balances.write(user, current_balance + amount);
}

References :

building-secure-contracts/not-so-smart-contracts/cairo/unchecked_l1_handler_from
Caracal detector: unchecked-l1-handler-from

7. Priority Guidelines

Critical (Immediate Fix Required)
- Unchecked from_address in L1 handlers (infinite mint)
- L1-L2 address conversion issues (funds to zero address)
High (Fix Before Deployment)
- Felt252 arithmetic overflow/underflow (balance manipulation)
- Missing signature replay protection (replay attacks)
- L1-L2 message failure without cancellation (locked funds)
Medium (Address in Audit)
- Overconstrained L1-L2 interactions (trapped funds)
8. Testing Recommendations

Unit Tests
```
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_felt252_overflow() {
        // Test arithmetic edge cases
    }

    #[test]
    #[should_panic]
    fn test_unauthorized_l1_handler() {
        // Wrong from_address should fail
    }

    #[test]
    fn test_signature_replay_protection() {
        // Same signature twice should fail
    }
}
```

Integration Tests (with L1)

// Test full L1-L2 flow
#[test]
fn test_deposit_withdraw_roundtrip() {
    // 1. Deposit on L1
    // 2. Wait for L2 processing
    // 3. Verify L2 balance
    // 4. Withdraw to L1
    // 5. Verify L1 balance restored
}

Caracal CI Integration

# .github/workflows/security.yml
- name: Run Caracal
  run: |
    pip install caracal
    caracal detect src/ --fail-on high,critical

9. Additional Resources

Building Secure Contracts : building-secure-contracts/not-so-smart-contracts/cairo/
Caracal : https://github.com/crytic/caracal
Cairo Documentation : https://book.cairo-lang.org/
StarkNet Documentation : https://docs.starknet.io/
OpenZeppelin Cairo Contracts : https://github.com/OpenZeppelin/cairo-contracts

10. Quick Reference Checklist

Before completing Cairo/StarkNet audit:

Arithmetic Safety (HIGH) :

No felt252 used for balances/amounts (use u128/u256)
OR felt252 arithmetic has explicit bounds checking
Overflow/underflow scenarios tested

L1 Handler Security (CRITICAL) :

ALL #[l1_handler] functions validate from_address
from_address compared against stored L1 contract address
Cannot bypass by deploying alternate L1 contract

L1-L2 Messaging (HIGH) :

L1 bridge validates addresses < STARKNET_FIELD_PRIME
L1 bridge implements message cancellation
L2 handlers check from_address
Symmetric validation rules L1 ↔ L2
Full roundtrip flows tested

Signature Security (HIGH) :

Signatures include nonce tracking
Nonce incremented after each use
Domain separator includes chain ID and contract address
Signature replay tested and prevented
Cross-chain replay prevented

Tool Usage :

Caracal scan completed with no critical findings
Unit tests cover all vulnerability scenarios
Integration tests verify L1-L2 flows
Testnet deployment tested before mainnet

Weekly Installs

1.1K

Repository

trailofbits/skills

GitHub Stars

3.9K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

claude-code986

opencode940

gemini-cli926

codex920

cursor898

github-copilot868

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Cairo/StarkNet 智能合约漏洞扫描器 | 6大安全模式检测与静态分析

🇨🇳中文介绍

Cairo/StarkNet 漏洞扫描器

1. 目的

2. 使用场景

3. 平台检测

文件扩展名及标识

语言/框架标记

相关 Skills

项目结构

工具支持

4. 技能工作原理

5. 示例输出

5. 漏洞模式（6 种模式）

模式摘要：