Siderophile finds the "most unsafe" functions in your Rust codebase, so you can fuzz them or refactor them out entirely.
It checks the callgraph of each function in the codebase, estimates how many
unsafe
expressions are called in an evalutation of that function, then
produces a list sorted by this value. Here's what Siderophile's output format
looks like:
Badness Function
092 <myProject::myThing as my_project::myThing>::tempt_fate
064 <myProject::myOtherThing::whatever as my_project::myThing>::defy_death
[...]
"Badness" of a function is simply an approximation of how many unsafe
expressions are evaluated during an evaluation of that function. For instance,
marking unsafe functions with a *
, suppose your function f
calls functions
g*
and h
. Furthermore, h
calls i*
. Then the badness of f
is 2.
Functions with high badness have a lot of opportunities to be memory unsafe.
Siderophile is available via crates.io,
and can be installed with cargo
:
cargo install siderophile
When you run that step, you may see an error from the llvm-sys
crate:
error: No suitable version of LLVM was found system-wide or pointed
to by LLVM_SYS_170_PREFIX.
Consider using `llvmenv` to compile an appropriate copy of LLVM, and
refer to the llvm-sys documentation for more information.
llvm-sys: https://crates.io/crates/llvm-sys
llvmenv: https://crates.io/crates/llvmenv
--> /Users/william/.cargo/registry/src/gh.neting.cc-1ecc6299db9ec823/llvm-sys-170.0.2/src/lib.rs:487:1
|
487 | / std::compile_error!(concat!(
488 | | "No suitable version of LLVM was found system-wide or pointed
489 | | to by LLVM_SYS_",
490 | | env!("CARGO_PKG_VERSION_MAJOR"),
... |
497 | | llvmenv: https://crates.io/crates/llvmenv"
498 | | ));
| |__^
error: could not compile `llvm-sys` due to previous error
This indicates that the build was unable to automatically find a copy of LLVM to link against.
You can fix it by setting the LLVM_SYS_170_PREFIX
. For example, for macOS with LLVM via
Homebrew, you might do:
LLVM_SYS_170_PREFIX=$(brew --prefix)/opt/llvm@17/ cargo install siderophile
You may run into other linker errors as well, e.g.:
= note: ld: library not found for -lzstd
clang: error: linker command failed with exit code 1 (use -v to see invocation)
You can fix this by setting the LIBRARY_PATH
. For example, for macOS with
Homebrew:
LIBRARY_PATH=$(brew --prefix)/lib cargo install siderophile
To tie it all together:
LIBRARY_PATH=$(brew --prefix)/lib \
LLVM_SYS_170_PREFIX=$(brew --prefix)/opt/llvm@17/
cargo install siderophile
Alternatively, if you'd like to build from source:
git clone https://github.com/trailofbits/siderophile && cd siderophile
# TIP: include --release for a release build
cargo build
# optionally: install the built binary to cargo's default bin path
cargo install --path .
You may need the same LLVM_SYS_170_PATH
and LIBRARY_PATH
overrides
mentioned above.
Make sure that you followed the above steps, then do the following:
-
cd
to the root directory of the crate you want to analyze -
Run
siderophile --crate-name CRATENAME
, whereCRATENAME
is the name of the crate you want to analyze
Functions are written to stdout
, ordered by their badness.
Siderophile extends cargo-geiger
, whose goal is to find unsafety at the crate-level.
First, the callgraph is created by having cargo
output the crate's bitcode,
then parsing it to produce a callgraph and demangle the names into things that
we can match with the source code.
Next, Siderophile finds all the sources of the current crate, finds every
Rust file in the sources, and parses each file individually using the syn
crate. Each file is recursively combed through for unsafety occurring in
functions, trait declarations, trait implementations, and submodules.
Siderophile will output the path of these objects, along with an indication
of what type of syntactic block they were found in. The list received from this
step contains every unsafe block in every dependency of the crate, regardless
of whether it's used. To narrow this down, Siderophile needs to compare its
list to nodes in the callgraph of the crate.
Using the callgraph produced in the first step, Siderophile checks which elements from the
output are actually executed from the crate in question. This
step (implemented in src/callgraph_matching
) is not guaranteed to find
everything, but it has shown good results against manual search. It is also not
immune to false positives, although none have been found yet. The labels of the
nodes that are found to be unsafe are used as input for the final step.
The final step is to trace these unsafe nodes in the callgraph. For each node in the list, Siderophile will find every upstream node in the callgraph, and increment their badness by one, thus indicating that they use unsafety at some point in their execution. At the end of this process, all the nodes with nonzero badness are printed out, sorted in descending order by badness.
Siderophile is not guaranteed to catch all the unsafety in a crate's deps.
Since things are only tagged at a source-level, Siderophile does not have the ability to inspect macros or resolve dynamically dispatched methods. Accordingly, this tool should not be used to "prove" that a crate contains no unsafety.
To get debugging output from siderophile
, set the RUST_LOG
environment
variable to siderophile=XXX
where XXX
can be info
, debug
, or trace
.
To cargo-geiger
and
rust-praezi
for current best practices.
This project is mostly due to their work.
Siderophile is licensed and distributed under the AGPLv3 license.
Contact us if you're looking for an exception to the terms.