Dependencies and Supply Chain

Security Analysis: cargo-audit

Projects MUST run cargo-audit¹ to check for known vulnerabilities in dependencies.

Dependency Policy and Supply Chain

cargo-audit¹ answers one question: are any dependencies subject to a published advisory? Projects MUST also enforce a license and provenance policy. cargo-deny³ MUST be used for advisories, licenses, banned crates, and permitted sources. cargo-vet⁴ SHOULD be used where audit provenance is a requirement.

Cargo.lock Strategy

Projects MUST make a deliberate, documented choice. Committing Cargo.lock SHOULD be the starting point for both binaries and libraries, and every project that commits it MUST also test against latest dependencies on a schedule.

Why: the old rule — binaries commit, libraries do not — was withdrawn by the Cargo team on 29 August 2023. Their guidance is now “do what is best for your project”, with committing Cargo.lock as the suggested starting point, and cargo new no longer ignores Cargo.lock for libraries. The reasoning is that an ignored lockfile removes bisectable history, makes contributor CI fail for reasons unrelated to the change under review whenever an upstream release is yanked or broken, and leaves no place to pin a graph that still builds with the declared MSRV — which pushed maintainers towards upper bounds on version requirements, a worse outcome.⁵ The Cargo book states the same position: “When in doubt, check Cargo.lock into the version control system”.⁶

Concern	Commit Cargo.lock	Ignore Cargo.lock
Reproducible builds and bisecting	Yes	No
Contributor CI stability	Unaffected by upstream yanks	Breaks on upstream yanks
MSRV verification	A pinned graph that builds on the MSRV	Must be reconstructed each run
Latest-dependency coverage	Requires a scheduled cargo update job	Automatic, on every run
Binaries and reproducible artifacts	Required	Not acceptable

# The job a committed lockfile obliges you to add
jobs:
  latest-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
        with:
          toolchain: stable
      - run: cargo update            # ignore the committed lockfile
      - run: cargo test --all-features

BAD: "libraries SHOULD NOT commit Cargo.lock". This was withdrawn in 2023
leaves the MSRV lane with no pinned graph to verify against.

--locked MUST be used in CI jobs that are meant to verify the committed graph; without it Cargo silently updates the lockfile when a requirement no longer resolves, and the job stops testing what the repository contains.

Version Constraints

Library dependencies SHOULD use the default caret requirement. Executable tools installed with cargo install MUST be pinned with --version and --locked. Wildcard requirements MUST NOT be used.

Why: a caret requirement lets Cargo unify one copy of a dependency across the graph; an upper bound or an exact pin in a library forces a second copy into every consumer that wants a newer release, and two versions of a crate that exposes types across an API boundary produce “expected struct X, found struct X” errors. Wildcards are worse still: crates.io rejects a publish that contains one, so utils = "1.*" blocks release. Executables are the opposite case — nothing unifies them, and an unpinned cargo install in CI means a new upstream release changes the build with no diff.

[dependencies]
# Caret (default): ^1.2.3 -> >=1.2.3 <2.0.0 — the right choice for a library
serde = "1.0"

# Tilde: ~1.2.3 -> >=1.2.3 <1.3.0 — only with a stated reason
tokio = "~1.53"

# Exact: =1.2.3 — only for a dependency with a known-broken newer release
critical-lib = "=1.2.3"

# BAD: crates.io rejects a publish containing a wildcard requirement.
utils = "1.*"

# GOOD: reproducible tool installs
cargo install cargo-nextest --version 0.9.143 --locked

# BAD: installs whatever is newest today
# crefft: allow-floating -- Negative example contrasts an unpinned install with the command above.
cargo install cargo-nextest

--locked uses the tool’s own published Cargo.lock, so the build is the one its author tested. Without it, a transitive dependency released an hour ago can break the install.

Vulnerability Scanning

cargo audit fix --dry-run MUST be run and its output reviewed before cargo audit fix.

Why: cargo audit fix is not a report. Upstream states that it “will modify Cargo.toml in place”, and that the dry run is the way to “perform a dry run instead, which shows a preview of what dependencies would be upgraded”.¹ Running the mutating form first overwrites dependency requirements before anyone has seen what it proposes; the change surfaces only in the manifest diff or in the next failing build, and recovery depends on version control or on retyping the requirements by hand. The feature is labeled experimental upstream, which is a further reason to look before writing.

# Install cargo-audit with the optional `fix` feature
cargo install cargo-audit --version 0.22.2 --locked --features=fix

# Run security audit
cargo audit

# ALWAYS preview first: this writes nothing
cargo audit fix --dry-run

# Only after reviewing the preview: this rewrites Cargo.toml in place
cargo audit fix

# BAD: rewrites Cargo.toml before anyone has seen the proposed change.
cargo audit fix
cargo audit fix --dry-run   # too late; the manifest is already modified

cargo audit fix MUST NOT be invoked from a default cargo-audit build made with cargo install: the subcommand is compiled out unless the fix feature is enabled, and the documented remediation step then fails with “error: unrecognized subcommand ‘fix’”.¹