crev-dev/cargo-crev/cargo-crev-review

cargo-crev: reviewing Rust dependencies as an agent

This skill tells you how to review a Rust dependency on the user's behalf and help them produce a signed cargo-crev package review proof that they can publish to their proof repository.

When to use this skill

Use this skill when the user asks you to:

• review one of their Rust dependencies (or a transitive dep),
• audit a specific crate version,
• produce a cargo crev review/proof for a crate,
• help them catch up on crates that still need reviewing.

Do not use this skill for unrelated security audits, non-Rust code, or trust proofs for other crev ids — those are separate workflows.

Prerequisites (check these first)

1. The user has a crev id configured:

``sh cargo crev id current ` If this fails, stop and ask the user to run cargo crev id new --github-username <them>` first. Do not auto-generate an id.

1. The user's proof repo has been set up and is reachable.

cargo crev repo dir prints the local path.

High-level workflow

1. Refresh the user's web of trust. Run cargo crev update once

at the start of the session to pull the latest proofs from every trusted reviewer's proof repo (it's a shortcut for cargo crev repo update). Without this, both candidate discovery (which depends on the status column reflecting current trusted reviews) and the later cross-check against existing reviews can be working off stale data, causing you to either review a crate someone else just signed off on or miss a recent advisory. See "Refreshing the web of trust" below.

1. Pick the crate + version to review. If the user names a specific

crate, skip to the next step. Otherwise, use the candidate discovery step below to produce a ranked list and confirm the pick with the user.

1. Start a review report file. See "The review report file" below.

Every finding from every subsequent step — positive or negative — gets appended to this file as you go. This is your scratchpad, your audit trail, and the source you distill into the final comment.

1. Locate the crate's local source. Use

cargo crev crate dir <name> <version> to print the path to the crate source tree that cargo downloaded from crates.io. Record the path in the report.

1. External verification. Check that what crates.io shipped matches

the public upstream repository at a specific commit, and that that commit corresponds to the advertised version tag. See "External verification" below. Record the outcome — pass, partial, or fail — in the report. Any unexpected discrepancy is a real finding and must be raised to the user before proceeding.

1. Read the code. See "Reviewing the code" below. Append findings

to the report as you go.

1. Cross-check against existing reviews. Query the local proof

database for any existing reviews of this crate (any version), read them, and reconcile with your own findings. See "Cross-checking existing reviews" below. Record the comparison in the report.

1. Assemble the unsigned proof file. Fill in the YAML fields

(rating, thoroughness, understanding, comment, issues, advisories, llm-agent). The comment is the full text of the report file by default — see "Assembling the unsigned proof" below.

1. Validate the proof file. Round-trip the unsigned proof through

cargo crev review --import-unsigned-from ... --no-store --no-edit --print-unsigned. This step is mandatory — fix and re-validate until it passes. See "Round-trip validating the draft" below.

1. Hand off to the user. The agent does not sign or publish.

Give the user two files — the report and the unsigned proof — along with the exact command they should run to interactively review, edit and sign it. See "Handing off to the user" below.

The review report file

Maintain a single markdown file per review, at:

target/crev/reviews/<crate>-<version>.md

(Create the directories if they don't exist.) Start it as soon as a candidate is picked, before any inspection begins. Append to it throughout the review — treat it as an append-only journal.

Minimum structure:

# Review: <crate> <version>
 
-Local source: <path from `crate dir`>
-Upstream repository: <URL or "unknown">
-Upstream commit verified: <sha or "n/a">
-Upstream tag for version: <tag or "n/a">
-Verification outcome: pass | partial | fail
 
## External verification
 
<details of what was checked, what matched, what differed>
 
## Code review findings
 
<ongoing notes — one bullet per observation, grouped by file or theme>
 
## Cross-check against existing reviews
 
<how many prior reviews, agreement, disagreement, verdict on whether
they change your draft fields>
 
## Open questions / things skipped
 
<anything you didn't examine and why>
 
## Draft review fields
 
-rating: ...
-thoroughness: ...
-understanding: ...

Rules:

• Append, don't rewrite. If you change your mind about something,

add a follow-up note; don't quietly edit earlier entries. The user should be able to see how your understanding evolved.

• Every problem, however small, goes in. Even if you decide it's

not worth reporting in the final proof, it belongs in the report so the user can sanity-check your judgement.

• Record what you did *not* look at. If you skipped the test

directory, or only skimmed build.rs, say so explicitly under "Open questions / things skipped". This is what backs honest thoroughness / understanding values later.

• Hand the report to the user alongside the unsigned proof file

at the end of the workflow (see "Handing off to the user"). The report is how the user actually audits your work; the unsigned proof is the thing they sign after auditing.

Refreshing the web of trust

Before any candidate discovery or cross-checking, pull the latest proofs from every trusted reviewer:

cargo crev update

This is a shortcut for cargo crev repo update. It walks every proof repository in the user's WoT and git fetches it, so the local proof database reflects the current state of the world. It can take a few seconds to a minute depending on how many ids the user trusts and network conditions; that's normal.

Run this once per session, before the first candidate-discovery pass, and again only if the session has been running long enough that the data is plausibly stale or the user explicitly asks. It is not necessary to re-run it between successive reviews in the same session.

If the command fails for some repos (network blip, dead remote, auth issue) but succeeds for others, that is usually fine — note the failures in case they matter, but proceed. If it fails entirely (e.g. no trusted ids configured, so there is nothing to fetch), stop and tell the user: candidate discovery and cross-checking will both be meaningless until the WoT is set up.

Finding candidate crates to review

When the user hasn't named a specific crate, first make sure the WoT is fresh (see "Refreshing the web of trust" above), then capture a stats dump of their dependencies.

`cargo crev verify` is slow — it walks every dependency, downloads metadata from crates.io, and computes trust graphs. On a non-trivial project it can take 30 seconds to several minutes. Therefore:

• Run it exactly once per session and save the output to a file.
• Never re-run it unless the user explicitly asks or the dependency

tree has changed (e.g. after cargo update).

• All candidate discovery, sorting, and filtering works on the saved

file — re-read the file instead of re-running the command.

cargo crev verify \
    --show-reviews true --show-downloads true \
    --show-loc true --show-flags true \
    --force-print-header \
    > target/crev-verify.txt 2>&1

Notes:

• Only request the columns you actually need for candidate selection:

reviews, downloads, loc, and flags. The default output already includes status, name, and version.

• Do not use --show-all — it enables many extra columns (geiger,

owners, issues, lpidx, latest trusted version, …) that produce wide, hard-to-parse output and are not needed for picking candidates. If you need a specific extra column later (e.g. --show-geiger true for a particular analysis), add it to a one-off query for that crate, not to the full dump.

• --force-print-header makes the tool print the column header even

when stdout is redirected. Always use this when capturing — the header is the only reliable way to know which column is which.

• Exit status 255 is expected and does not mean the command

failed. It signals VerificationFailed — i.e. at least one dependency is not yet fully verified, which is obviously the case when you're about to start reviewing. Only treat it as a real error if the stdout file is empty or the stderr contains an actual error message.

• Status column values you'll see:
• local — crate from a local path source (skip; not reviewable via

crates.io).

• none — no existing trusted review; prime candidate.
• pass — already has sufficient trusted reviews; skip.
• flagged / dangerous — has issues reported against it; these

may be worth confirming rather than reviewing fresh.

• N/A — there are no trusted ids in the user's WoT at all. If you

see this, stop and tell the user they should set up trust first (cargo crev trust <id>) before candidate discovery is meaningful.

Once the file exists, work from it for all subsequent candidate selection in this session. If you need to re-examine the data, read target/crev-verify.txt — do not re-run cargo crev verify.

Before narrowing down, confirm the criteria with the user — see the "Picking candidates" section below.

Picking candidates

Picking what to review is inherently a bit arbitrary, but the default goal is: find the non-passing, non-local, least-reviewed, least-downloaded package — i.e. the most obscure crate in the user's dependency tree that nobody else is likely to be reviewing any time soon. Unless the user says otherwise, apply these filters/rankings in order:

1. Filter by `status`. Keep only status = none. Skip pass

(already covered), local (not from crates.io), and N/A (configuration problem, handled separately). flagged / dangerous are a separate workflow (confirming pre-existing issue reports) — don't pick them unless the user asked.

1. Sort by lowest total review count. Use the second reviews

column (total across all versions, not the per-version count). Zero-review crates come first.

1. Tiebreak by lowest total download count. Popular crates will

eventually get reviewed by someone else; obscure ones won't. Reviewing the long tail is higher marginal value. Use the second downloads column (total).

1. Tiebreak by `CB` flag. Among otherwise equal candidates, prefer

crates with a custom build script — they run arbitrary code at build time and are higher-risk, so the review is more valuable.

If the user has additional or different preferences (e.g. "I only care about direct deps", "prioritize high lpidx", "skip -sys crates"), they override the defaults above — ask if unsure.

The user's own crates are valid candidates. If a top candidate turns out to be authored by the user themselves, don't filter it out — a review where the author says "I wrote this and had an LLM agent audit it" is still a useful signal for downstream consumers, and once published it'll flip to status = pass and drop out of the filter naturally. Agent provenance is recorded structurally via the llm-agent: field on the proof (see "Disclosing agent provenance" below), so no special comment wording is needed for own-crate reviews.