Saltar al contenido
Nuevo

DeepSeek V4.1 Flash gratis por 7 días: 10M tokens al día tras una recarga de $10 o más. Hasta el 30/11.

Cómo funciona
trailofbits/cairo-vulnerability-scannerCriptografía y Web3

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 instalaciones+3 en 7 días8,2 mil EstrellasCC-BY-SA-4.0sincronizado hace 22 horas

Instalar

¿Aún no tienes la CLI de NotHoly? Instálala primero.

$ curl -fsSL https://notholy.com/install.sh | sh
$ notholy skills install trailofbits/cairo-vulnerability-scanner

Escribe en ⁦~/.notholy/skills⁩ después de comprobar la firma y el SHA-256.

FirmaFirmado, ed25519
NGCV4jKQbO…N8cBTRDg==La CLI comprueba el SHA-256 y la firma antes de escribir cualquier archivo.
Paquete3e9dff18…d14ad095
3e9dff187f23…08d5d14ad0954 archivos · ⁦11.8 KB⁩
EscaneoMedio2 hallazgos
  • injection.no_confirmationSKILL.md:100
  • Enlaces a dominios externos
Ver el escaneo completo
Fuentegithub.com/trailofbits/skills/tree/main/plugins/building-secure-contracts/skills/cairo-vulnerability-scanner@149d7b2

Esta entrada todavía no está escrita en tu idioma, así que aparece en English.

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

rust
// 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: 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:

  1. Search your codebase for Cairo files
  2. Analyze each contract for the 6 vulnerability patterns
  3. Report findings with file references and severity, above them a coverage table carrying a verdict for every pattern
  4. Provide fixes for each identified issue
  5. Check L1-L2 interactions for messaging vulnerabilities

5. Example Output

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

text
=== 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:

  1. Felt252 Arithmetic Overflow/Underflow ⚠️ HIGH - felt252 wraps silently; use u128/u256
  2. L1 to L2 Address Conversion ⚠️ HIGH - L1 address not validated against STARKNET_FIELD_PRIME
  3. L1 to L2 Message Failure ⚠️ HIGH - No cancellation path when a message cannot be consumed
  4. Overconstrained L1 <-> L2 Interaction ⚠️ MEDIUM - Coupling that can strand funds or block progress
  5. Signature Replay Protection ⚠️ HIGH - No nonce, or a domain separator missing chain/contract
  6. 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

  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

bash
# 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

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 — cite file:line and 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 not n/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

markdown
## [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

rust
#[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)

rust
// 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

yaml
# .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,critical

11. Additional Resources


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 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
  • Coverage table emitted with all 6 rows, each carrying a verdict of found, clear or n/a with a reason

13. Rationalizations to Reject

  • "The contract is small, so most patterns obviously don't apply." Obvious to whom? An n/a costs 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. felt252 does 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_address is the canonical StarkNet bridge bug.

Archivos de esta versión

Permisos

PermisoDeclaradoHallado en el escaneo
Lee archivosSíSí
Escribe archivosSíSí
Ejecuta comandos de shellSíSí
Usa la redSíSí
Usa conectoresNoNo
Controla un navegadorNoNo

Hallazgos del escaneo

Revisado el 13 nov 2026

  1. MediaPrompt injection · injection.no_confirmationSKILL.md:100
  2. InfoEnlace · Enlaces a dominios externos

Un escaneo limpio baja el riesgo, pero no prueba que el paquete sea seguro. Lee lo que instalas.

VersiónPublicadaCommitSHA-256FirmaCambio de permisos
v2026.11.12-149d7b213 nov 2026149d7b23e9dff18Firmada–

Pregunta todo lo que tu alcance permite.

Crea la cuenta, añade créditos y haz la primera pregunta en el chat o en la terminal.

  1. 1/3

    Crea la cuenta

    Individual o empresa. Puedes pasar a empresa después sin perder saldo ni claves.

    IndividualEmpresa
  2. 2/3

    Añade créditos

    Con tarjeta. Pagas por token, sin suscripción.

    $5.00recarga mínima
  3. 3/3

    Pregunta

    En el chat, o instala el CLI y ejecuta notholy login en tu terminal.

    $ notholy login