🦀 Rust Panic Analyzer 🔎

概述

Rust Panic Analyzer是一款旨在扫描您的Rust crate或工作区的审计工具。其主要功能是识别代码库中的潜在panic点，帮助您开发尽可能接近“panic-free”的二进制文件和库。

它是如何工作的？

关键识别模式

该工具会在Rust代码中搜索几种与panic点相关的关键模式。这些包括

• panic!：直接调用panic!宏，导致程序立即终止并提供错误信息。
• unwrap：调用.unwrap()方法，通常用于Option或Result类型，如果值为None或Err将引发panic。
• expect：类似于unwrap，但允许指定自定义错误信息。
• Array Indexing：直接对数组进行索引（例如，arr[index]），没有进行边界检查，如果索引超出范围，则可能引发panic。（一个更安全的索引方法是.get()）
• unreachable!：指示永远不会到达的代码；如果执行，则引发panic。
• todo!和unimplemented!：指示不完整或未实现的代码的宏，如果到达，则引发panic。

安装

要开始使用它，您首先需要安装。

cargo install panic-analyzer

本地使用

安装后，您可以在您的crate或整个工作区上运行分析器。使用以下命令

cargo panic-analyzer > audit.md

将审计结果记录到终端

cargo panic-analyzer

如果您希望在分析期间排除工作区中的特定crate，请设置`IGNORED_CRATES`环境变量。传递您想要排除的crate的名称，用逗号分隔

IGNORED_CRATES=tests,benches cargo panic-analyzer > audit.md

您也可以用以下方式对文件进行相同的操作

IGNORED_FILES=./src/tests/something.rs,./src/tests/else.rs cargo panic-analyzer > audit.md

潜在的恐慌并不一定不好，有时错误是无法恢复的，我们必须恐慌。如果您有意恐慌，可以在可能引发恐慌的代码行之前添加注释，如下所示

pub fn shutdown_server() {
  // @expected: we need this
  panic!("Exited process!")
}

语法如下： // @expected: description/reason。

这不会被视为潜在的恐慌点，而是一个预期在最后部分的恐慌。

通过GitHub Actions审核拉取请求结果

您还可以将其与您的CI连接，以便将结果作为评论发布到您的PR中，这可能非常有帮助！

name: ci

on:
  push:
    branches:
      - main
  pull_request:
jobs:
  panic-free-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions-rust-lang/setup-rust-toolchain@v1

      - name: install panic free analyzer
        run: |
            cargo install panic-analyzer

      - name: run panic free analyzer
        run: |
            cargo panic-analyzer > ./audit.md
        env:
          IGNORED_CRATES: e2e_tests,benches

      - name: comment on pull request
        uses: thollander/actions-comment-pull-request@v2
        with:
          filePath: ./audit.md
          comment_tag: rust-code-audit

⚠️ 限制

• 目前，它只搜索您开发的crates，而不是您的crates的依赖项。
• 分析使用正则表达式而不是AST进行，以便简化，因此您可能会遇到无法识别的潜在恐慌点，如果这些行以正则表达式模式无法捕获的方式包装。

审计结果示例 👇

以下是由Rust Panic Free Analyzer生成的审计结果示例

🚨 Rust Panic Audit: 检测到82个潜在恐慌点 🚨

Crates: vrl

📊 总使用次数：37

• 🔎 expect 使用次数：1
• 🎁 unwrap 使用次数：32
• 🚨 panic 使用次数：1
• 🔢 array_index 使用次数：3

Crates: jwt_auth

📊 总使用次数：31

• 🎁 unwrap 使用次数：29
• 🔢 array_index 使用次数：2

Crates: config

📊 总使用次数：14

• 🚨 panic 使用次数：3
• 🔎 expect 使用次数：3
• 🎁 unwrap 使用次数：8

📌 预期注释

Crates: common

📊 总预期使用次数：1

• 原因： "我们需要这个"
• 代码： panic!("进程退出！")
• 位置： ./libs/common/src/lib.rs:18