aeondave/osv-scanner

osv-scanner

Google's dependency scanner — lockfiles + SBOMs, minimal false positives.

Quick Start

# Scan directory (auto-detect lockfiles)
osv-scanner scan source -r .

# Scan specific lockfile
osv-scanner scan source --lockfile package-lock.json

# Scan container image
osv-scanner scan image nginx:latest

# JSON output
osv-scanner scan source -r . --format json

Core Flags

| Flag | Purpose | |------|---------| | -l, --lockfile <file> | Scan specific lockfile | | -r, --recursive | Recursively find lockfiles in directory | | --format <fmt> | Output: json / vertical / html / sarif | | -o, --output-file <file> | Save output to file | | --serve | Serve HTML report at localhost:8000 | | --experimental-call-analysis | Reachability analysis (skip unused vuln code) | | --all-packages | Include packages without CVEs in JSON output | | --no-resolve | Disable transitive dependency resolution | | --offline-vulnerabilities | Use cached local DB (no network) | | --download-offline-databases <dir> | Cache DB locally | | --licenses | Check license compliance | | --config <file> | Config file (overrides directory-level configs) | | --verbosity <level> | info / warning / error |

Supported Lockfiles (19+ formats)

| Language | Files | |----------|-------| | Go | go.mod, go.sum | | JavaScript | package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock | | Python | requirements.txt, poetry.lock, Pipfile.lock, pdm.lock, pylock.toml, uv.lock | | Java | pom.xml, gradle.lockfile, gradle/verification-metadata.xml | | Rust | Cargo.lock | | Ruby | Gemfile.lock, gems.locked | | PHP | composer.lock | | .NET | packages.config, packages.lock.json | | Dart | pubspec.lock | | Elixir | mix.lock | | Haskell | cabal.project.freeze, stack.yaml.lock |

Common Workflows

# Full project scan (recursive)
osv-scanner scan source -r /path/to/project

# Multiple specific lockfiles
osv-scanner scan source \
    -l package-lock.json \
    -l requirements.txt \
    -l go.sum

# Container image scan
osv-scanner scan image myapp:latest --format json

# Reachability analysis (reduces false positives)
osv-scanner scan source -r . --experimental-call-analysis

# HTML interactive report
osv-scanner scan source -r . --format html --serve

# Offline scan (use cached DB)
osv-scanner scan source -r . --offline-vulnerabilities

# CI gate: fail on any finding
osv-scanner scan source -r . --format sarif -o results.sarif
echo $?   # non-zero = vulnerabilities found

# License compliance check
osv-scanner scan source -r . --licenses --format json

Output Parsing

osv-scanner scan source -r . --format json -o scan.json

# Extract findings
cat scan.json | jq '.results[].packages[].vulnerabilities[] | {id: .id, package: .packages[0].package.name, severity: .database_specific.severity}'

# Count by ecosystem
cat scan.json | jq '[.results[].packages[] | select(.vulnerabilities | length > 0) | .package.ecosystem] | group_by(.) | map({eco: .[0], count: length})'

# List affected packages
cat scan.json | jq -r '.results[].packages[] | select(.vulnerabilities | length > 0) | "\(.package.name) \(.package.version) (\(.package.ecosystem))"'

GitHub Actions

name: OSV Scanner
on:
  pull_request:
  schedule:
    - cron: "0 0 * * 0"  # Weekly full scan

jobs:
  # PR scan: only new vulnerabilities introduced in PR
  scan-pr:
    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@v2
    with:
      scan-args: |-
        --lockfile=./package-lock.json
        --lockfile=./requirements.txt
      fail-on-vuln: true
      upload-sarif: true

  # Scheduled full scan
  scan-full:
    if: github.event_name == 'schedule'
    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v2
    with:
      scan-args: |-
        -r .
      fail-on-vuln: true

Resources

| File | When to load | |------|--------------| | references/config-ignore.md | osv-scanner.toml config, ignore rules, package overrides, comparison with grype/trivy |