Skip to content

Latest commit

 

History

History
109 lines (77 loc) · 4.14 KB

README.md

File metadata and controls

109 lines (77 loc) · 4.14 KB
Raw

Cackle / cargo acl

A code ACL checker for Rust.

Cackle is a tool to analyse the transitive dependencies of your crate to see what kinds of APIs each crate uses.

The idea is look for crates that are using APIs that you don't think they should be using. For example a crate that from its description should just be doing some data processing, but is actually using network APIs.

Installation

Currently Cackle only works on Linux. See PORTING.md for more details.

cargo install --locked cargo-acl

Or if you'd like to install from git:

cargo install --locked --git https://github.com/cackle-rs/cackle.git cargo-acl

Installing bubblewrap is recommended as it allows build scripts (build.rs), tests and rustc to be run inside a sandbox.

On systems with apt, this can be done by running:

sudo apt install bubblewrap

Usage

From the root of your project (the directory containing Cargo.toml), run:

cargo acl

This will interactively guide you through creating an initial cackle.toml. Some manual editing of your cackle.toml is recommended. In particular, you should look through your dependency tree and think about which crates export APIs that you'd like to restrict. e.g. if you're using a crate that provides network APIs, you should declare this in your config. See CONFIG.md for more details.

Running from CI

Cackle can be run from GitHub actions. See the instructions in the cackle-action repository.

Features

  • Checks what APIs are used by each crate in your dependency tree.
  • Ignores dead code, so if a crate uses an API, but in code that isn't called in your binary, then it doesn't count.
  • Restrict which crates are allowed to use unsafe.
  • A terminal UI that shows problems as they're found.
    • Preview the source where the API usage or unsafe was detected.
    • For API usages, show a backtrace of how that code is reachable.
    • Select from several edits that can be applied to your config file to allow the usage.
  • Can run build scripts, tests in a sandbox to restrict network and filesystem access.
  • The sandbox for each build script is configured separately, so if one build script needs extra access you can grant it to just that build script.
  • Can run rustc in a sandbox, thus sandboxing all proc macros. This however is currently not granular, so if one proc macro needs more access it needs to be granted to all. Fortunately proc macros that need network access are relatively rare.

Limitations and precautions

  • A proc macro might detect that it's being run under Cackle and emit different code.
  • Even without proc macros, a crate may only use problematic APIs only in certain configurations that don't match the configuration used when you run Cackle.
  • This tool is intended to supplement and aid manual review of 3rd party code, not replace it.
  • Your configuration might miss defining an API provided by a crate as falling into a certain category that you care about.
  • There are undoubtedly countless ways that a determined person could circumvent detection that they're using some APIs. With time we may try to prevent such circumventions, but for now, you should definitely assume that circumvention is possible.

With all these limitations, what's the point? The goal really is to just raise the bar for what's required to sneak problematic code unnoticed into some package. Use of Cackle should not replace any manual code reviews of your dependencies that you would otherwise have done.

How it works

See HOW_IT_WORKS.md.

FAQ

FAQ

Contributing

Contributions are very welcome. If you'd like to get involved, please reach out either by filing an issue or emailing David Lattimore (email address is in the commit log).

License

This software is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE for details.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.