osv-scanner

What this skill does

# 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

```bash
# 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

```bash
# 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:

```bash
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

```bash
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`

```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

```yaml
# .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/[email protected]
        with:
          scan-args: |
            --recursive
            --skip-git
            ./
        # OR: direct CLI usage
```

### Direct CLI

```yaml
- 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)

```yaml
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)

```bash
# 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:

```bash
# 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 scannin