Package: amarna
AmarnaAmarna is a static-analyzer and linter for the Cairo programming language.FeaturesFinds code-smells and potential vulnerabilities in Cairo codeCompiler-identical parsing of Cairo code and StarkNet contractsSupports creating local and global rulesExports the parsed AST of a Cairo fileExports static-analysis results to theSARIFformat.Basic UsageAnalyze a Cairo project in the current directory and export the SARIF results to a file:amarna.-oout.sarifAnalyze a single filefile.cairoand export the SARIF results to a file:amarnafile.cairo-oout.sarifAnalyze a single filefile.cairoand print a summary of the results:amarnafile.cairo-sIntegrationFor GitHub action integration, useamarna-action.Currently supported rules#RuleWhat it findsImpactPrecision1Arithmetic operationsAll uses of arithmetic operations +, -, *, and /InfoHigh2Unused argumentsFunction arguments that are not used in the functions in which they appearWarningHigh3Unused importsUnused importsInfoHigh4Mistyped decoratorsMistyped code decoratorsInfoHigh5Unused functionsFunctions that are never calledInfoMedium6Error codesFunction calls that have return values that must be checkedInfoHigh7Inconsistent assert usageAsserts that use the same constant in different ways, e.g.,assert_le(amount, BOUND)andassert_le(amount, BOUND - 1)WarningHigh8Dead storesVariables that are assigned values but not used before a return statementInfoMedium9Unchecked overflowsFunction calls that ignore the returned overflow flags, e.g.,uint256_addWarningHigh10Caller address return valueFunction calls to theget_caller_addressfunction.InfoHigh11Storage variable collisionMultiple@storage_varwith the same name. (deprecated)WarningHigh12Implicit function importFunction with decorator@external, @view, @l1_handlerthat is being implicitly imported. (deprecated)InfoHigh13Unenforced view functionState modification within a@viewfunctionInfoHigh14Uninitialized variableLocal variables that are never initialized.InfoHighUsageAnalyze a Cairo project in the current directory and export results to a file:amarna.-oout.sarifAnalyze a single filedeleverage.cairoand export results to a file:amarnadeleverage.cairo-odeleverage.sarifAnalyze a single filecode.cairoand print a summary of the results:amarnacode.cairo-sParse a Cairo file and output the recovered AST inpng:amarnafile.cairo-pngAnalyze a Cairo file with the unused_import rule:amarnafile.cairo--rules=unused-importsAnalyze a Cairo file using all rules except the arithmetic-add rule:amarnafile.cairo--except-rules=arithmetic-addThe 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,rulename2SARIF file formatTheSARIFfile format is a standard format for static-analysis tools and can be viewed in vscode with theofficial extension.InstallationpipinstallamarnaHow the rules workThe 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 filegatherer rules: gather all declared functions, and called functionspost-process rules: find unused functions using the gathered data, i.e., functions that were declared but never called.Rule allowlist, denylist and inline commentsRule namesObtain the names of the currently implemented rules with:amarna--show-rulesRule allowlistRun amarna with a defined set of rules usingamarna--rules=rule1,rule2.The following command will only run theunused-importsrule and print the summary resultamarna--rules=unused-imports.-sRule denylistRun amarna with all rules except a defined set of rules usingamarna--exclude-rules=arithmetic-add,arithmetic-sub.-sInline rule disabling commentsYou 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-addas the first line offile.cairoand running amarna withamarnadirectory/--disable-inline-swill not report any arithmetic rule to thefile.cairofile.