cargo-deny

https://embarkstudios.github.io/cargo-deny/
Admin
cargo-deny is a cargo plugin that lints your project's dependency graph to ensure all dependencies...
Tokens:27,827
Snippets:303
Trust Score:8.3
Update:6 days ago
Show doc for...
Tokens:
Raw
### Install, initialize, and run cargo-deny checks

Source: https://embarkstudios.github.io/cargo-deny/index.html

Installs cargo-deny, initializes your project with a default configuration, then runs all of the checks against your project.

```bash
cargo install --locked cargo-deny && cargo deny init && cargo deny check
```

--------------------------------

### Full [bans] configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Complete example of the [bans] section showing all available configuration keys: multiple-versions, wildcards, allow/deny lists, skip-tree, workspace-dependencies, skip, features, build, and std-replacements. Use as a reference for configuring cargo deny check bans.

```toml
[bans]
multiple-versions = "deny"
wildcards = "deny"
allow-wildcard-paths = true
highlight = "simplest-path"
workspace-default-features = "warn"
external-default-features = "deny"
allow = [
    { name = "all-versionsa" },
    "version-rangea:<0.1.1",
    "specific-versionb@0.1.2",
    "any-version",
]
deny = [
    "specific-versiond@0.1.9",
    { name = "all-versionsd", wrappers = [
        "specific-versiona",
    ], reason = "we want to get rid of this crate but there is still one user of it" },
]
skip-tree = [{ name = "blah", depth = 20 }]

[bans.workspace-dependencies]
duplicates = "allow"
include-path-dependencies = false
unused = "allow"

[[bans.skip]]
name = "rand"
version = "=0.6.5"

[[bans.features]]
name = "featured-krate"
version = "1.0"
deny = ["bad-feature"]
allow = ["good-feature"]
exact = true
reason = "`bad-feature` is bad"

[bans.build]
allow-build-scripts = [{ name = "all-versionsa" }]
executables = "warn"
interpreted = "deny"
script-extensions = ["cs"]
enable-builtin-globs = true
include-dependencies = true
include-workspace = true
include-archives = true

[[bans.build.bypass]]
name = "allversionsa"
build-script = "5392f0e58ad06e089462d93304dfe82337acbbefb87a0749a7dc2ed32af04af7"
required-features = ["feature-used-at-build-time"]
allow-globs = ["scripts/*.cs"]
allow = [
    { path = "bin/x86_64-linux", checksum = "5392f0e58ad06e089462d93304dfe82337acbbefb87a0749a7dc2ed32af04af7" },
]

[bans.std-replacements]
scope = "workspace"
level = "deny"
rust-version = "1.0"
```

--------------------------------

### Workspace dependencies configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Example of the [bans.workspace-dependencies] section with duplicates, include-path-dependencies, and unused options. This example uses single quotes for string values, unlike the full example which uses double quotes.

```toml
[bans.workspace-dependencies]
duplicates = 'deny'
include-path-dependencies = true
unused = 'deny'
```

--------------------------------

### Example `[licenses]` configuration

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Shows a complete `[licenses]` section with `unused-allowed-license`, `confidence-threshold`, `allow`, `private`, `exceptions`, and `clarify` fields.

```toml
[licenses]
unused-allowed-license = "warn"
confidence-threshold = 0.95
allow = [
    "EUPL-1.2",
    "Apache-2.0 WITH LLVM-exception",
]

[licenses.private]
ignore = true
registries = ["sekrets"]

[[licenses.exceptions]]
allow = ["Zlib"]
name = "adler32"
version = "0.1.1"

[[licenses.clarify]]
name = "ring"
expression = "MIT AND ISC AND OpenSSL"
license-files = [
    { path = "LICENSE", hash = 0xbd0eed23 }
]
```

--------------------------------

### allow-registry default example

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Shows the default allow-registry list containing the crates.io registry.

```toml
[sources]
allow-registry = [
    "https://github.com/rust-lang/crates.io-index",
]

```

--------------------------------

### Example deny.toml configuration

Source: https://embarkstudios.github.io/cargo-deny/checks/cfg.html

A complete example of a deny.toml configuration file. It sets target platforms, enables all features, denies multiple versions and wildcards, bans specific crates, skips certain crates, sets a license confidence threshold, and allows specific licenses.

```toml
[graph]
# cargo-deny is really only ever intended to run on the "normal" tier-1 targets
targets = [
    "x86_64-unknown-linux-gnu",
    "aarch64-unknown-linux-gnu",
    "x86_64-unknown-linux-musl",
    "aarch64-apple-darwin",
    "x86_64-apple-darwin",
    "x86_64-pc-windows-msvc",
]
all-features = true

[advisories]
unmaintained = "all"
unsound = "all"
ignore = [
]

[bans]
multiple-versions = "deny"
wildcards = 'deny'
deny = [
    { crate = "git2", use-instead = "git cli" },
    { crate = "gix", use-instead = "git cli" },
    { crate = "openssl", use-instead = "rustls" },
    { crate = "openssl-sys", use-instead = "rustls" },
    "libssh2-sys",
    { crate = "cmake", use-instead = "cc" },
    { crate = "windows", reason = "bloated and unnecessary", use-instead = "ideally inline bindings, practically, windows-sys" },
]
skip = [
    { crate = "getrandom@0.2.17", reason = "ring uses this old version" },
]
skip-tree = [
    { crate = "windows-sys", reason = "a foundational crate for many that bumps far too frequently to ever have a shared version" },
]

[bans.std-replacements]
scope = "workspace"

[sources]
unknown-registry = "deny"
unknown-git = "deny"

[licenses]
# We want really high confidence when inferring licenses from text
confidence-threshold = 0.93
allow = [
    "Apache-2.0",
    "Apache-2.0 WITH LLVM-exception",
    "BSD-3-Clause",
    "MIT",
    "ISC",
    "Unicode-3.0",
    "Zlib",
]
exceptions = [
]

```

--------------------------------

### Install cargo-deny with pacman

Source: https://embarkstudios.github.io/cargo-deny/cli/index.html

Install cargo-deny from the Arch Linux extra repository using pacman.

```bash
pacman -S cargo-deny
```

--------------------------------

### [graph] configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/cfg.html

Example TOML configuration for the [graph] table, showing targets, exclude, all-features, no-default-features, features, and exclude-dev options.

```toml
[graph]
targets = [
    "x86_64-unknown-linux-gnu",
    { triple = "aarch64-apple-darwin" },
    { triple = "x86_64-pc-windows-msvc", features = ["sse2"] },
]
exclude = ["some-crate@0.1.0"]
all-features = true
no-default-features = false
features = ["some-feature"]
exclude-dev = true

```

--------------------------------

### Complete [sources] configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Shows a full [sources] configuration with all options: unknown-registry, unknown-git, required-git-spec, allow-registry, allow-git, private, unused-allowed-source, and allow-org for GitHub, GitLab, and Bitbucket.

```toml
[sources]
unknown-registry = "allow"
unknown-git = "deny"
required-git-spec = "tag"
allow-registry = [
    "https://sekretz.com/registry/index",
    "sparse+https://fake.sparse.com",
]
allow-git = [
    "https://notgithub.com/orgname/reponame.git",
]
private = [
    "https://internal-host/repos",
]
unused-allowed-source = "warn"
[sources.allow-org]
github = [
    "yourghid",
    "YourOrg",
]
gitlab = [
    "gitlab-org",
]
bitbucket = [
    "atlassian",
]

```

--------------------------------

### Target-specific dependencies example

Source: https://embarkstudios.github.io/cargo-deny/checks/cfg.html

Example Cargo.toml snippet showing target-specific dependencies for Windows and Fuchsia, used to illustrate how cargo-deny filters target-specific dependencies.

```toml
[target.x86_64-pc-windows-msvc.dependencies]
winapi = "0.3.8"

[target.'cfg(target_os = "fuchsia")'.dependencies]
fuchsia-cprng = "0.1.1"

```

--------------------------------

### allow-git example

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Configures an allowed git URL. The URL must match exactly, though .git is stripped if present to match cargo's logic.

```toml
[sources]
allow-git = [
    "https://github.com/EmbarkStudios/cargo-deny",
]

```

--------------------------------

### private example

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Allows any git repo URL that matches the host and begins with the same path, useful for internal/private git hosts.

```toml
[sources]
private = [
    "https://super-duper-sekret",
]

```

--------------------------------

### Install cargo-deny git version

Source: https://embarkstudios.github.io/cargo-deny/cli/index.html

Build and install the latest git version from the repository, containing unreleased bug-fixes and features.

```bash
cargo install --locked --git https://github.com/EmbarkStudios/cargo-deny cargo-deny
```

--------------------------------

### Install cargo-deny from source with Cargo

Source: https://embarkstudios.github.io/cargo-deny/cli/index.html

Compile and install the latest release from Crates.io. Requires Rust and a C toolchain. Add Cargo's bin directory to PATH if needed.

```bash
cargo install --locked cargo-deny
```

--------------------------------

### skip-tree configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Shows how to configure the `skip-tree` field to skip a crate and its transitive dependencies up to a specified depth. The `depth` field is optional and defaults to infinite. Entries can be simple package specs or include a `reason` and `depth`.

```toml
skip-tree = [
    "windows-sys<=0.52", # will skip this crate and _all_ direct and transitive dependencies
    { crate = "windows-sys<=0.52", reason = "several crates use the outdated 0.42 and 0.45 versions" },
    { crate = "windows-sys<=0.52", depth = 3, reason = "several crates use the outdated 0.42 and 0.45 versions" },
]

```

--------------------------------

### skip configuration example

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Shows how to configure the `skip` field in the `bans` section to ignore specific crates during duplicate version detection. Entries can be simple package specs or include a `reason` for documentation. It is recommended to use specific version constraints to avoid warnings when entries no longer match.

```toml
skip = [
    "package-spec",
    { crate = "package-spec", reason = "an old version is used by crate-x, see <PR link> for updating it" },
]

```

--------------------------------

### Configure db-path, db-urls, and ignore

Source: https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html

Example showing how to set the advisory database path and URLs, and how to ignore specific advisories or yanked crates. The ignore field accepts advisory IDs, crate@version strings, or objects with a reason.

```toml
[advisories]
db-path = "~/.cargo/advisory-dbs"
db-urls = ["https://github.com/RustSec/advisory-db"]
ignore = [
    "RUSTSEC-0000-0000",
    "crate@0.1",
    { crate = "yanked", reason = "a new version has not been released" },
]
unmaintained = "workspace"
unused-ignored-advisory = "warn"

```

--------------------------------

### allow-registry empty example

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Disallows all crate registries by setting allow-registry to an empty list and unknown-registry to deny.

```toml
[sources]
unknown-registry = "deny"
allow-registry = []

```

--------------------------------

### Setting the `version` field

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Example of setting the `version` field to 2. This field is no longer used and may emit errors.

```toml
version = 2
```

--------------------------------

### Manual download and run script for cargo-deny

Source: https://embarkstudios.github.io/cargo-deny/cli/index.html

Example bash script to download a specific version of cargo-deny and run checks. Uses version 0.8.5 and the x86_64-unknown-linux-musl target.

```bash
#!/bin/bash
set -eu

NAME="cargo-deny"
VS="0.8.5"
DIR="/tmp/$NAME"

mkdir $DIR

# Download the tarball
curl -L -o $DIR/archive.tar.gz https://github.com/EmbarkStudios/$NAME/releases/download/$VS/$NAME-$VS-x86_64-unknown-linux-musl.tar.gz

# Unpack the tarball into the temp directory
tar -xzvf $DIR/archive.tar.gz --strip-components=1 -C $DIR

# Run cargo deny check in our current directory
$DIR/$NAME -L debug check bans licenses advisories
```

--------------------------------

### Run cargo deny init

Source: https://embarkstudios.github.io/cargo-deny/cli/init.html

Creates a deny.toml configuration file in the current working directory from a template.

```bash
cargo deny init
```

--------------------------------

### Private crate published to a private registry

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Example Cargo.toml for a crate that is published only to a private registry named 'sauce'.

```toml
# Cargo.toml
[package]
name = "sekret"
license = "¯\_(ツ)_/¯"
publish = ["sauce"]
```

--------------------------------

### Private workspace crate with unpublished license

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Example Cargo.toml for a private workspace crate that is not published and has a non-standard license expression.

```toml
# Cargo.toml
[package]
name = "sekret"
license = "¯\_(ツ)_/¯"
publish = false # "private"!
```

--------------------------------

### Allowing licenses with exceptions using `WITH`

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Shows how to allow a license with an exception by appending `WITH <exception-id>` to the license identifier.

```toml
allow = [
    # The Apache license identifier
    "Apache-2.0",
    # The Apache license + LLVM-exception
    "Apache-2.0 WITH LLVM-exception",
]
```

--------------------------------

### Run the licenses check

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/index.html

Command to run the licenses check for the current project.

```bash
cargo deny check licenses
```

--------------------------------

### Example diagnostic message with inclusion graph

Source: https://embarkstudios.github.io/cargo-deny/cli/check.html

Shows the format of a diagnostic message that includes an inverse dependency graph, as appended when a diagnostic pertains to a specific crate.

```text
some diagnostic message

the-crate
├── a-crate
└── b-crate
    └── c-crate
```

--------------------------------

### Run cargo deny init with --config

Source: https://embarkstudios.github.io/cargo-deny/cli/init.html

Uses the root --config option to change the default output path (<cwd>/deny.toml) of the generated configuration file.

```bash
cargo deny --config path/to/config.toml init
```

--------------------------------

### Using custom license identifiers with `LicenseRef-`

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Demonstrates allowing a custom license identifier prefixed with `LicenseRef-` and clarifying a crate with that custom license.

```toml
allow = [
    # The Apache license identifier
    "Apache-2.0",
    # A custom license identifier
    "LicenseRef-Embark-Custom",
]

# Custom license refs can be specified for crates which don't use a license
# in the SPDX list
[[licenses.clarify]]
crate = "a-crate"
expression = "LicenseRef-Embark-Custom"
license-files = [
    { path = "LICENSE", hash = 0x001c7e6c },
]
```

--------------------------------

### Allow Bitbucket organizations as git sources

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Configure `sources.allow-org.bitbucket` with a list of Bitbucket organization names to trust as git sources. The `__` marker is a placeholder for the `[sources]` table header.

```toml
__
[sources.allow-org]
bitbucket = ["YourCoolOrgGoesHere"]

```

--------------------------------

### Basic [advisories] configuration

Source: https://embarkstudios.github.io/cargo-deny/checks/advisories/cfg.html

Shows the default configuration for the [advisories] section. All fields are optional; if the section is omitted, the advisory check runs with these defaults.

```toml
[advisories]
db-urls = ["https://github.com/RustSec/advisory-db"]
db-path = "~/.cargo/advisory-dbs" # Or wherever $CARGO_HOME/advisory-dbs resolves to
yanked = "warn"
unmaintained = "all"
unsound = "workspace"
maximum-db-staleness = "P90D" # Only checked when advisory database fetching has been disabled
unused-ignored-advisory = "warn"

```

--------------------------------

### License allow list with exceptions

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Configures the general allow list for licenses and adds an exception for a specific crate that requires a different license.

```toml
[licenses]
allow = [
    "Apache-2.0",
    "MIT",
]
exceptions = [
    # This is the only crate that cannot be licensed with either Apache-2.0
    # or MIT, so we just add an exception for it, meaning we'll get a warning
    # if we add another crate that also requires this license
    { crate = "cloudabi", allow = ["BSD-2-Clause"] },
]
```

--------------------------------

### Configure unmaintained advisories to workspace only

Source: https://embarkstudios.github.io/cargo-deny/checks/advisories/index.html

Configuration to only error on unmaintained crates that are direct workspace dependencies, instead of all unmaintained crates.

```toml
[advisories]
unmaintained = 'workspace'
```

--------------------------------

### allow.reason: provide reason for allowing crate

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Provides the reason the crate is allowed as a string (e.g., a simple message or URL) surfaced in diagnostic output.

```toml
allow = [{ crate = "package-spec", reason = "the reason this crate is allowed"}]
```

--------------------------------

### Allowing specific GNU licenses

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Shows how to allow `GPL-2.0-or-later`, `GPL-3.0`, and `GPL-3.0-or-later` while excluding `GPL-3.0-only`. GNU licenses are treated pedantically as of cargo-deny 0.18.4.

```toml
allow = ['GPL-2.0-or-later', 'GPL-3.0', 'GPL-3.0-or-later']
```

--------------------------------

### Project exceptions file with allow list

Source: https://embarkstudios.github.io/cargo-deny/checks/licenses/cfg.html

Defines a project exceptions file to allow specific licenses for particular crates. Only the exceptions field should be set in this file.

```toml
exceptions = [
    # Each entry is the crate and version constraint, and its specific allow list.
    { allow = ["CDDL-1.0"], crate = "inferno" },
]
```

--------------------------------

### allow-workspace: automatically allow workspace members

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

If `true`, automatically allows all workspace members even when using a deny-by-default policy. Default is `false`.

```toml
allow-workspace = false
```

--------------------------------

### Run the sources check

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/index.html

Command to run the cargo-deny sources check.

```bash
cargo deny check sources
```

--------------------------------

### Run cargo deny check advisories

Source: https://embarkstudios.github.io/cargo-deny/checks/advisories/index.html

Run the advisories check from the command line.

```bash
cargo deny check advisories
```

--------------------------------

### Allow GitHub organizations as git sources

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Configure `sources.allow-org.github` with a list of GitHub organization names to trust as git sources. The `__` marker is a placeholder for the `[sources]` table header.

```toml
__
[sources.allow-org]
github = ["YourCoolOrgGoesHere"]

```

--------------------------------

### deny.use-instead: suggest replacement crate

Source: https://embarkstudios.github.io/cargo-deny/checks/bans/cfg.html

Shorthand for banning a crate and suggesting a replacement crate.

```toml
deny = [{ crate = "openssl", use-instead = "rustls"}]
```

--------------------------------

### Allow GitLab organizations as git sources

Source: https://embarkstudios.github.io/cargo-deny/checks/sources/cfg.html

Configure `sources.allow-org.gitlab` with a list of GitLab organization names to trust as git sources. The `__` marker is a placeholder for the `[sources]` table header.

```toml
__
[sources.allow-org]
gitlab = ["YourCoolOrgGoesHere"]

```
Tokens:
Raw