amarna

Amarna

Amarna é um analisador estático e linter para a linguagem de programação do Cairo.

Características

• Encontra-se de código e vulnerabilidades potenciais no código do Cairo
• Parsing idêntico do compilador de código do Cairo e contratos de starknet
• Suporta a criação de regras locais e globais
• Exporta o AST analisado de um arquivo do Cairo
• Exporta a análise estática resulta para o formato SARIF.

Uso básico

Analise um projeto do Cairo no diretório atual e exporte os resultados do SARIF para um arquivo:

amarna . -o out.sarif

Analise um único arquivo file.cairo e exporte os resultados do SARIF para um arquivo:

amarna file.cairo -o out.sarif

Analise um único arquivo file.cairo e imprima um resumo dos resultados:

amarna file.cairo -s

Integração

• Para integração da ação do GitHub, use a ação de amarna.

Regras atualmente suportadas

#	Regra	O que encontra	Impacto	Precisão
1	Operações aritméticas	Todos os usos das operações aritméticas +, -, *e / /	Informações	Alto
2	Argumentos não utilizados	Argumentos de função que não são usados ​​nas funções em que eles aparecem	Aviso	Alto
3	Importações não utilizadas	Importações não utilizadas	Informações	Alto
4	Decoradores e nivadas	Decoradores de código e erro	Informações	Alto
5	Funções não utilizadas	Funções que nunca são chamadas	Informações	Médio
6	Códigos de erro	Chamadas de função que têm valores de retorno que devem ser verificados	Informações	Alto
7	Uso de retenção inconsistente	Afirma que usa a mesma constante de maneiras diferentes, por exemplo, assert_le(amount, BOUND) e assert_le(amount, BOUND - 1)	Aviso	Alto
8	Lojas mortas	Variáveis ​​que são atribuídas valores, mas não usadas antes de uma declaração de retorno	Informações	Médio
9	Transbordou transbordamentos	Chamadas de função que ignoram as bandeiras de transbordamento retornado, por exemplo, uint256_add	Aviso	Alto
10	Endereço do chamador Valor de retorno	Função chama para a função get_caller_address .	Informações	Alto
11	Colisão variável de armazenamento	Múltiplo @storage_var com o mesmo nome. (descontinuado)	Aviso	Alto
12	Importação de função implícita	Função com decorador @external, @view, @l1_handler que está sendo implicitamente importado. (descontinuado)	Informações	Alto
13	Função de visão não forçada	Modificação de estado dentro de uma função @view	Informações	Alto
14	Variável não inicializada	Variáveis ​​locais que nunca são inicializadas.	Informações	Alto

Uso

Analise um projeto do Cairo no diretório atual e os resultados de exportação para um arquivo:

amarna . -o out.sarif

Analise um único arquivo deleverage.cairo e exporte resultados para um arquivo:

amarna deleverage.cairo -o deleverage.sarif

Analise um único code.cairo de arquivo.cairo e imprima um resumo dos resultados:

amarna code.cairo -s

Analisar um arquivo do Cairo e produzir o AST recuperado no png :

amarna file.cairo -png

Analise um arquivo do Cairo com a regra UNUSUS_IMPORT:

amarna file.cairo --rules=unused-imports

Analise um arquivo do Cairo usando todas as regras, exceto a regra da Aritmética-ADD:

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

O menu de ajuda total é:

 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 arquivo SARIF

O formato do arquivo SARIF é um formato padrão para ferramentas de análise estática e pode ser visualizado no VSCode com a extensão oficial.

Instalação

pip install amarna

Como as regras funcionam

As regras de análise estática podem ser:

• Regras locais, que analisam cada arquivo de forma independente.
• Regras de Gatherler, que analisam cada arquivo de forma independente e reunem dados a serem usados ​​nas regras pós-processo.
• As regras pós-processo, que são executadas depois que todos os arquivos foram analisados ​​podem usar os dados coletados nas regras do coletor.

Exemplos deles são:

• Regras locais: encontre todas as operações aritméticas em um arquivo
• Regras do coletor: Reúna todas as funções declaradas e chamadas funções
• Regras pós-processo: encontre funções não utilizadas usando os dados coletados, ou seja, funções que foram declaradas, mas nunca chamadas.

Lista de regra, denilista e comentários embutidos

Nomes de regras

Obter os nomes das regras atualmente implementadas com:

 amarna --show-rules

Regra de altura

Execute amarna com um conjunto definido de regras usando

 amarna --rules=rule1,rule2 .

O comando a seguir executará apenas a regra unused-imports e imprimirá o resultado resumido

 amarna --rules=unused-imports . -s

Regra denilista

Execute amarna com todas as regras, exceto um conjunto definido de regras usando

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

Regra em linha desativando comentários

Você pode alterar a primeira linha de um arquivo do Cairo para desativar uma regra específica definida nesse arquivo. Por exemplo, adicionando a linha

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

como a primeira linha de file.cairo e correndo amarna com

amarna directory/ --disable-inline -s

não relatará nenhuma regra aritmética ao arquivo file.cairo .