From 2cae015d23c8c294a1c94477e72cf82168cb3ba0 Mon Sep 17 00:00:00 2001 From: technovision99 <25871300+technovision99@users.noreply.github.com> Date: Fri, 14 Jul 2023 08:42:40 +0200 Subject: [PATCH] Update README.md (#22) * Update README.md added name + unenforced view detector * Update README.md --------- Co-authored-by: Simone --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 7157f2a..3978bd6 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,94 @@ -# TBD +# Caracal -TBD is a static analyzer tool over the SIERRA representation for Starknet smart contracts. +Caracal is a static analyzer tool over the SIERRA representation for Starknet smart contracts. ## Features - Detectors to detect vulnerable Cairo code -- Printers to report informations +- 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](https://github.com/crytic/caracal/releases). + +### Building from source +You need the Rust compiler and Cargo. +Building from git: +```bash +cargo install --git https://github.com/crytic/caracal --profile release --force +``` +Building from a local copy: +```bash +git clone https://github.com/crytic/caracal +cd caracal +cargo install --path . --profile release --force +``` ## Usage -You need to pass the path to the [corelib](https://github.com/starkware-libs/cairo/tree/main/corelib) library either with the `--corelib` cli option or by setting the `CORELIB_PATH` environment variable. List detectors: ```bash -cargo run --release --bin starknet-static-analysis detectors +caracal detectors +``` +List printers: +```bash +caracal printers ``` +### Standalone +To use with a standalone cairo file you need to pass the path to the [corelib](https://github.com/starkware-libs/cairo/tree/main/corelib) library either with the `--corelib` cli option or by setting the `CORELIB_PATH` environment variable. Run detectors: ```bash -cargo run --release --bin starknet-static-analysis detect path/file/to/analyze --corelib path/to/corelib/src +caracal detect path/file/to/analyze --corelib path/to/corelib/src ``` -List printers: +Run printers: ```bash -cargo run --release --bin starknet-static-analysis printers +caracal print path/file/to/analyze --printer printer_to_use --corelib path/to/corelib/src +``` +### Scarb +If you have a project that uses Scarb you need to add the following in Scarb.toml: +```bash +[[target.starknet-contract]] +sierra = true + +[cairo] +sierra-replace-ids = true +``` +Then pass the path to the directory where Scarb.toml resides. +Run detectors: +```bash +caracal detect path/to/dir ``` Run printers: ```bash -cargo run --release --bin starknet-static-analysis print path/file/to/analyze --what printer_to_use --corelib path/to/corelib/src +caracal print path/to/dir --printer printer_to_use ``` ## Detectors - Num | Detector | What it Detects | Impact | Confidence --- | --- | --- | --- | --- 1 | `controlled-library-call` | Library calls with a user controlled class hash | High | Medium -2 | `unused-events` | Events defined but not emitted | Medium | Medium -3 | `dead-code` | Private functions never used | Low | Medium -4 | `unused-arguments` | Unused arguments | Low | High +2 | `unchecked-l1-handler-from` | Detect L1 handlers without from address check | High | Medium +3 | `reentrancy` | Detect when a storage variable is read before an external call and written after | Medium | Medium +4 | `unused-events` | Events defined but not emitted | Medium | Medium 5 | `unused-return` | Unused return values | Medium | Medium +6 | `unenforced-view` | Function has view decorator but modifies state | Medium | Medium +7 | `unused-arguments` | Unused arguments | Low | High +8 | `reentrancy-benign` | Detect when a storage variable is written after an external call but not read before | Low | Medium +9 | `reentrancy-events` | Detect when an event is emitted after an external call leading to out-of-order events | Low | Medium +10 | `dead-code` | Private functions never used | Low | Medium ## Printers - `cfg`: Export the CFG of each function in a .dot file -- `cfg-optimized`: Export the CFG optimized of each function in a .dot file. Note now it's the same as cfg because the SIERRA representation doesn't have the pattern that was optimized anymore. +- `callgraph`: Export function call graph to a .dot file ## How to contribute Check the wiki on the following topics: - * [How to write a detector](https://github.com/crytic/starknet-static-analysis/wiki/How-to-write-a-detector) - * [How to write a printer](https://github.com/crytic/starknet-static-analysis/wiki/How-to-write-a-printer) + * [How to write a detector](https://github.com/crytic/caracal/wiki/How-to-write-a-detector) + * [How to write a printer](https://github.com/crytic/caracal/wiki/How-to-write-a-printer) ## Limitations +- At the moment only Cairo 1 is supported (compiler version up to 1.1.1). +- 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. -- Works correctly only with Starknet contracts that have at least one `view` or `external` function.