osv-scanner

name	osv-scanner
description	| Use when this capability is needed.

OSV-Scanner — Cross-Language Vuln Scanner

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: osv-scanner or osv.

Why OSV

OSV (Open Source Vulnerabilities) is Google-led project with two parts:

1. OSV.dev — distributed vulnerability database aggregating from many sources
2. OSV-Scanner — CLI client that scans your project against OSV.dev

OSV.dev aggregates:

• RustSec Advisory DB (Rust crates)
• GitHub Security Advisory (GHSA) (npm, Maven, NuGet, etc.)
• PyPA Advisory DB (Python)
• Go vulndb
• Android security bulletins
• Linux distro CVEs
• OSS-Fuzz findings
• Ruby Advisory DB
• Hex.pm (Erlang), Pub.dev (Dart), Packagist (PHP)

Single source of truth, single tool. Replaces:

• cargo audit (still useful but redundant if you run osv-scanner)
• npm audit / pnpm audit / yarn audit
• pip-audit
• govulncheck
• bundler-audit

For polyglot projects (BHODL: Rust + Kotlin + Swift + JS tooling): one scanner for all.

Install

# macOS
brew install osv-scanner

# Linux / Windows: download from GitHub releases
curl -L https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64 \
    -o osv-scanner
chmod +x osv-scanner && sudo mv osv-scanner /usr/local/bin/

# Or via Go
go install github.com/google/osv-scanner/cmd/osv-scanner@latest

# Verify
osv-scanner --version

Basic Usage

# Scan current directory (auto-detects all lockfiles)
osv-scanner -r .

# Specific lockfile
osv-scanner --lockfile=Cargo.lock
osv-scanner --lockfile=package-lock.json
osv-scanner --lockfile=pnpm-lock.yaml
osv-scanner --lockfile=requirements.txt
osv-scanner --lockfile=go.mod

# Scan SBOM (CycloneDX or SPDX)
osv-scanner --sbom=sbom.cdx.json
osv-scanner --sbom=sbom.spdx.json

# Container image (uses syft under the hood)
osv-scanner --docker=ghcr.io/bhodl/api:1.0.0

For multi-language projects:

osv-scanner -r . \
    --lockfile=Cargo.lock \
    --lockfile=apps/android/app/build.gradle.kts \
    --lockfile=tooling/package-lock.json

OSV-Scanner detects lockfile type automatically — -r . is usually enough.

Output

Scanning dir .
Scanned <path>/Cargo.lock file and found 145 packages
Scanned <path>/package-lock.json file and found 873 packages

╭─────────────────────────────────────┬──────┬───────────────┬───────────────────────╮
│ OSV URL                             │ ECOS │ PACKAGE       │ VERSION               │
├─────────────────────────────────────┼──────┼───────────────┼───────────────────────┤
│ https://osv.dev/RUSTSEC-2024-0123   │ Crat │ openssl       │ 0.10.50               │
│   ↳ Severity: HIGH                  │      │               │  → fixed in 0.10.55   │
│   ↳ CVE-2024-12345                  │      │               │                       │
├─────────────────────────────────────┼──────┼───────────────┼───────────────────────┤
│ https://osv.dev/GHSA-1234-5678      │ npm  │ ws            │ 8.10.0                │
│   ↳ Severity: MEDIUM                │      │               │  → fixed in 8.17.1    │
╰─────────────────────────────────────┴──────┴───────────────┴───────────────────────╯

Exit code:

• 0 — no vulnerabilities found
• 1 — vulnerabilities found
• 127 — error

Output Formats

osv-scanner -r . --format=json > report.json
osv-scanner -r . --format=sarif > report.sarif       # GitHub Code Scanning
osv-scanner -r . --format=table                        # default
osv-scanner -r . --format=markdown
osv-scanner -r . --format=cyclonedx                    # SBOM-ish

Configuration — .osv-scanner.toml

[[IgnoredVulns]]
id = "GHSA-xxxx-xxxx-xxxx"
ignoreUntil = 2026-12-31
reason = "Not exploitable in our use case (path X never reached)"

[[IgnoredVulns]]
id = "RUSTSEC-2024-0123"
reason = "Vulnerable code path is dev-only, not in release build"

[[PackageOverrides]]
name = "tokio"
version = "1.0.0"
license = { ignore = true }

Place at project root. OSV-Scanner reads automatically.

Severity Levels

OSV uses CVSS scores:

• CRITICAL — 9.0-10.0 (immediate action)
• HIGH — 7.0-8.9 (urgent)
• MEDIUM — 4.0-6.9 (planned fix)
• LOW — 0.1-3.9 (acceptable risk)

For wallet apps: treat HIGH and CRITICAL as merge-blocking. MEDIUM as backlog item with rationale.

CI Integration — GitHub Actions

Quick scan on PR

# .github/workflows/security.yml
name: Vulnerability scan

on: [push, pull_request]

jobs:
  osv-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.9.0
        with:
          scan-args: |
            --recursive
            --skip-git
            ./
        # OR: direct CLI usage

Direct CLI

- name: Install OSV-Scanner
  run: |
    curl -L https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64 \
        -o /usr/local/bin/osv-scanner
    chmod +x /usr/local/bin/osv-scanner

- name: Scan
  run: osv-scanner -r . --format=sarif --output=results.sarif

- name: Upload SARIF to GitHub Code Scanning
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Weekly Scheduled Scan (Catches new CVEs in existing deps)

on:
  schedule:
    - cron: '0 6 * * 1'                   # Monday 6am UTC

jobs:
  weekly-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: main }
      - run: osv-scanner -r .
      - name: Open issue if vulns found
        if: failure()
        uses: peter-evans/create-issue-from-file@v5
        with:
          title: "OSV: weekly scan found vulnerabilities"
          content-filepath: results.json
          labels: security,vulnerability

Comparison with Other Scanners

Tool	Languages	Source	Use case
OSV-Scanner	All major	OSV.dev (aggregator)	Universal scanner
cargo-audit	Rust only	RustSec	Quick Rust check
cargo-deny	Rust only	RustSec + license + bans	Policy enforcement
npm audit	JS only	GHSA via npm registry	Built-in npm
Snyk	All major	Snyk DB (commercial)	Enterprise SaaS
Trivy	OS + langs + container	Multiple	Container-focused
Dependabot	All major	GHSA	GitHub-native auto-PRs
Renovate	All major	OSV + others	Dep updates with PRs

For BHODL CI: OSV-Scanner + cargo-deny + Renovate = comprehensive coverage.

OSV.dev API (Programmatic Access)

# Query single package
curl -X POST https://api.osv.dev/v1/query \
    -d '{"package": {"name": "tokio", "ecosystem": "crates.io"}, "version": "1.0.0"}'

# Get vulnerability details
curl https://api.osv.dev/v1/vulns/RUSTSEC-2024-0001

# Batch query
curl -X POST https://api.osv.dev/v1/querybatch \
    -d @batch.json

Useful for custom dashboards or integration with internal security tools.

Wallet App Security Checklist

For BHODL-style production:

• OSV-Scanner runs on every PR
• OSV-Scanner runs weekly on main (catches new CVEs in unchanged deps)
• HIGH/CRITICAL block merge
• MEDIUM tracked as issue with rationale
• LOW logged but not blocking
• cargo deny for license + ban policies (Rust-specific)
• Renovate or Dependabot for auto-PR updates
• SBOM generated and signed (cosign)
• Vulnerability disclosure policy (SECURITY.md)
• Time-to-patch SLO (e.g., HIGH within 48h)

Comparison with cargo-audit

OSV-Scanner can fully replace cargo audit for Rust:

# cargo audit
cargo audit                           # checks Cargo.lock against RustSec

# OSV-Scanner
osv-scanner --lockfile=Cargo.lock     # checks Cargo.lock against OSV.dev (which includes RustSec)

Both query the same advisories; OSV-Scanner adds:

• Cross-ecosystem scanning (one tool for Rust + JS + Python + Go + ...)
• Container scanning
• SBOM input
• Better SARIF output

For Rust-only projects: cargo-audit + cargo-deny is fine. For polyglot: prefer OSV-Scanner + cargo-deny.

SBOM Generation Pairing

Generate SBOM for archival, then scan repeatedly:

# Rust SBOM
cargo sbom --output-format cyclonedx-json > rust-sbom.cdx.json

# Node SBOM
npx @cyclonedx/cyclonedx-npm --output-file js-sbom.cdx.json

# Container SBOM
syft ghcr.io/bhodl/api:1.0.0 -o cyclonedx-json > container-sbom.cdx.json

# Scan SBOMs (combine into one if possible)
osv-scanner --sbom=rust-sbom.cdx.json --sbom=js-sbom.cdx.json

Sign SBOMs with cosign (see security/sigstore-cosign).

Anti-Patterns

Anti-pattern	Why it's bad	Correct approach
Running OSV-Scanner only on PR	New CVEs in stable deps go undetected	Schedule weekly scan on main
Ignoring HIGH severity vulns	Real exploit risk	Block merge or document waiver
Generic --format=table in CI	Hard to parse	Use SARIF or JSON for tooling
Vulnerability ignore without reason	Future maintainer can't audit	Always explain in .osv-scanner.toml
Single-shot scan (no schedule)	Silent decay	Weekly + per-PR
Trusting only OSV-Scanner	Some advisories slow to land	Pair with cargo audit for Rust
Lock files in .gitignore	Can't reproduce vulns	Always commit Cargo.lock, package-lock.json, etc.
Allow-listing entire crate	Loses future advisories	Pin to specific advisory ID
Running on host with old OSV-Scanner version	Outdated DB	Update tool weekly via dependabot or auto-update CI
Skipping non-prod deps from scan	dev tools also have CVEs	Scan both deps and dev-deps

Troubleshooting

Symptom	Cause	Fix
Failed to scan package	Lockfile format unsupported	Update OSV-Scanner version
Many false positives	Strict version match without context	Use .osv-scanner.toml to ignore with reason
Slow scan	Many lockfiles	Scan only changed lockfiles in PR
lockfile not found	Wrong path or repo layout	Specify with --lockfile=path
SARIF upload to GitHub fails	Permissions	Add security-events: write to workflow permissions
Different results local vs CI	Different OSV-Scanner version	Pin version in CI
Dep update breaks scan	Lockfile drift	Rerun cargo update etc. + commit
Container scan slow	Large image	Layer-by-layer scan with syft + osv-scanner
Reports vulns in transitive deps you can't fix	Upstream not updated	Document, escalate to upstream, or vendor + patch
Cargo.lock scan misses Rust nightly	Some advisories are nightly-only	Acceptable; use stable channel

Public OSV.dev Alternatives

Source	Note
deps.dev (Google)	Same data as OSV.dev, web UI
Snyk Vulnerability DB	Commercial (Snyk acct), broader coverage including license
NVD (NIST)	Authoritative CVE source but slow + low-quality metadata
GitHub Advisory Database	Subset of OSV; useful for browsing

For BHODL: stick with OSV.dev (free, comprehensive, fast).

When NOT to Use This Skill

Scenario	Use Instead
Rust-specific policy enforcement	quality/rust-supply-chain (cargo-deny)
Container deep scanning (OS packages)	Trivy / Grype
SAST (code-level vuln scan)	CodeQL, Semgrep, security-specific skills
Secret scanning	truffleHog, git-secrets, gitleaks
License compliance	cargo deny check licenses, FOSSA, license-checker
iOS/Android-specific vuln (CocoaPods, Maven)	OSV-Scanner DOES cover these

---

Source: claude-dev-suite/claude-dev-suite — distributed by TomeVault.