unsafe-review

Advisory unsafe-contract review for Rust PRs.

unsafe-review points reviewers and coding agents at changed Rust unsafe seams that are missing review evidence: a safety contract, local guard, test reach, or witness receipt.

It does not prove unsafe Rust sound. It makes unsafe Rust reviewable.

The first useful run should feel small:

one PR
-> one changed unsafe contract
-> one missing evidence gap
-> one recommended guard, test, or witness route

Miri asks:

Did this concrete execution hit UB?

unsafe-review asks the cheaper PR-time question:

Does this unsafe change have the safety contract, guard, test reach,
and witness route needed to make review credible?

Trust boundary

unsafe-review reports static review evidence. It is not memory-safety proof, not UB-free status, not Miri-clean status, and not a site-execution claim unless a matching witness receipt is attached.

It is advisory by default: no witness execution, no automatic comments, no source edits, and no default blocking policy.

Install

cargo install unsafe-review --locked
unsafe-review --version
unsafe-review doctor

Programmatic users should depend on unsafe-review-core. Most users should install the unsafe-review façade crate.

Quick start

# Review the current PR against main
unsafe-review first-pr --base origin/main

# Explain one card
unsafe-review explain <card-id>

# Confirm support posture and limits
unsafe-review support

first-pr writes cards.json, pr-summary.md, github-summary.md, cards.sarif, comment-plan.json, witness-plan.md, and lsp.json under target/unsafe-review/. It is advisory-only: it does not run witnesses, post comments, edit source, or enforce blocking policy.

For the end-to-end maintainer path from first card to fix, witness receipt, and outcome comparison, see Find and fix UB-risk review seams. For release-note history, see CHANGELOG.md.

Example: Review a fixture PR

Run against the bundled raw_pointer_alignment fixture (no real diff required):

unsafe-review first-pr \
  --root fixtures/raw_pointer_alignment \
  --diff fixtures/raw_pointer_alignment/change.diff

Real output (trimmed):

unsafe-review first-pr
unsafe-review wrote an advisory PR bundle.
- Artifact directory: target/unsafe-review
- Review cards: 1
- Open actionable gaps: 1
Open:
  target/unsafe-review/pr-summary.md
Top card:
  src/lib.rs:8 `raw_pointer_read`
  Class: `guard_missing`
  Missing: guard, witness
  Route: `miri`
Explain top card:
  unsafe-review explain --root fixtures/raw_pointer_alignment \
    UR-raw-pointer-alignment-fixture-src-lib-rs-read-header-operation-raw_pointer_read-cast-header-8a1362456e39-pointer_validity-c1
Artifacts:
  target/unsafe-review/cards.json
  target/unsafe-review/pr-summary.md
  target/unsafe-review/cards.sarif
  target/unsafe-review/comment-plan.json
  target/unsafe-review/lsp.json
  ... (full list in target/unsafe-review/)
Trust boundary:
  static unsafe contract review only; not memory-safety proof, not UB-free status,
  not Miri-clean status, and not a site-execution claim unless a matching witness
  receipt says so.

Then explain the card:

unsafe-review explain --root fixtures/raw_pointer_alignment \
  UR-raw-pointer-alignment-fixture-src-lib-rs-read-header-operation-raw_pointer_read-cast-header-8a1362456e39-pointer_validity-c1

For the full loop from card to fix and witness receipt, see Find and fix UB-risk review seams.

Add badges to your repo

cargo install unsafe-review --locked
unsafe-review badges --out badges/
git add badges/

Then add Shields endpoint badges that point at your own repository and policy document.

Do not copy this repository’s badge URLs. Badge endpoints are repo-scoped static evidence projections and must point at your own OWNER/REPO/BRANCH badges/*.json paths. unsafe-review reports open review gaps; unsafe-review+ reports missing-or-weak evidence-quality findings. Both are advisory evidence indicators only.

Try the bundled smoke fixture:

unsafe-review first-pr \
  --root fixtures/raw_pointer_alignment \
  --diff fixtures/raw_pointer_alignment/change.diff

What unsafe-review produces

Surface	Output	Use
Review cards	JSON / human / Markdown	The canonical evidence object
PR summary	pr-summary.md	Reviewer first screen
GitHub job summary fragment	github-summary.md	Bounded slice for GITHUB_STEP_SUMMARY
SARIF	cards.sarif	Code scanning / CI artifact
Comment plan	comment-plan.json	Proposed comments, not posted
Saved LSP projection	lsp.json	Read-only editor diagnostics and hovers
Agent packet	context <card-id> --json	Bounded LLM repair context
Receipt audit	JSON / Markdown	Match saved witness receipts to cards
Outcome comparison	JSON / Markdown	Compare saved snapshots
Repo posture	JSON / Markdown / badge JSON	Count open review gaps, not safety
Policy report	JSON / Markdown	Advisory no-new-debt simulation

Choose a path

If you need to...	Start with...	Typical output
Review a PR	unsafe-review pr (auto-detects base)	ReviewCards and PR summary
Feed CI artifacts	--format json, --format sarif, --format pr-summary	Uploaded advisory artifacts
Explain one finding	unsafe-review explain <card-id>	Human-readable contract gap
Inspect support posture	unsafe-review support	Experimental / advisory / deferred boundaries
Hand work to an agent	unsafe-review context <card-id> --json	Bounded repair packet
Audit saved witness receipts	unsafe-review receipt audit	Matched / stale / duplicate receipt report
Compare before/after posture	unsafe-review outcome --before before.json --after after.json	New / resolved / improved / regressed cards
Inspect repo posture	unsafe-review repo --format markdown	Open unsafe-review gaps
Simulate policy	unsafe-review policy report	Advisory no-new-debt report

What works today

• Fixture-backed ReviewCards for many core unsafe operation families.
• Dogfood-backed evidence rules across selected real Rust crates and PR diffs.
• Advisory PR artifacts: cards JSON, PR summary, SARIF, and comment-plan.
• Read-only projections for saved LSP/editor output and bounded agent packets.
• Saved receipt audit for imported witness metadata.
• Outcome and repo posture reports for before/after movement and open gaps.
• Advisory policy reports for no-new-debt simulation.

Everything above remains experimental and advisory. No current surface is calibrated as a blocking policy gate.

Status at a glance

The README is the front door, not the support ledger. Current proof and support posture live in the status docs.

Area	Status source
Support posture	Support summary
Claim-to-proof ledger	Support tiers
Find/fix workflow	Find and fix UB-risk review seams
Advisory CI cookbook	UB-risk review CI cookbook
First-use guide	First-use guide
First-hour guide	First-hour guide
ReviewCard trust boundary	ReviewCard explanation
Explain examples	Reviewer examples
Agent repair workflow	Bounded agent repair workflow
Dogfood evidence	Dogfood index
CLI reference	CLI guide
LSP/editor integration	Saved LSP projection guide

Crate surface

unsafe-review          # product facade / install handle
unsafe-review-cli      # CLI adapter and rendering
unsafe-review-core     # SDK / analysis engine
xtask                  # repo automation, not product surface

The crate boundary policy is: design seams like microcrates, implement most as module families, and publish only seams that deserve a support promise.

Development

cargo fmt --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
cargo run --locked -p xtask -- check-pr
cargo run --locked -p xtask -- check-calibration
cargo run --locked -p xtask -- check-dogfood

Documentation map

• Start here: adopting unsafe-review
• First-use guide
• First-hour guide
• Mission and vision
• Roadmap
• Architecture
• CLI guide
• UB-risk review CI cookbook
• ReviewCard trust boundary
• Explain examples
• Bounded agent repair workflow
• Specifications
• ADRs
• Implementation plan
• Support summary
• Support tiers
• Dogfood index
• Policy ledgers

Fuzzing

The repository includes a manual cargo-fuzz harness for analyzer robustness. It is not part of the default PR gate. See Fuzzing for the harness input contract.

cargo install cargo-fuzz
cargo fuzz run analyze

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license