amarna

Amarna

Amarna es un analizador estático y un linter para el lenguaje de programación de El Cairo.

Características

• Encuentra al código de código y vulnerabilidades potenciales en el código de El Cairo
• Analización del compilador-idéntico del código de El Cairo y los contratos de Starknet
• Apoya la creación de reglas locales y globales
• Exporta el AST analizado de un archivo de El Cairo
• Exporta resultados de análisis estático al formato SARIF.

Uso básico

Analice un proyecto de El Cairo en el directorio actual y exporte los resultados de SARIF a un archivo:

amarna . -o out.sarif

Analice un file.cairo de archivo único.cairo y exporte los resultados de SARIF a un archivo:

amarna file.cairo -o out.sarif

Analice un solo file.cairo de archivo.cairo e imprima un resumen de los resultados:

amarna file.cairo -s

Integración

• Para la integración de la acción de GitHub, use Amarna-Action.

Reglas compatibles actualmente

#	Regla	Lo que encuentra	Impacto	Precisión
1	Operaciones aritméticas	Todos los usos de las operaciones aritméticas +, -, *y /	Información	Alto
2	Argumentos no utilizados	Argumentos de función que no se utilizan en las funciones en las que aparecen	Advertencia	Alto
3	Importaciones no utilizadas	Importaciones no utilizadas	Información	Alto
4	Decoradores con mistre	Decoradores de código con mistre	Información	Alto
5	Funciones no utilizadas	Funciones que nunca se llaman	Información	Medio
6	Códigos de error	Llamadas de función que tienen valores de retorno que deben verificarse	Información	Alto
7	Uso de afirmación inconsistente	Afirma que usa la misma constante de diferentes maneras, por ejemplo, assert_le(amount, BOUND) y assert_le(amount, BOUND - 1)	Advertencia	Alto
8	Tiendas muertas	Variables que se asignan valores pero no se usan antes de una declaración de retorno	Información	Medio
9	Desbordamientos sin control	Las llamadas de la función que ignoran las banderas de desbordamiento devueltas, por ejemplo, uint256_add	Advertencia	Alto
10	Valor de retorno de la dirección de la llamada	Llamadas de función a la función get_caller_address .	Información	Alto
11	Colisión variable de almacenamiento	Múltiples @storage_var con el mismo nombre. (Deprecido)	Advertencia	Alto
12	Importación de funciones implícitas	Funcionar con decorador @external, @view, @l1_handler que se está importando implícitamente. (Deprecido)	Información	Alto
13	Función de vista no forzada	Modificación de estado dentro de una función @view	Información	Alto
14	Variable no inicializada	Variables locales que nunca se inicializan.	Información	Alto

Uso

Analice un proyecto de El Cairo en el directorio actual y exporte los resultados a un archivo:

amarna . -o out.sarif

Analice un solo archivo deleverage.cairo y exporte los resultados a un archivo:

amarna deleverage.cairo -o deleverage.sarif

Analice un solo code.cairo de archivo. Cairo e imprima un resumen de los resultados:

amarna code.cairo -s

Analice un archivo de El Cairo y salga el AST recuperado en png :

amarna file.cairo -png

Analice un archivo de El Cairo con la regla no utilizada_import:

amarna file.cairo --rules=unused-imports

Analice un archivo de El Cairo utilizando todas las reglas, excepto la regla aritmética-ADD:

amarna file.cairo --except-rules=arithmetic-add

El menú de ayuda completa es:

 usage: amarna [-h] [-p] [-o OUTPUT] [-s] [-png] [-rules RULES] [-exclude-rules EXCLUDE_RULES] [-show-rules] [-disable-inline] -f

Amarna is a static-analyzer for the Cairo programming language.

positional arguments:
  -f                    the name of the .cairo file or directory with .cairo files to analyze

optional arguments:
  -h, --help            show this help message and exit
  -p, --print           print output
  -o OUTPUT, --output OUTPUT
                        file to write the output results in sarif format
  -s, -summary, --summary
                        output summary
  -png, --png           save a png with the AST of a file
  -rules RULES, --rules RULES
                        Only run this set of rules. Enter rule names comma-separated, e.g., dead-store,unused-arguments
  -exclude-rules EXCLUDE_RULES, --exclude-rules EXCLUDE_RULES
                        Exclude these rules from the analysis. Enter rule names comma-separated, e.g., dead-store,unused-arguments
  -show-rules, --show-rules
                        Show all supported rules and descriptions.
  -disable-inline, --disable-inline
                        Disable rules with inline comments. The comments should be the first line and of the form: # amarna: disable=rulename1,rulename2

Formato de archivo sarif

El formato de archivo SARIF es un formato estándar para herramientas de análisis estático y se puede ver en VScode con la extensión oficial.

Instalación

pip install amarna

Cómo funcionan las reglas

Las reglas de análisis estático pueden ser:

• Reglas locales, que analizan cada archivo de forma independiente.
• Reglas recolectadoras, que analizan cada archivo de forma independiente y recopilan datos para ser utilizados en las reglas posteriores al procesamiento.
• Las reglas posteriores al proceso, que se ejecutan después de que se analizaran todos los archivos, pueden usar los datos recopilados en las reglas del receptor.

Ejemplos de estos son:

• Reglas locales: encuentre todas las operaciones aritméticas en un archivo
• Reglas del recolector: Reúna todas las funciones declaradas y las funciones llamadas
• Reglas posteriores al proceso: encuentre funciones no utilizadas que usen los datos recopilados, es decir, funciones que fueron declaradas pero nunca llamadas.

Comentarios de Listista, Denilista y en línea de reglas

Nombres de reglas

Obtenga los nombres de las reglas implementadas actualmente con:

 amarna --show-rules

Lista de pendientes de reglas

Ejecute Amarna con un conjunto definido de reglas utilizando

 amarna --rules=rule1,rule2 .

El siguiente comando solo ejecutará la regla unused-imports e imprimirá el resultado de resumen

 amarna --rules=unused-imports . -s

Denilista de reglas

Ejecute Amarna con todas las reglas, excepto un conjunto definido de reglas que usan

 amarna --exclude-rules=arithmetic-add,arithmetic-sub . -s

Comentarios en línea que deshabilitan las reglas

Puede cambiar la primera línea de un archivo de El Cairo para deshabilitar un conjunto de reglas específica en ese archivo. Por ejemplo, agregar la línea

 // amarna: disable=arithmetic-div,arithmetic-sub,arithmetic-mul,arithmetic-add

como la primera línea de file.cairo y ejecutando amarna con

amarna directory/ --disable-inline -s

No informará ninguna regla aritmética al archivo file.cairo .