Amarna

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

Features

Finds code-smells and potential vulnerabilities in Cairo code
Compiler-identical parsing of Cairo code and StarkNet contracts
Supports creating local and global rules
Exports the parsed AST of a Cairo file
Exports static-analysis results to the SARIF format.

Basic Usage

Analyze a Cairo project in the current directory and export the SARIF results to a file:

amarna . -o out.sarif

Analyze a single file file.cairo and export the SARIF results to a file:

amarna file.cairo -o out.sarif

Analyze a single file file.cairo and print a summary of the results:

amarna file.cairo -s

Integration

For GitHub action integration, use amarna-action.

Currently supported rules

#	Rule	What it finds	Impact	Precision
1	Arithmetic operations	All uses of arithmetic operations +, -, *, and /	Info	High
2	Unused arguments	Function arguments that are not used in the functions in which they appear	Warning	High
3	Unused imports	Unused imports	Info	High
4	Mistyped decorators	Mistyped code decorators	Info	High
5	Unused functions	Functions that are never called	Info	Medium
6	Error codes	Function calls that have return values that must be checked	Info	High
7	Inconsistent assert usage	Asserts that use the same constant in different ways, e.g., `assert_le(amount, BOUND)` and `assert_le(amount, BOUND - 1)`	Warning	High
8	Dead stores	Variables that are assigned values but not used before a return statement	Info	Medium
9	Unchecked overflows	Function calls that ignore the returned overflow flags, e.g., `uint256_add`	Warning	High
10	Caller address return value	Function calls to the `get_caller_address` function.	Info	High
11	Storage variable collision	Multiple `@storage_var` with the same name.	Warning	High
12	Implicit function import	Function with decorator `@external, @view, @l1_handler` that is being implicitly imported.	Info	High
13	Unenforced view function	State modification within a `@view` function	Info	High
14	Uninitialized variable	Local variables that are never initialized.	Info	High

Usage

Analyze a Cairo project in the current directory and export results to a file:

amarna . -o out.sarif

Analyze a single file deleverage.cairo and export results to a file:

amarna deleverage.cairo -o deleverage.sarif

Analyze a single file code.cairo and print a summary of the results:

amarna code.cairo -s

Parse a Cairo file and output the recovered AST in png:

amarna file.cairo -png

Analyze a Cairo file with the unused_import rule:

amarna file.cairo --rules=unused-imports

Analyze a Cairo file using all rules except the arithmetic-add rule:

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

The full help menu is:

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

SARIF file format

The SARIF file format is a standard format for static-analysis tools and can be viewed in vscode with the official extension.

Installation

pip install amarna

How the rules work

The static-analysis rules can be:

local rules, which analyse each file independently.
gatherer rules, which analyse each file independently and gather data to be used in post-process rules.
post-process rules, which run after all files were analyzed can use the data gathered in the gatherer rules.

Examples of these are:

local rules: find all arithmetic operations in a file
gatherer rules: gather all declared functions, and called functions
post-process rules: find unused functions using the gathered data, i.e., functions that were declared but never called.

Rule allowlist, denylist and inline comments

Rule names

Obtain the names of the currently implemented rules with:

 amarna --show-rules

Rule allowlist

Run amarna with a defined set of rules using

 amarna --rules=rule1,rule2 .

The following command will only run the unused-imports rule and print the summary result

 amarna --rules=unused-imports . -s

Rule denylist

Run amarna with all rules except a defined set of rules using

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

Inline rule disabling comments

You can change the first line of a cairo file to disable a specific rule set on that file. For example, adding the line

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

as the first line of file.cairo and running amarna with

amarna directory/ --disable-inline -s

will not report any arithmetic rule to the file.cairo file.

0xLucqs/amarna