{"id":20009798,"url":"https://github.com/plsyssec/cargo-scan","last_synced_at":"2025-05-04T19:36:00.327Z","repository":{"id":63441114,"uuid":"539638571","full_name":"PLSysSec/cargo-scan","owner":"PLSysSec","description":"A tool for auditing Rust crates","archived":false,"fork":false,"pushed_at":"2025-03-29T01:06:51.000Z","size":42955,"stargazers_count":17,"open_issues_count":18,"forks_count":4,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-04T05:35:26.996Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PLSysSec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDITING.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-21T18:48:04.000Z","updated_at":"2025-04-08T06:05:54.000Z","dependencies_parsed_at":"2023-10-24T23:28:10.951Z","dependency_job_id":"b3d507b8-2bc3-49ae-9ba0-53b33256957c","html_url":"https://github.com/PLSysSec/cargo-scan","commit_stats":{"total_commits":586,"total_committers":5,"mean_commits":117.2,"dds":"0.16382252559726962","last_synced_commit":"1ffa10115849802d7250b9107181bb41b459349e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fcargo-scan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fcargo-scan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fcargo-scan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fcargo-scan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PLSysSec","download_url":"https://codeload.github.com/PLSysSec/cargo-scan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252390732,"owners_count":21740374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T07:17:06.673Z","updated_at":"2025-05-04T19:35:55.315Z","avatar_url":"https://github.com/PLSysSec.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cargo Scan\n\nCargo Scan is a tool for auditing Rust crates.\n\n**⚠️ Cargo Scan is under active development. Some interfaces may be subject to change.**\n\n## Installation\n\n1. Clone this repository.\n2. Run `rustup update` to ensure you have the latest version of Rust (or install it via the [official website]((https://www.rust-lang.org/tools/install))).\n3. Run `cargo build`.\n\nKnown working builds:\n\n- August 22, 2024 on Mac OS (Sonoma) using Rust 1.80.1.\n\n- August 22, 2024 on Linux (Arch Linux) using Rust 1.80.1.\n\n## Quick-start\n\nTo use Cargo Scan you first need a Rust crate somewhere on your system (any Rust code with a `Cargo.toml` file).\nThere are three ways to run Cargo Scan:\n\n1. Using the basic command-line interface (easiest: `cargo run --bin scan \u003cpath to crate\u003e`);\n\n2. Using interactive auditing mode (`cargo run --bin audit \u003cpath to crate\u003e -i`); or\n\n3. Using the VSCode extension.\n\nInstructions for these are included below.\n\n## Method 1: Using the basic command-line interface\n\nTo scan a crate, you run the binary (from this repository), and provide it a path to the crate:\n```\ncargo run --bin scan \u003cpath to crate\u003e\n```\n\nThis is the simplest available output, which is returned in CSV format as a list of *side effects,* one per line.\nThe beginning of the line gives the crate name, the function body and callee that contains the effect, and the effect type or pattern that it matches.\nThe last four items on each line give the directory, file, line, and column where the effect occurs.\nExample output is as follows:\n```\n$ cargo run --bin scan data/packages/rand\n    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s\n     Running `target/debug/scan data/packages/rand`\ncrate, fn_decl, callee, effect, dir, file, line, col\nrand, rand::distributions::other::\u003cStandard as Distribution\u003cchar\u003e\u003e::sample, core::char::from_u32_unchecked, [UnsafeCall], data/packages/rand/src/distributions, other.rs, 94, 17\nrand, rand::distributions::other::\u003cAlphanumeric as DistString\u003e::append_string, alloc::string::String::as_mut_vec, [UnsafeCall], data/packages/rand/src/distributions, other.rs, 136, 27\n...\nrand, rand::distributions::uniform::\u003cUniform\u003cchar\u003e as super::DistString\u003e::append_string, core::char::methods::len_utf8, [FnPtrCreation], data/packages/rand/src/distributions, uniform.rs, 860, 50\n\nnum_effects, total, loc_lb, loc_ub, macros, loc_lb, loc_ub, conditional_code, loc_lb, loc_ub, skipped_calls, loc_lb, loc_ub, skipped_fn_ptrs, loc_lb, loc_ub, skipped_other, loc_lb, loc_ub, unsafe_trait, loc_lb, loc_ub, unsafe_impl, loc_lb, loc_ub, pub_fns, pub_fns_with_effects, pub_total_effects, audited_fns, audited_loc\n12, 25, 8708, 8708, 127, 1117, 1185, 21, 2410, 2410, 0, 0, 0, 0, 0, 0, 25, 3, 25, 0, 0, 0, 0, 0, 0, 53, 23, 52, 58, 540\n```\n\nIf you don't want the last two lines (totals at the bottom), suppress them with the `-s` option.\n\nFor additional usage options, run `help`:\n```\ncargo run --bin scan -- --help\n```\n\n### What's a side effect?\n\nSee [Wikipedia](https://en.wikipedia.org/wiki/Side_effect_(computer_science)). Basically, it represents some behavior of a function that might or might not be dangerous (e.g., operating system calls, memory unsafety, or filesystem/network access). These are behaviors that you may want to look into further when auditing a crate.\n\n### If you don't have a crate on your system\n\nYou can run one of our provided example crates in `data/test-packages`:\n```\ncargo run --bin scan data/test-packages/permissions-ex\n```\n\n## Method 2: Interactive mode\n\nInteractive mode is a variant of the command-line interface that allows you to mark\naudits as safe or unsafe as you go through them.\nInteractive mode works by maintaining an *audit file* of the effects you have marked so far,\nwhich are maintained dynamically as you progress through an audit.\n```\ncargo run --bin audit \u003cpath to crate\u003e -i\n```\n\nAt each effect, the audit will ask you whether you want to mark it safe or unsafe,\nskip it or provide more context, or mark it caller-checked, which means that the caller\nof the function is responsible for ensuring safety.\nThe interactive mode looks like this:\n```\nhelp[Audit location]:\n   ┌─ data/packages/rand/src/distributions/other.rs:94:1\n   │\n79 │   ╭       fn sample\u003cR: Rng + ?Sized\u003e(\u0026self, rng: \u0026mut R) -\u003e char {\n80 │   │           // A valid `char` is either in the interval `[0, 0xD800)` or\n   │   ╰──'\n   ·   │\n90 │     ╭         let mut n = range.sample(rng);\n91 │     │         if n \u003c= 0xDFFF {\n92 │     │             n -= GAP_SIZE;\n93 │     │         }\n94 │ ╭   │         unsafe { char::from_u32_unchecked(n) }\n95 │ │   │     }\n   │ ╰───│^ unsafe call: core::char::from_u32_unchecked\n96 │     │ }\n   │     ╰'\n\n? Select how to mark this effect:\n  (s)afe, (u)nsafe, (c)aller checked, (e)xpand context, ask me (l)ater, e(x)it tool\n```\n\nIf the command is run a second time, it continues the existing audit.\nTo review the audit, use `-r`.\n\nFor additional usage options, run `help`:\n```\ncargo run --bin scan -- --help\n```\n\n## Method 3: Using the VSCode extension\n\n### Installing the extension in VSCode\n\n1. Build the extension by running `make` in the `editor-plugin` directory. This will produce a `.vsix` file in that location.\n2. Launch VSCode and install the extension from the `.vsix` file:\n    - Press `Ctrl + Shift + P` (Windows/Linux) or `Cmd + Shift + P` (macOS) to open the Command Palette.\n    - Type \"Extensions: Install from VSIX...\" and select it.\n    - Navigate to the folder where the .vsix file is located and open it.\n\nThe extension is automatically activated when a Rust package is detected in the workspace.\n\n### Performing an audit in VSCode\n\nThere are two types of audits you can perform with Cargo Scan in VSCode\n1. **Single Crate Audit** that scans only the currently open package for effects.\n- To run a single crate audit type `cargo-scan: Audit Crate` in the Command Palette. \n2. **Chain Audit** that performs a full audit and also scans the transitive dependencies of the open package.\n- To run a chain audit, create the chain by typing `cargo-scan: Create Chain` in the Command Palette and then perform the actual audit by running the command `cargo-scan: Audit Chain`.\n\nThe set of effects that Cargo Scan identifies are shown in the Effects view of the Explorer side bar.\n\n## Other usage\n\n### Running the unit tests\n\n- Run `cargo test` to run Rust unit tests\n\n- Run `make test` to re-run the tool on all our test packages, whose results are in `data/results` and placed under version control to check for any regressions.\n\n### Running an experiment\n\nYou can also run `./scripts/scan.py -h` to see options for running an experiment; this is useful for running a scan on a large list of crates, e.g. the top 100 crates on crates.io or your own provided list. Alternatively, see `Makefile` for some pre-defined experiments to run, such as `make top10`.\n\n### Running in tandem with other tools\n\nCargo Scan can also be used in tandem with other Rust supply chain auditing tools, such as [cargo vet](https://mozilla.github.io/cargo-vet/).\nWe are interested in exploring other use cases for integration; if you think Cargo Scan would be useful for your project, let us know!\n\n## Additional information\n\n### Repository structure\n\nMost of the source code of Cargo Scan can be found in `src/`, with miscellaneous data and scripts in `data/` and `scripts/`.\nThe VS Code extension is developed in `lang_server` and `editor-plugin`.\n\n### Current maintainers\n\nCargo Scan is open source.\nIt is currently maintained by [Caleb Stanford](https://web.cs.ucdavis.edu/~cdstanford/) and Lydia Zoghbi.\nIt includes past contributions from other authors at UC Davis PL and UC San Diego PLSysSec.\nFor copyright information, see the `LICENSE`.\n\n### Issues\n\nWe welcome bug reports, suggestions, and pull requests! Please raise an issue or send us an email about your use case.\n\n## Citing this repository\n\nIf you want to cite this repository, please consider citing our technical report.\nThe current draft (in submission) is available below:\n\n- *Auditing Rust Crates Effectively.* Lydia Zoghbi, David Thien, Ranjit Jhala, Deian Stefan, and Caleb Stanford. Preprint (2024). [Draft Link](https://web.cs.ucdavis.edu/~cdstanford/doc/2024/CargoScan-draft.pdf)\n\nYou may also cite the repository directly:\n\n- Cargo Scan: a tool for auditing Rust crates. Lydia Zoghbi, David Thien, Ranjit Jhala, Deian Stefan, and Caleb Stanford. GitHub repository (2024). [GitHub Link](https://github.com/PLSysSec/cargo-scan)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Fcargo-scan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplsyssec%2Fcargo-scan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Fcargo-scan/lists"}