osv-scanner - qa-security-scanning

When to use

Team prefers OSS tooling over commercial Snyk.
Layered SCA strategy - pair with snyk-test for cross-DB consensus signal.
Custom package manager produces SBOMs not natively supported; feed SBOM directly to OSV-Scanner.
Lightweight CI gate without commercial-license setup.

Step 1 - Install

docker pull ghcr.io/google/osv-scanner:latest

Other install paths (consult google.github.io/osv-scanner for current options per platform):

# Go install
go install github.com/google/osv-scanner/cmd/osv-scanner@v1

# Homebrew
brew install osv-scanner

# Direct binary download from github.com/google/osv-scanner/releases

Step 2 - Basic recursive scan

Per osv-usage (opens in new window):

osv-scanner scan -r ./my-project-dir/

Auto-detects manifest files (package-lock.json, Pipfile.lock, go.mod, Cargo.lock, etc.) and queries OSV.dev for each.

Per-lockfile scan (-L targets one lockfile without recursing, useful in monorepos):

osv-scanner scan -L package-lock.json --output-file scan-results.txt

Step 3 - Output formats

Per osv-usage (opens in new window): --format json and --format=vertical and --format=html are referenced. Full format list per the osv-scanner documentation:

Format	Use
`--format json`	For downstream aggregation
`--format sarif`	GitHub Code Scanning upload
`--format markdown`	PR comments
`--format vertical`	Default human-readable
`--format html`	Standalone report

Step 4 - SBOM-driven scanning

For projects with custom build systems that emit SBOMs but lack natively-parsed lockfiles:

osv-scanner scan --sbom my-app.cyclonedx.json
osv-scanner scan --sbom my-app.spdx.json

This composes with syft-generation - Syft generates the SBOM, OSV-Scanner queries OSV.dev against it.

Step 5 - `osv-scanner.toml` config

Suppress a vuln with an expiring, reasoned entry (auditable in git):

# osv-scanner.toml
[[IgnoredVulns]]
id = "CVE-2024-1234"
ignoreUntil = 2026-12-15T00:00:00Z
reason = "Reachability confirms unreachable; tracked in JIRA-1234"

The full schema ([[PackageOverrides]], multi-entry config, --config flag, the mandatory justification template) is in references/osv-scanner-config-and-ci.md.

Step 6 - False-positive triage (MANDATORY)

Suppress via [[IgnoredVulns]] (per-CVE, with ignoreUntil) or [[PackageOverrides]] (per pinned package + ecosystem) in osv-scanner.toml; --severity-threshold is a scan-time filter, not a suppression. Every entry carries a mandatory reason + approver + re-review date. ignoreUntil is enforced - past-due ignores re-surface in the scan results. The suppression-layer table and justification template are in references/osv-scanner-config-and-ci.md.

Step 7 - Exit codes + CI gating

OSV-Scanner exit codes (verify against current docs):

0 - no vulnerabilities found
1 - vulnerabilities found
127 - config error

The google/osv-scanner-action GHA (Docker invocation + SARIF upload) is in references/osv-scanner-config-and-ci.md.

Step 8 - License-checking (adjacent feature)

OSV-Scanner has experimental license-summary support:

osv-scanner --experimental-licenses-summary scan -r .

For full license-compliance + scanning, pair with sbom-formats or use a dedicated tool like ScanCode / FOSSology.

Anti-patterns

[[IgnoredVulns]] without ignoreUntil -> debt persists; always set ignoreUntil (Step 5).
Skipping --format=sarif upload -> findings invisible in the GitHub Security tab; always emit SARIF (Step 7).
Running only OSV-Scanner -> OSV.dev has its own coverage profile; layer with snyk-test.
Scanning without a committed lockfile -> manifest fallback resolves versions less accurately; commit the lockfile and scan via -L.
--config pointing outside the repo -> suppressions not auditable; commit osv-scanner.toml at the repo root.

Limitations

OSV.dev coverage varies by ecosystem (Python / npm / Go strong; less common ones thinner).
No reachability analysis: every CVE on a declared dep counts even if the vulnerable function isn't called.
Container image scanning is limited; prefer trivy-image or the Grype workflow in syft-generation.
Some CLI surface evolves; verify against current osv-scanner help output.

References

osv-usage (opens in new window) - usage page (lockfile, SBOM, config)
Full osv-scanner.toml schema, triage template, and CI workflow: references/osv-scanner-config-and-ci.md
google.github.io/osv-scanner - full docs
github.com/google/osv-scanner - repository
osv.dev - OSV vulnerability database
ossf.github.io/osv-schema/ - OSV schema
snyk-test, dependabot-config, renovate-config, npm-pip-maven-audit - sister tools
syft-generation - cross-plugin SBOM source

Deep reference for the osv-scanner SKILL.md. SKILL.md keeps install, the recursive/per-lockfile scan, output formats, SBOM input, exit codes, and a minimal ignore snippet; this file holds the full osv-scanner.toml schema, the justification template, and the GitHub Actions workflow.

Full `osv-scanner.toml` schema

Point the scanner at a config with --config (osv-usage (opens in new window)):

osv-scanner --config ./my-osv-scanner-config.toml scan -r .

# osv-scanner.toml
[[IgnoredVulns]]
id = "CVE-2024-1234"
ignoreUntil = 2026-12-15T00:00:00Z
reason = "Reachability analysis confirms unreachable; tracked in JIRA-1234"

[[IgnoredVulns]]
id = "GHSA-xxxx-yyyy-zzzz"
ignoreUntil = 2026-09-30T00:00:00Z
reason = "Vendor-supplied; pin to current version pending Q3 upgrade"

[[PackageOverrides]]
name = "lodash"
version = "4.17.20"
ecosystem = "npm"
ignore = true   # Suppress all vulns in this exact pinned version
reason = "Test fixture; not in production dependency graph"

Suppression layers and justification

Three suppression layers:

Mechanism	Where	Use
`[[IgnoredVulns]]` in osv-scanner.toml (with `ignoreUntil`)	Repo root	Per-CVE; auditable in git
`[[PackageOverrides]]` in osv-scanner.toml	Repo root	Per-package version + ecosystem
`--severity-threshold` filter (when supported by version)	CI flag	Scan-time filter, not suppression

Justification is mandatory in osv-scanner.toml:

[[IgnoredVulns]]
id = "CVE-2024-1234"
ignoreUntil = 2026-12-15T00:00:00Z
reason = """
Reachability: function `vulnerable_func` not exported; verified via
git grep + dynamic instrumentation. Issue requires admin context
which is separately controlled.
Approved-by: alice@example.com
Re-review-date: 2026-09-15
"""

ignoreUntil is enforced by osv-scanner - past-due ignores are re-surfaced in the scan results. Cadence: every quarter, list all [[IgnoredVulns]] entries + re-validate the reason; expired ones removed, persistent ones escalated to upgrade work.

GitHub Actions CI

The google/osv-scanner-action GHA wraps the Docker invocation + SARIF upload:

jobs:
  osv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: google/osv-scanner-action/osv-scanner-action@v1
        with:
          scan-args: |-
            --recursive
            --skip-git
            --format=sarif
            --output=osv.sarif
            ./
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: osv.sarif }