Amarna is a static-analyzer for the Cairo programming language.
Project description
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. (deprecated) |
Warning | High |
| 12 | Implicit function import | Function with decorator @external, @view, @l1_handler that is being implicitly imported. (deprecated) |
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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
