cairo-vulnerability-scanner

cairo-vulnerability-scanner

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. ### 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. ## 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 ```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) // 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 Installs792Repositorytrailofbits/skillsGitHub Stars3.6KFirst SeenJan 19, 2026Security AuditsGen Agent Trust HubWarnSocketPassSnykPassInstalled onclaude-code723opencode662gemini-cli648codex642cursor619github-copilot590