an audit tool to scan your crate or workspace searching for potential panic points in your codebase
MIT License
Rust Panic Analyzer is an audit tool designed to scan your Rust crate or workspace. Its primary function is to identify potential panic points in your codebase, leading you in developing binaries and libraries that are as close to "Panic Free" as possible.
The tool searches for usage of several key patterns in Rust code that are often associated with panic points. These include:
panic!
: Direct calls to the panic!
macro, which causes the program to terminate immediately and provide an error message.unwrap
: Calls to the .unwrap()
method, often used on Option
or Result
types, which will cause a panic if the value is None
or Err
.expect
: Similar to unwrap
, but allows specifying a custom error message.Array Indexing
: Direct indexing into arrays (e.g., arr[index]) without bounds checking, which can panic if the index is out of bounds. (A safer indexing method is .get()
)unreachable!
: Indicates code that should never be reached; panics if executed.todo!
and unimplemented!
: Macros indicating incomplete or unimplemented code, which will panic if reached.To start using it, you need to install it first.
cargo install panic-analyzer
After installation, you can run the analyzer on your crate or entire workspace. Use the following command:
cargo panic-analyzer > audit.md
Logging audit result to the terminal
cargo panic-analyzer
If you wish to exclude specific crates from your workspace during the analysis, set the `IGNORED_CRATES`` environment variable. Pass the names of the crates you want to exclude, separated by commas:
IGNORED_CRATES=tests,benches cargo panic-analyzer > audit.md
You can also do the same with files as the following:
IGNORED_FILES=./src/tests/something.rs,./src/tests/else.rs cargo panic-analyzer > audit.md
A potential panic is not necessarily bad, sometimes errors are unrecoverable, and we have to panic. If your panic is intentional, you can add a comment before the line that has the potential panicing code like this:
pub fn shutdown_server() {
// @expected: we need this
panic!("Exited process!")
}
The syntax is as the following: // @expected: description/reason
.
This won't be counted as a potential panic point, but rather an expected panic in a section at the end.
You can also hook it up with your CI to post the results on your PRs as a comment which can be very helpful!
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
Below is an example of an audit result generated by the Rust Panic Free Analyzer:
vrl
π Total Usages: 37
expect
usages: 1unwrap
usages: 32panic
usages: 1array_index
usages: 3jwt_auth
π Total Usages: 31
unwrap
usages: 29array_index
usages: 2config
π Total Usages: 14
panic
usages: 3expect
usages: 3unwrap
usages: 8common
π Total Expected Usages: 1
panic!("Exited process!")
./libs/common/src/lib.rs:18