Caracal

Caracal es una herramienta de análisis estático sobre la representación SIERRA para contratos inteligentes de Starknet.

Características

• Detectores para detectar código Cairo vulnerable
• Impresoras para reportar información
• Análisis de taint
• Marco de análisis de flujo de datos
• Fácil de ejecutar en proyectos Scarb

Instalación

Binarios precompilados

Los binarios precompilados están disponibles en nuestra página de lanzamientos. Si usas el compilador Cairo 1.x.x, utiliza el binario v0.1.x; de lo contrario, si usas el compilador Cairo 2.x.x, utiliza v0.2.x.

Compilación desde el código fuente

Necesitas el compilador de Rust y Cargo. Compilando desde git:

cargo install --git https://github.com/crytic/caracal --profile release --force

Compilando desde una copia local:

git clone https://github.com/crytic/caracal
cd caracal
cargo install --path . --profile release --force

Uso

Listar detectores:

caracal detectors

Listar impresoras:

caracal printers

Independiente

Para usar con un archivo Cairo independiente y tienes un binario del compilador Cairo local, es suficiente apuntarlo al archivo. De lo contrario, se usará un compilador empaquetado y necesitas pasar la ruta a la biblioteca corelib ya sea con la opción de CLI --corelib o configurando la variable de entorno CORELIB_PATH.
Ejecutar detectores:

caracal detect path/file/to/analyze

caracal detect path/file/to/analyze --corelib path/to/corelib/src

Ejecutar impresoras:

caracal print path/file/to/analyze --printer printer_to_use --corelib path/to/corelib/src

Proyecto Cairo

Si tienes un proyecto Cairo con múltiples archivos y contratos, puede que necesites especificar qué contratos con --contract-path. Se usará el binario del compilador Cairo local si está disponible; de lo contrario, se usará un compilador empaquetado. En este último caso, también debes especificar el corelib como se explicó anteriormente para el caso independiente. La ruta es el directorio donde reside cairo_project.toml.
Ejecutar detectores:

caracal detect path/to/dir

caracal detect path/to/dir --contract-path token::myerc20::... token::myerc721::...

Ejecutar impresoras:

caracal print path/to/dir --printer printer_to_use

Scarb

Si tienes un proyecto que usa Scarb, debes agregar lo siguiente en Scarb.toml:

[[target.starknet-contract]]
sierra = true

[cairo]
sierra-replace-ids = true

Luego pasa la ruta al directorio donde reside Scarb.toml. Ejecutar detectores:

caracal detect path/to/dir

Ejecutar impresoras:

caracal print path/to/dir --printer printer_to_use

Detectores

Num	Detector	Qué detecta	Impacto	Confianza	Cairo
1	controlled-library-call	Llamadas a librería con un hash de clase controlado por el usuario	Alto	Media	1 & 2
2	unchecked-l1-handler-from	Detecta manejadores L1 sin verificación de dirección de origen	Alto	Media	1 & 2
3	felt252-unsafe-arithmetic	Detecta operaciones controladas por el usuario con tipo felt252, que no es seguro contra desbordamiento/subdesbordamiento	Medio	Media	1 & 2
4	reentrancy	Detecta cuando una variable de almacenamiento se lee antes de una llamada externa y se escribe después	Medio	Media	1 & 2
5	read-only-reentrancy	Detecta cuando una función de vista lee una variable de almacenamiento escrita después de una llamada externa	Medio	Media	1 & 2
6	unused-events	Eventos definidos pero no emitidos	Medio	Media	1 & 2
7	unused-return	Valores de retorno no utilizados	Medio	Media	1 & 2
8	unenforced-view	La función tiene decorador de vista pero modifica el estado	Medio	Media	1
9	tx-origin	Detecta el uso de la dirección de origen de la transacción como control de acceso	Medio	Media	2
10	unused-arguments	Argumentos no utilizados	Bajo	Media	1 & 2
11	reentrancy-benign	Detecta cuando una variable de almacenamiento se escribe después de una llamada externa pero no se lee antes	Bajo	Media	1 & 2
12	reentrancy-events	Detecta cuando un evento se emite después de una llamada externa, provocando eventos fuera de orden	Bajo	Media	1 & 2
13	dead-code	Funciones privadas nunca utilizadas	Bajo	Media	1 & 2
14	use-after-pop-front	Detecta el uso de un array o un span después de eliminar elemento(s)	Bajo	Media	1 & 2

La columna Cairo representa la(s) versión(es) del compilador para las cuales el detector es válido.

Impresoras

• cfg: Exporta el CFG de cada función a un archivo .dot
• callgraph: Exporta el grafo de llamadas de funciones a un archivo .dot

Cómo contribuir

Consulta la wiki sobre los siguientes temas:

• Cómo escribir un detector
• Cómo escribir una impresora

Limitaciones

• Las funciones inlineadas no se manejan correctamente.
• Dado que funciona sobre la representación SIERRA, no es posible reportar dónde está un error en el código fuente, solo podemos reportar instrucciones SIERRA/lo que está disponible en un programa SIERRA.