Amarna

Amarna 是 Cairo 编程语言的静态分析器和代码检查器。

特性

• 在 Cairo 代码中查找代码异味和潜在漏洞
• 与 StarkNet 合约相同的 Cairo 代码和编译器识别解析
• 支持创建本地和全局规则
• 导出 Cairo 文件的解析 AST
• 将静态分析结果导出为 SARIF 格式。

基本用法

分析当前目录中的 Cairo 项目并导出 SARIF 结果到文件

amarna . -o out.sarif

分析单个文件 file.cairo 并导出 SARIF 结果到文件

amarna file.cairo -o out.sarif

分析单个文件 file.cairo 并打印结果摘要

amarna file.cairo -s

集成

• 对于 GitHub action 集成，请使用 amarna-action。

当前支持的规则

用法

分析当前目录中的 Cairo 项目并将其结果导出到文件

amarna . -o out.sarif

分析单个文件 deleverage.cairo 并将结果导出到文件

amarna deleverage.cairo -o deleverage.sarif

分析单个文件 code.cairo 并打印结果摘要

amarna code.cairo -s

解析 Cairo 文件并将恢复的 AST 输出为 png

amarna file.cairo -png

使用未使用导入规则分析 Cairo 文件

amarna file.cairo --rules=unused-imports

使用所有规则（除算术加法规则外）分析 Cairo 文件

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

完整的帮助菜单是

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 文件格式

SARIF 文件格式是静态分析工具的标准格式，可以在 vscode 中通过 官方扩展 查看。

安装

pip install amarna

规则如何工作

静态分析规则可以是

• 本地规则，独立分析每个文件。
• 收集器规则，独立分析每个文件并收集用于后续处理规则的数据。
• 后处理规则，在分析所有文件之后运行，可以使用收集器规则收集的数据。

这些示例包括

• 本地规则：在一个文件中查找所有算术运算
• 收集器规则：收集所有声明的函数和调用的函数
• 后处理规则：使用收集的数据查找未使用的函数，即已声明但从未调用的函数。

规则允许列表、拒绝列表和内联注释

规则名称

使用以下命令获取当前实现规则的名称

 amarna --show-rules

规则允许列表

使用定义的规则集运行 amarna

 amarna --rules=rule1,rule2 .

以下命令将仅运行 unused-imports 规则并打印摘要结果

 amarna --rules=unused-imports . -s

规则拒绝列表

使用除定义的规则集之外的所有规则运行 amarna

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

内联规则禁用注释

您可以将 Cairo 文件的第一行更改为禁用该文件上的特定规则集。例如，向 file.cairo 的第一行添加以下行

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

然后使用运行 amarna

amarna directory/ --disable-inline -s

将不会向 file.cairo 文件报告任何算术规则。