Every Rust build trusts three things it rarely examines: the registry credentials on the machine that publishes, the sources Cargo is allowed to fetch from, and the crates that resolve into Cargo.lock. By default Cargo stores a crates.io token in a plain text file, accepts any registry or git source a manifest names, and picks up a new version the moment it is published. This guide goes deeper than the general Rust Security Guide on the Cargo and crates.io side: credential providers and token scopes, private and mirrored registries, source policy with cargo-deny, audit policy with cargo-vet, minimum publish age, and how to monitor all of it. It is for Rust platform owners, build and release engineers, and security teams responsible for Rust dependencies; facts are from the Cargo, cargo-deny and cargo-vet documentation as checked on 27 October 2026.
This is an independent guide from NHI Mgmt Group, based on the Rust Project's public documentation as of November 2026. It is not sponsored or reviewed by the Rust Project. Product features change, so confirm settings against the Rust Project's current documentation.
Key takeaways
- Configure credential providers everywhere. Cargo's own documentation recommends a global provider list that uses the operating system key store, so tokens are not left unencrypted in
credentials.toml. - Scope and expire every crates.io token. Tokens can be limited to endpoint scopes such as
publish-updateand to crate name patterns; a legacy full-access token is a key to every crate its owner maintains. - Prefer Trusted Publishing, then delete the old token. Short-lived OIDC tokens only help if the long-lived token they replace is revoked.
- Make sources explicit. cargo-deny's
[sources]check can deny unknown registries and git repositories, which closes dependency confusion and drive-by git dependencies. - Slow down new versions. Committed lock files with
--lockedin CI, cargo-vet audits and, from Cargo 1.100, a minimum publish age keep a freshly published malicious version out of builds.
How identity and access work in crates.io and Cargo
crates.io accounts are created by signing in with GitHub, so the maintainer's GitHub account is the root of trust for every crate they own. Each crate has owners (users or GitHub teams) who can publish versions, yank versions and change ownership. Machines act through API tokens.
| Identity | Where it lives | What it can do | Main risk |
|---|---|---|---|
| Maintainer GitHub account | GitHub | Sign in to crates.io, create tokens, manage owners | Phished or token-compromised GitHub account |
| crates.io API token | Developer machine, CI secret, credential provider | Whatever its endpoint and crate scopes allow | Plain text storage, broad legacy scope, no expiry |
| Trusted Publishing token | Issued per workflow run from GitHub OIDC | Publish the crates configured for that repository and workflow | Compromised workflow or untrusted build inputs |
| Private registry token | Credential provider or environment variable | Read and or publish to an internal registry | Shared CI token reused across projects |
| Git credentials for git dependencies | Git credential helper, SSH keys | Fetch private repositories | Broad deploy keys on build agents |
Credential providers
Cargo authenticates to registries through credential providers. The Registry Authentication chapter states that alternative registries requiring authentication must have a credential provider configured, to avoid storing unencrypted credentials on disk without knowing it; for historical reasons, public registries such as crates.io fall back to cargo:token when nothing is configured.
| Provider | Storage | Use |
|---|---|---|
cargo:token | Plain text credentials.toml; also reads CARGO_REGISTRIES_<NAME>_TOKEN | CI with injected environment variables; fallback only. If it is not listed, the *_TOKEN variables do not work |
cargo:wincred | Windows Credential Manager, as cargo-registry:<index-url> | Windows developer machines |
cargo:macos-keychain | macOS Keychain | macOS developer machines |
cargo:libsecret | libsecret-compatible stores such as GNOME Keyring, KDE Wallet or KeePassXC | Linux desktops |
cargo:token-from-stdout <command> | Whatever the command reads, for example a vault CLI | Fetching short-lived tokens from a secrets manager; cargo login and logout are not supported |
| Credential plugins | External executables following the credential provider protocol | Password managers or enterprise vaults |
The documented recommended configuration in $CARGO_HOME/config.toml is [registry] global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"], where later entries have higher precedence, so the operating system store is tried before the plain text fallback. A registry-specific provider can be set with registries.<name>.credential-provider. The provider protocol tells the provider whether a request is for a read or a publish operation and lets it say whether a token may be cached never, for the session or until expiry, which allows a vault-backed provider to hand out publish credentials only when needed. Note that the experimental asymmetric token feature and its cargo:paseto provider have been removed from nightly Cargo, so do not build on it.
Admin roles and privileged access
- Crate owners: every owner can publish and yank. Keep at least two human owners for continuity, remove former maintainers promptly and prefer a GitHub team owner for organisation crates so membership follows team changes.
- Token scopes: RFC 2947 defines crates.io endpoint scopes
publish-new,publish-update,yankandchange-owners, pluslegacyfor the old unrestricted behaviour, and crate scopes that may end in*to match a prefix. A release token needspublish-updatefor named crates only;change-ownersshould never sit in CI. - Expiry: give every remaining API token an expiry date and an owner, and review tokens when maintainers leave.
- Maintainer accounts: because crates.io sign-in is through GitHub, enforce phishing-resistant MFA on maintainer GitHub accounts and review their OAuth grants. See the GitHub and GitHub Actions Security Guide.
- Private registries: separate read tokens (for builds) from publish tokens (for release pipelines), and restrict who can administer the registry and its storage.
Integrations, API tokens and service accounts
Publishing from CI
crates.io Trusted Publishing, announced in the July 2025 crates.io development update, lets a configured GitHub repository exchange a GitHub Actions OIDC token for a short-lived crates.io token using rust-lang/crates-io-auth-action. It supports GitHub Actions only, with other providers such as GitLab CI described as possible later; the first release must be published manually, and the optional environment: release setting is described as adding security. The workflow mechanics are in the Rust Security Guide; the points that matter for supply chain governance are:
- Revoke the token Trusted Publishing replaces. In the Ultralytics PyPI compromise, the project had adopted trusted publishing but a long-lived API token was never revoked, and the attacker used it to upload two further malicious releases after the workflow flaw was fixed. The same failure is possible on crates.io.
- Protect the workflow, not just the token. The Ultralytics release also trusted a cache the attacker could write to. Release jobs should not restore caches written by untrusted pull request jobs, and should run in a protected environment with required reviewers. See the GitHub Actions OIDC Federation Hardening Guide.
- Where Trusted Publishing is unavailable: use a token scoped to
publish-updateand named crates, with expiry, stored as an environment-scoped CI secret rather than a repository-wide one.
Private and mirrored registries
- Authenticated registries: a private registry that sets
auth-required: truein its indexconfig.jsonmakes Cargo send theAuthorizationheader for all operations, including API requests, crate downloads and sparse index updates. Use it for internal crates so the index itself is not public. - Source replacement: Cargo can replace crates.io with a mirror or a vendored directory, but the documentation is explicit that a replacement source must contain exactly the same code and is not appropriate for private registries or patching. Mirrors give you a choke point for scanning and quarantine; vendoring (
cargo vendor) gives fully offline, reviewable builds. Publishing commands then need an explicit--registry. - Private crate names: publish internal crates only to the internal registry, and name them so that a public crate with the same name cannot be confused for them. See the Malicious Package and Dependency Confusion Guide.
Dependency policy: cargo-deny, cargo-vet and publish age
| Control | Setting | Effect |
|---|---|---|
| cargo-deny sources | unknown-registry = "deny", unknown-git = "deny", explicit allow-git | Fails the build on any registry or git source not approved; both default to warn |
| cargo-deny sources | required-git-spec = "rev" | Git dependencies must pin a commit rather than track a branch |
| cargo-deny bans, build section | allow-build-scripts list; executables = "deny" (default) | Only listed crates may have build scripts; native executables in crate sources are flagged |
| cargo-deny advisories and bans | Deny vulnerable, yanked and unmaintained crates; ban known bad or duplicate crates | Policy-as-code over the dependency graph |
| cargo-vet | cargo vet --locked in CI, shared audit imports, cargo vet trust with an expiry | Every version is audited or covered by a time-limited trusted publisher entry |
| Lock files | Commit Cargo.lock; build with --locked (or --frozen, which adds --offline) | CI fails if resolution would change or the lock file is missing |
| Minimum publish age | registry.global-min-publish-age = "7 days" | Resolver ignores versions published more recently, unless already in Cargo.lock |
- Build script limits are partial: cargo-deny's own documentation warns that its build checks mainly highlight native executables and scripts, and cannot catch, for example, a build script that uses
include!()to pull in code that changes between versions. Pair it with cargo-vet review of anything that runs at build time. - cargo-vet trust entries: trusting a publisher requires an expiry date so the judgement is revisited. The book suggests making the
supply-chain/directory subject to code owners so audit changes are reviewed. - Publish age status: the Cargo changelog lists minimum publish age ("dependency cooldowns", RFC 3923) as stabilised in Cargo 1.100, dated 12 November 2026. Until your toolchain includes it, achieve the same effect through a mirror that delays new versions or through dependency update tooling with a cooldown. See the Dependency Update Automation Guide.
Decision guidance
| Situation | Recommended pattern |
|---|---|
| Open source crate maintained by a small team | Trusted Publishing from a protected environment, no stored tokens, two owners with strong MFA, cargo-deny in CI |
| Company consuming crates.io in products | Committed lock files, --locked, cargo-deny sources and advisories, cargo-vet with imported audits, minimum publish age |
| Regulated or air-gapped builds | Internal mirror or vendored sources via source replacement, scanning and quarantine on the mirror, --frozen builds |
| Internal crates shared across teams | Private registry with auth-required, read and publish tokens separated, delivered by a credential provider |
Small teams should start with credential providers, token scoping and cargo-deny, which cost almost nothing. Large organisations gain most from a central mirror and a shared cargo-vet audit set, because audits and quarantine decisions are then made once for every team.
Logging and detection
- Publish events: watch crates.io notifications and the crate's version list for releases that do not correspond to a tag and a release workflow run.
- Token inventory: list crates.io and private registry tokens with scope, owner, last use and expiry; alert on legacy-scope tokens and tokens past their review date.
- Secret scanning: scan repositories, CI logs and build caches for registry tokens and
credentials.tomlfiles. See the Git Secret Scanning Guide. - Policy results: record cargo-deny and cargo-vet results per build, and alert when exemptions or allow lists change.
- Mirror telemetry: requests for crates not previously used, typosquat-like names and versions younger than the publish age.
Metrics:
- Percentage of publishing crates using Trusted Publishing, and count of remaining long-lived publish tokens.
- Percentage of developer machines and agents with a credential provider other than
cargo:tokenconfigured. - cargo-vet exemptions count, trending down.
- Builds using
--lockedand passing cargo-deny sources withdenysettings. - Mean time from a RustSec advisory to an updated Cargo.lock in production services.
Hardening baseline
- Credential providers: roll out the recommended
global-credential-providerslist through managed developer configuration; in CI, inject tokens as environment variables and keepcargo:tokenlisted so they work. - Token clean-up: inventory crates.io tokens, revoke legacy-scope and unused tokens, and reissue only scoped, expiring tokens where Trusted Publishing is not possible.
- Trusted Publishing: enable it for each crate, protect the release environment, then revoke the stored token.
- Source policy: introduce cargo-deny with
unknown-registryandunknown-gitatwarn, fix findings, then switch todeny. - Audit policy: initialise cargo-vet, import audits from organisations you trust, record exemptions, and require
cargo vet --lockedon every change to Cargo.lock. - Freshness controls: enforce
--lockedin CI and adopt minimum publish age once on Cargo 1.100 or later. - Rollback: each policy is a configuration file; keep changes in version control so a policy that blocks an urgent fix can be relaxed for one crate with a recorded exemption rather than disabled.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | SR-3, SR-4, SR-11, CM-14 | Supply chain controls, provenance, component authenticity, signed components |
| NIST SP 800-53 Rev. 5 | IA-5, SC-28 | Registry token management and protection at rest |
| NIST CSF 2.0 | GV.SC-05, PR.PS-02 | Supply chain requirements; software maintained and replaced by risk |
| MITRE ATT&CK | T1195.001, T1552.001, T1528 | Compromised dependencies; tokens in credential files; stolen application tokens |
For provenance and attestations across ecosystems see the SLSA and Build Provenance Guide.
Common misconfigurations
- No credential provider configured, so
cargo loginleaves a crates.io token in plain text on laptops and build agents. - Legacy full-scope tokens in CI that can publish, yank and change owners for every crate the maintainer owns.
- Trusted Publishing enabled, old token still live, as in the Ultralytics case on PyPI.
- cargo-deny left at warn, so unknown registries and branch-tracking git dependencies pass silently.
- Libraries and services built without
--locked, so CI resolves a newly published version that nobody reviewed. - Source replacement used as a private registry, contrary to Cargo's documentation, creating confusion between internal and public crates.
Practitioner checklist
- Deploy the recommended credential provider list to all developer machines and build agents.
- Inventory crates.io and private registry tokens; revoke legacy and unused ones.
- Scope remaining tokens to
publish-updateand named crates, with expiry and an owner. - Enable Trusted Publishing from a protected environment, then delete stored publish tokens.
- Keep two or more owners per crate with phishing-resistant MFA on their GitHub accounts.
- Set cargo-deny
unknown-registryandunknown-gittodenyand require pinned git revisions. - Run
cargo vet --lockedin CI and protect thesupply-chain/directory with code owners. - Commit Cargo.lock, build with
--locked, and adopt a minimum publish age. - Use
auth-requiredprivate registries or a mirror for internal crates and quarantine.
Standards and references
- The Cargo Book: Registry Authentication
- The Cargo Book: Credential Provider Protocol
- The Cargo Book: Source Replacement
- The Cargo Book: Registry Index
- Rust RFC 2947: crates.io token scopes
- cargo-deny: Sources configuration
- cargo-vet: The cargo-vet book
- Rust Blog: crates.io development update, July 2025
Related NHI Mgmt Group resources: Rust Security Guide · Software Supply Chain Security Guide · npm Trusted Publishing and Provenance Guide · PyPI API Tokens and Trusted Publishing Security Guide