majiayu000 Cairo Scanner Skill
Purpose
Analyze Cairo smart contracts deployed on Starknet for security vulnerabilities. Cairo's unique computational model — based on field elements (felts), STARK proofs, and native account abstraction — creates attack surfaces that don't exist on EVM chains.
Cairo Security Model
| Property | Cairo/Starknet | EVM/Solidity |
|---|---|---|
| Integer type | Felt252 (field element, $0$ to $P-1$ where $P = 2^{251} + 17 \cdot 2^{192} + 1$) | uint256, int256 |
| Arithmetic | Modular (wraps around $P$) | Checked (reverts in Solidity 0.8+) |
| Division | Modular inverse (not integer division) | Integer truncation |
| Account model | All accounts are smart contracts (native AA) | EOAs + smart contracts |
| Upgrades | replace_class_syscall (instant) |
Proxy patterns (delegatecall) |
| Storage | Pedersen hash-based addresses | Sequential slots (keccak256) |
| L1 interaction | L1-L2 messaging via Starknet Core on Ethereum | Bridges required |
| Proving | STARK proofs for L1 verification | No proofs needed |
Detection Capabilities
Critical — Direct Fund Loss
| Vulnerability | Description | Detection Signal |
|---|---|---|
| Felt overflow wrapping | Arithmetic on felt252 wraps around $P$, enabling underflow/overflow | Felt252 used for balances or amounts without range checks |
Unprotected replace_class_syscall |
Anyone can upgrade the contract logic | replace_class_syscall without assert_only_owner or equivalent |
| L1-L2 message replay | Same L1→L2 message consumed multiple times | Missing nonce or message hash tracking in l1_handler |
| Account validation bypass | Custom __validate__ skips critical checks |
__validate__ returns success without signature verification |
| Storage collision | Two different state variables map to same storage slot | Custom storage_address_from_base with colliding inputs |
High — Significant Impact
| Vulnerability | Description | Detection Signal |
|---|---|---|
Reentrancy via call_contract_syscall |
External contract call re-enters before state update | call_contract_syscall before storage writes |
| Missing caller validation | External function callable by anyone | get_caller_address() not checked in sensitive functions |
| Felt252 comparison pitfalls | Comparing felts that represent "negative" numbers (near $P$) | < or > on felts where semantic negativity matters |
| Component storage isolation failure | Components sharing storage addresses | Overlapping #[storage] declarations across components |
| Incorrect modular division | Using / operator expecting integer division |
a / b on felt252 produces modular inverse, not truncation |
Medium — Conditional Impact
| Vulnerability | Description | Detection Signal |
|---|---|---|
| Unbounded storage growth | Maps or arrays without size limits | Map<K, V> without pruning mechanism |
| Missing events | State changes without event emission | write to storage without emit |
| Library dispatch trust | Using library_call_syscall with unchecked class hash |
External class hash in library call |
| Paymaster manipulation | Transaction fee payment logic exploitable | Custom __validate__ with fee token handling |
| Felt-to-u256 conversion errors | Incorrect type casting between felt and uint types | felt252.into() or TryInto::<u256> without bounds |
Cairo-Specific Pitfalls
Felt Arithmetic Is Modular
// DANGEROUS: Felt subtraction wraps around P
let balance: felt252 = 100;
let amount: felt252 = 200;
let result = balance - amount;
// result is NOT -100, it is P - 100 (a very large number)
// Any comparison result > 0 will be TRUE
// SAFE: Use u256 for amounts
let balance: u256 = 100;
let amount: u256 = 200;
assert(balance >= amount, 'Insufficient balance'); // Correctly reverts
Division Is Not Integer Division
// UNEXPECTED: Felt division is modular inverse
let a: felt252 = 7;
let b: felt252 = 2;
let result = a / b;
// result is NOT 3 (integer truncation)
// result is the felt252 x such that x * 2 ≡ 7 (mod P)
// This is (P + 7) / 2 = a very large number
// SAFE: Use u256 for integer division
let a: u256 = 7;
let b: u256 = 2;
let result = a / b; // result is 3 (integer truncation, as expected)
Resources
| Resource | Description |
|---|---|
| Cairo Patterns | Vulnerability patterns specific to Cairo language and Starknet |
| Starknet Security | Starknet architecture security: sequencer, proofs, upgrades |
| Messaging Security | L1-L2 messaging: message replay, nonce handling, proof finalization |
Workflows
| Workflow | Description |
|---|---|
| Cairo Audit | Step-by-step audit workflow for Cairo contracts on Starknet |
Notable Starknet Security Incidents
| Incident | Root Cause | Impact |
|---|---|---|
| Various DeFi exploits on Starknet testnet | Felt overflow in token balances | Fund inflation |
| L1→L2 message replay in early bridges | Missing consumed message tracking | Double-spending |
| Account contract vulnerabilities | Insufficient __validate__ logic |
Transaction forging |
Integration with Other Skills
| Skill | Connection |
|---|---|
starknet-scanner/ |
Shares Cairo language patterns; this skill focuses on language, starknet-scanner focuses on chain |
chain-guides/starknet.md |
Chain-level context for Starknet architecture |
patterns/ |
Cross-reference with general vulnerability categories (reentrancy, access control) |
exploit-forensics/ |
Limited Starknet exploits but growing as ecosystem matures |
Error Code Reference
Common Cairo/Starknet errors encountered during audits. Cairo errors manifest as felt252 values in transaction reverts.
Cairo Language Errors
| Error Pattern | Error Source | Meaning |
|---|---|---|
felt252 overflow |
Arithmetic operation | Result exceeds field prime P (≈ 2^251 + 17·2^192 + 1) — wraps silently |
index out of bounds |
Array access | Array index exceeds length — causes execution failure |
Option::unwrap on None |
Option handling | Attempted to unwrap an empty Option — missing existence check |
assertion failed |
assert() macro |
Contract invariant violation — check assert conditions |
'Entry not found' |
StorageMap access | Key does not exist in LegacyMap/Map — missing default handling |
u256_sub Overflow |
Subtraction underflow | Unsigned subtraction result would be negative |
u256_add Overflow |
Addition overflow | Addition exceeds u256 max value |
Division by zero |
Division operation | Denominator is zero — missing zero-check |
Starknet Contract Errors
| Error Pattern | Error Source | Meaning |
|---|---|---|
'Caller is not the owner' |
OZ Ownable | Missing ownership — check access control |
'Caller is the zero address' |
OZ Ownable | Zero address caller — validate caller identity |
'ERC20: insufficient balance' |
OZ ERC20 | Token balance too low |
'ERC20: insufficient allowance' |
OZ ERC20 | Approval not set or insufficient |
'ERC20: approve to zero address' |
OZ ERC20 | Invalid spender address |
'ERC721: invalid token ID' |
OZ ERC721 | Token does not exist |
'Contract already initialized' |
Initializable pattern | Re-initialization attempt — check initializer guard |
'ENTRYPOINT_NOT_FOUND' |
Starknet OS | Called selector doesn't exist on contract |
'UNINITIALIZED_CONTRACT' |
Starknet OS | Class not declared or deployed |
'TRANSACTION_FAILED' |
Starknet sequencer | Generic failure — check inner error for details |
Felt Arithmetic Audit Concerns
| Issue | Risk | Detection |
|---|---|---|
| Felt overflow wrapping | Arithmetic wraps mod P instead of reverting | Flag all felt252 math ops — prefer u256/u128 for financial math |
| Felt comparison edge cases | < and > comparisons are mod P, not natural ordering |
Check comparisons on felt252 values — may produce unexpected results |
| Integer to felt truncation | Converting large u256 to felt252 silently truncates | Flag all into() / try_into() conversions between types |
| Storage key collision | LegacyMap keys hash via Pedersen — potential collision with crafted inputs | Verify map key uniqueness assumptions |
Troubleshooting
| Issue | Likely Cause | Solution |
|---|---|---|
| Scanner misses felt overflow issues | Analyzing code as if integers revert on overflow | Cairo felt252 wraps mod P — flag all felt arithmetic in financial logic |
| False positives on storage access | Scanner flags all LegacyMap reads as risky | Verify if default value (0) is safe for the use case |
| Account abstraction patterns not detected | Scanner uses EVM mental model | Load starknet-scanner/ for account abstraction-specific checks |
| Component architecture flaws missed | Scanner doesn't understand Cairo components | Manually review component trait implementations and storage conflicts |
| Missed reentrancy via L1 handler | Scanner only checks external functions | Include #[l1_handler] functions in reentrancy analysis |
| Cairo version mismatch warnings | Pattern written for Cairo 1.x, contract uses 2.x | Verify syntax patterns match target Cairo version; update detection rules |