cairo-vulnerability-scanner
Scans Cairo/StarkNet smart contracts for 6 critical vulnerabilities including felt252 arithmetic overflow, L1-L2 messaging issues, address conversion problems, and signature replay. Use when auditing StarkNet projects.
trailofbits · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add trailofbits/skills --skill cairo-vulnerability-scanner技能说明
name: cairo-vulnerability-scanner description: Scans Cairo/StarkNet smart contracts for 6 critical vulnerabilities including felt252 arithmetic overflow, L1-L2 messaging issues, address conversion problems, and signature replay. Use when auditing StarkNet projects.
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 implementationsrc/lib.cairo- Library modulestests/- Contract testsScarb.toml- Cairo project configuration
Tool Support
- Caracal: Trail of Bits static analyzer for Cairo
- Installation:
cargo install --git https://github.com/crytic/caracal --profile release --force(a Rust tool — not on PyPI) - 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 ===
6. 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.
Pattern Summary:
- Unchecked Arithmetic ⚠️ CRITICAL - Integer overflow/underflow in felt252
- Storage Collision ⚠️ CRITICAL - Conflicting storage variable hashes
- Missing Access Control ⚠️ CRITICAL - No caller validation on sensitive functions
- Improper Felt252 Boundaries ⚠️ HIGH - Not validating felt252 range
- Unvalidated Contract Address ⚠️ HIGH - Using untrusted contract addresses
- Missing Caller Validation ⚠️ CRITICAL - No get_caller_address() checks
For complete vulnerability patterns with code examples, see VULNERABILITY_PATTERNS.md.
7. Scanning Workflow
Step 1: Platform Identification
- Verify Cairo language and StarkNet framework
- Check Cairo version (Cairo 1.0+ vs legacy Cairo 0)
- Locate contract files (
src/*.cairo) - Identify L1-L2 bridge contracts (if applicable)
Step 2: Arithmetic Safety Sweep
# 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_addressparameter - 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
8. 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**:
1. Attacker deploys malicious L1 contract
2. Malicious contract calls `starknetCore.sendMessageToL2(l2Contract, selector, [attacker_ad
阅读完整来源 ↗