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.
v2026.11.12-149d7b23 instalações+3 em 7 dias8,2 mil EstrelasCC-BY-SA-4.0sincronizado há 22 horas
Instalar
Ainda não tem a CLI da NotHoly? Instale primeiro.
$ curl -fsSL https://notholy.com/install.sh | sh$ notholy skills install trailofbits/cairo-vulnerability-scannerGrava em ~/.notholy/skills depois de conferir a assinatura e o SHA-256.
AssinaturaAssinado, ed25519
Pacote3e9dff18…d14ad095
3e9dff187f23…08d5d14ad0954 arquivos · 11.8 KBVarreduraMédio2 achados
- injection.no_confirmationSKILL.md:100
- Links para domínios externos
Fontegithub.com/trailofbits/skills/tree/main/plugins/building-secure-contracts/skills/cairo-vulnerability-scanner@149d7b2
Este item ainda não foi escrito no seu idioma, então aparece em English.
Nesta página
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_syscallProject 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, above them a coverage table carrying a verdict for every pattern
- 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:
- Felt252 Arithmetic Overflow/Underflow ⚠️ HIGH -
felt252wraps silently; useu128/u256 - L1 to L2 Address Conversion ⚠️ HIGH - L1 address not validated against STARKNET_FIELD_PRIME
- L1 to L2 Message Failure ⚠️ HIGH - No cancellation path when a message cannot be consumed
- Overconstrained L1 <-> L2 Interaction ⚠️ MEDIUM - Coupling that can strand funds or block progress
- Signature Replay Protection ⚠️ HIGH - No nonce, or a domain separator missing chain/contract
- Unchecked from_address in L1 Handler ⚠️ CRITICAL - Any L1 contract can drive the handler
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 insteadStep 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-validation8. Reporting Format
Coverage Table
Report on every pattern in §6, whether or not it turned anything up. Emit this table above the findings, with all 6 rows present:
| # | Pattern | Verdict | Evidence |
|---|---|---|---|
| 1 | Felt252 Arithmetic Overflow/Underflow | clear |
balances are u256; searched felt252 in arithmetic, none |
| 2 | L1 to L2 Address Conversion | ||
| 3 | L1 to L2 Message Failure | ||
| 4 | Overconstrained L1 <-> L2 Interaction | ||
| 5 | Signature Replay Protection | ||
| 6 | Unchecked from_address in L1 Handler |
Each verdict is one of:
found— citefile:lineand write the finding up in full below.clear— the pattern applies to this contract and the contract handles it. Name the function, trait, or check you searched for, so a reader can repeat the search.n/a— the pattern cannot apply here. Give the reason in one clause ("no L1 handlers in this contract"). Not having looked is notn/a.
A table with fewer than 6 rows is an incomplete scan and must be reported as one. A row whose Verdict cell is empty is incomplete in the same way: row 1 above is filled in to show the shape, and every row is filled in the same way before the report is done. Six clear verdicts is a
result a reader can act on. A report that covers two patterns and says nothing about the other four reads
exactly like a clean contract, and that is the failure this table exists to prevent.
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_address, 1000000])`
3. L2 handler processes message without checking sender
4. Attacker receives 1,000,000 tokens without depositing any funds
5. Protocol suffers infinite mint vulnerability
**Recommendation**:
Validate `from_address` against authorized L1 bridge:
```rust
#[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`9. 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)
10. 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: |
# Rebuilds from source each run; cache ~/.cargo or pin a release binary instead.
cargo install --git https://github.com/crytic/caracal --profile release --force
caracal detect src/ --fail-on high,critical11. 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
12. 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 validatefrom_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
- Coverage table emitted with all 6 rows, each carrying a verdict of
found,clearorn/awith a reason
13. Rationalizations to Reject
- "The contract is small, so most patterns obviously don't apply." Obvious to whom? An
n/acosts one clause and makes the judgment reviewable. Silence records nothing, and a reader cannot tell it apart from not having checked. - "Caracal reported nothing, so the contract is clean." Caracal covers a subset of these 6 patterns and does not reach the logic-level ones at all. A clean tool run is one row of evidence, not a verdict on the patterns it never examined. Say which patterns it covered.
- "I checked the patterns that matter for this contract." Deciding which patterns matter is the scan, not a precondition for starting it. Rank by severity after the table is complete, not by leaving rows out.
- "No findings, so there is nothing to report." A zero-finding scan still emits the full coverage table. That table is the deliverable: it is what distinguishes a contract that was examined from one that was glanced at.
- "Cairo 1 has native overflow checks, so arithmetic is safe." Name the types.
felt252does not behave like the sized integer types, and the boundary between them is where pattern 4 lives. - "The L1 side validates that." Then cite the L1 contract. A check you believe exists across the bridge is
an assumption until you have read it, and unverified
from_addressis the canonical StarkNet bridge bug.
Arquivos desta versão
agents/1259 B
- openai.yaml259 B
assets/13.0 KB
- trail-of-bits-mark.svg3.0 KB
resources/120.8 KB
- VULNERABILITY_PATTERNS.md20.8 KB
- SKILL.md12.8 KB
Permissões
| Permissão | Declarada | Encontrada na varredura |
|---|---|---|
| Lê arquivos | Sim | Sim |
| Grava arquivos | Sim | Sim |
| Roda comandos no shell | Sim | Sim |
| Usa a rede | Sim | Sim |
| Usa conectores | Não | Não |
| Controla um navegador | Não | Não |
Achados da varredura
Revisado em 13 de nov. de 2026
- MédiaPrompt injection · injection.no_confirmationSKILL.md:100
- InfoLink · Links para domínios externos
Uma varredura limpa reduz o risco, mas não prova que o pacote é seguro. Leia o que você instala.
| Versão | Publicada em | Commit | SHA-256 | Assinatura | Mudança de permissão |
|---|---|---|---|---|---|
| v2026.11.12-149d7b2 | 13 de nov. de 2026 | 149d7b2 | 3e9dff18 | Assinada | – |
Mais de trailofbits
Tudo deste publicadorMais em Criptografia e Web3
Ver a categoriaPergunte tudo o que o seu escopo permite.
Crie a conta, adicione créditos e faça a primeira pergunta no chat ou no terminal.
- 1/3
Crie a conta
Individual ou empresa. Dá para virar empresa depois sem perder saldo nem chaves.
Pessoa físicaEmpresa - 2/3
Adicione créditos
No cartão. Você paga por token, sem assinatura.
$5.00recarga mínima - 3/3
Pergunte
No chat, ou instale o CLI e rode notholy login no terminal.
$ notholy login