Caracal
Caracal is a static analyzer tool over the SIERRA representation for Starknet smart contracts.
Features
- Detectors to detect vulnerable Cairo code
- Printers to report information
- Taint analysis
- Data flow analysis framework
- Easy to run in Scarb projects
Installation
Precompiled binaries
Precompiled binaries are available on our releases page. If you are using Cairo compiler 1.x.x uses the binary v0.1.x otherwise if you are using the Cairo compiler 2.x.x uses v0.2.x.
Building from source
You need the Rust compiler and Cargo. Building from git:
cargo install --git https://github.com/crytic/caracal --profile release --forceBuilding from a local copy:
git clone https://github.com/crytic/caracal
cd caracal
cargo install --path . --profile release --forceUsage
List detectors:
caracal detectorsList printers:
caracal printersStandalone
To use with a standalone cairo file and you have a local cairo compiler binary it's enough to point it to the file. Otherwise otherwise a bundled compiler is used and you need to pass the path to the corelib library either with the --corelib cli option or by setting the CORELIB_PATH environment variable.
Run detectors:
caracal detect path/file/to/analyzecaracal detect path/file/to/analyze --corelib path/to/corelib/srcRun printers:
caracal print path/file/to/analyze --printer printer_to_use --corelib path/to/corelib/srcCairo project
If you have a cairo project with multiple files and contracts you may need to specify which contracts with --contract-path. The local cairo compiler binary is used if available otherwise a bundled compiler is used. In the latter case you also need to specify the corelib as explained above for the standalone case. The path is the directory where cairo_project.toml resides.
Run detectors:
caracal detect path/to/dircaracal detect path/to/dir --contract-path token::myerc20::... token::myerc721::...Run printers:
caracal print path/to/dir --printer printer_to_useScarb
If you have a project that uses Scarb you need to add the following in Scarb.toml:
[[target.starknet-contract]]
sierra = true
[cairo]
sierra-replace-ids = trueThen pass the path to the directory where Scarb.toml resides. Run detectors:
caracal detect path/to/dirRun printers:
caracal print path/to/dir --printer printer_to_useDetectors
| Num | Detector | What it Detects | Impact | Confidence | Cairo |
|---|---|---|---|---|---|
| 1 | controlled-library-call |
Library calls with a user controlled class hash | High | Medium | 1 & 2 |
| 2 | unchecked-l1-handler-from |
Detect L1 handlers without from address check | High | Medium | 1 & 2 |
| 3 | felt252-unsafe-arithmetic |
Detect user controlled operations with felt252 type, which is not overflow/underflow safe | Medium | Medium | 1 & 2 |
| 4 | reentrancy |
Detect when a storage variable is read before an external call and written after | Medium | Medium | 1 & 2 |
| 5 | read-only-reentrancy |
Detect when a view function read a storage variable written after an external call | Medium | Medium | 1 & 2 |
| 6 | unused-events |
Events defined but not emitted | Medium | Medium | 1 & 2 |
| 7 | unused-return |
Unused return values | Medium | Medium | 1 & 2 |
| 8 | unenforced-view |
Function has view decorator but modifies state | Medium | Medium | 1 |
| 9 | tx-origin |
Detect usage of the transaction origin address as access control | Medium | Medium | 2 |
| 10 | unused-arguments |
Unused arguments | Low | Medium | 1 & 2 |
| 11 | reentrancy-benign |
Detect when a storage variable is written after an external call but not read before | Low | Medium | 1 & 2 |
| 12 | reentrancy-events |
Detect when an event is emitted after an external call leading to out-of-order events | Low | Medium | 1 & 2 |
| 13 | dead-code |
Private functions never used | Low | Medium | 1 & 2 |
| 14 | use-after-pop-front |
Detect use of an array or a span after removing element(s) | Low | Medium | 1 & 2 |
The Cairo column represent the compiler version(s) for which the detector is valid.
Printers
cfg: Export the CFG of each function to a .dot filecallgraph: Export function call graph to a .dot file
How to contribute
Check the wiki on the following topics:
Limitations
- Inlined functions are not handled correctly.
- Since it's working over the SIERRA representation it's not possible to report where an error is in the source code but we can only report SIERRA instructions/what's available in a SIERRA program.