Skip to content

Latest commit

 

History

History
116 lines (85 loc) · 5.76 KB

README.md

File metadata and controls

116 lines (85 loc) · 5.76 KB

Cargo-Sherlock 🕵️

Cargo-Sherlock (alternative name RHS for Rust Sherlock Holmes) is a Python-based tool designed to enhance the security of Rust projects by leveraging different metadata information about Rust crates. It is an automated reasoning tool that attempts to determine the safety of Rust crates by modeling trust.

⚠️ Cargo Sherlock is under active development. Some features may not work on all crates!

Installation

  1. Clone this repository and the cargo-scan submodule.
git clone --recurse-submodules https://github.com/DavisPL/cargo-sherlock.git
  1. Run rustup update to ensure you have the latest version of Rust (or install it via the official website).
rustup update
  1. Run make to create a Python virtual environment, install all Python dependencies, activate the virtual environment, and build cargo-scan.
make

  1. Generate a GitHub personal access token. Go to the token page and select Generate new token (classic). Then, name your token, select an expiration date, and grant the token at least the public_repo scope by checking the box. Finally, create and copy your token, pasting it into the file helpers/token.txt.

  2. You can activate the python virtual environment by running:

source .venv/bin/activate

Usage

To run the tool, run the Python interpreter on sherlock.py, supplying the crate name and version(optional) you would like to analyze. Additionally, you can use various flags to control its behaviour. The tool supports two modes log and trust. You will have to specify the mode while using it.

python3 sherlock.py trust <crate_name>

The above command will run the tool in trust mode for specified crate. Since no version is provided, it will use the latest version by default. For log mode, you can run:

python3 sherlock.py log <crate_name>

Here is an example output:

❯ python3 sherlock.py trust abomonation
Latest version of abomonation is 0.7.3.
Solving for required assumptions to trust abomonation-0.7.3...
This crate has been flagged by RustSec.
This crate has not been audited by any organization.
Trust Cost for abomonation-0.7.3 (lower cost is better): 97 cost
Assumptions Made:
abomonation-0.7.3 has many downloads: 37 cost
abomonation-0.7.3 having many downloads implies it is safe: 10 cost
abomonation-0.7.3 has all safe dependencies: 0 cost
abomonation-0.7.3 appearing in RustSec implies it is less safe (score penalty): 50 cost

Basic Usage

To analyze a specific crate and version:

python3 sherlock.py <crate_name> [version]

Replace <crate_name> with the actual crate name you want to analyze. If you omit the [version], the tool will fetch and use the latest version of the crate by default. By default, this will run the logger.py script to log information about the specified crate, printing the logging information to the screen. This information is also stored at logs/exp/<crate_name>-.csv

⚠️ The tool is under active development. The documentation below this is outdated.

Available Flags

  • -a or --assumptions: Runs solver.py to perform a detailed analysis of the crate. It prints a trust score representing how trustworthy the crate is and the assumptions made to prove the crate was safe.

    Note: This flag reasons about all the dependencies in the dependency tree of the crate, which may take a very long time for crates with large dependency trees. This flag is also still a work-in-progress; it may not work for all crates.

python3 sherlock.py <crate_name> [version] -a

  • -u or --update: Updates the information needed for analysis by running three scripts sequentially:

    1. scrapper.py to collect information from the RustSec website.
    2. getCrates.py to retrieve all crates and their side effects.
    3. aggregator.py to compile side effects for all reported vulnerable functions.

    This flag ensures that the latest data is used for analysis.

    Note: This flag updates information by scraping RustSec and retrieving side effects using cargo-scan for all RustSec crates. Depending upon the internet connection and processing power, it can take a fair amount of time.

  • -o or --output: Specifies an output file path to save the crate information. When used, the tool will write the logging information to the specified file. If you do not provide this flag, the information is stored at logs/exp/<crate_name>-.csv.

Note: This flag currently does not work in combination with the -a (assumptions) flag.

python3 sherlock.py <crate_name> [version] -o <output_file_path>
  • -h: Displays a help message.

Outputs

Depending on the flags used, Cargo Sherlock will output different information:

  • Default Output: Logs the crate information using logger.py, printing the results to the terminal.
  • With -a Flag: Provides detailed analysis results from solver.py.
  • With -u Flag: Updates the data from external sources, followed by either solver.py or logger.py execution based on additional flags.

Additional Information

Credits

Cargo Sherlock is an open source project from Professor Caleb Stanford's Davis PL research group. For copyright information, see the LICENSE.

The following members of the Davis PL research group have made contributions to this project (names in alphabetical order):

  • Anirudh Basu
  • Audrey Gobaco
  • Muhammad Hassnain
  • Ethan Ng

A portion of this project was funded by the NSF.

Issues

If you encounter an issue while using Cargo Sherlock, we would love to hear about it! Please raise a GitHub issue with any bugs you find, features you would like, or pull requests you have.