osv-scanner README

The project's README from github.com/google/osv-scanner. As one markdown file: README.md.

OpenSSF Scorecard Checks codecov SLSA 3 GitHub Release

Use OSV-Scanner to find existing vulnerabilities affecting your project's dependencies. OSV-Scanner provides an officially supported frontend to the OSV database and CLI interface to OSV-Scalibr that connects a project’s list of dependencies with the vulnerabilities that affect them.

OSV-Scanner supports a wide range of project types, package managers and features, including but not limited to:

OSV-Scanner uses the extensible OSV-Scalibr library under the hood to provide this functionality. If a language or package manager is not supported currently, please file a feature request.

Underlying database

The underlying database, OSV.dev has several benefits in comparison with closed source advisory databases and scanners:

The above all results in accurate and actionable vulnerability notifications, which reduces the time needed to resolve them. Check out OSV.dev for more details!

Basic installation

To install OSV-Scanner, please refer to the installation section of our documentation. OSV-Scanner releases can be found on the releases page of the GitHub repository. The recommended method is to download a prebuilt binary for your platform. Alternatively, you can use go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest to build it from source.

Key Features

For more information, please read our detailed documentation to learn how to use OSV-Scanner. For detailed information about each feature, click their titles in this README.

Please note: These are the instructions for the latest OSV-Scanner V2 beta. If you are using V1, checkout the V1 README and documentation instead.

Scanning a source directory

$ osv-scanner scan source -r /path/to/your/dir

This command will recursively scan the specified directory for any supported package files, such as package.json, go.mod, pom.xml, etc. and output any discovered vulnerabilities.

OSV-Scanner has the option of using call analysis to determine if a vulnerable function is actually being used in the project, resulting in fewer false positives, and actionable alerts.

OSV-Scanner can also detect vendored C/C++ code for vulnerability scanning. See here for details.

Supported Lockfiles

OSV-Scanner supports 11+ language ecosystems and 19+ lockfile types. To check if your ecosystem is covered, please check out our detailed documentation.

Container Scanning

OSV-Scanner also supports comprehensive, layer-aware scanning for container images to detect vulnerabilities in the following operating system packages and language-specific dependencies.

Distro Support Language Artifacts Support
Alpine OS Go
Debian Java
Ubuntu Node
Python

See the full documentation for details on support.

Usage:

$ osv-scanner scan image my-image-name:tag

screencast of html output of container scanning

License Scanning

Check your dependencies' licenses using deps.dev data. For a summary:

osv-scanner --licenses path/to/repository

To check against an allowed license list (SPDX format):

osv-scanner --licenses="MIT,Apache-2.0" path/to/directory

Offline Scanning

Scan your project against a local OSV database. No network connection is required after the initial database download. The database can also be manually downloaded.

osv-scanner --offline --download-offline-databases ./path/to/your/dir

Guided Remediation (Experimental)

[!WARNING] Guided remediation (the fix command) can be risky when run on untrusted projects. It may trigger the package manager to execute scripts or follow external registries specified in the project. Please ensure you trust the source code and artifacts before proceeding.

OSV-Scanner provides guided remediation, a feature that suggests package version upgrades based on criteria such as dependency depth, minimum severity, fix strategy, and return on investment. We currently support remediating vulnerabilities in the following files:

Ecosystem File Format (Type) Supported Remediation Strategies
npm package-lock.json (lockfile) in-place
npm package.json (manifest) relock
Maven pom.xml (manifest) override

This is available as a headless CLI command, as well as an interactive mode.

Example (for npm)

$ osv-scanner fix \
    --max-depth=3 \
    --min-severity=5 \
    --ignore-dev  \
    --strategy=in-place \
    -L path/to/package-lock.json

Interactive mode (for npm)

$ osv-scanner fix \
    -M path/to/package.json \
    -L path/to/package-lock.json
Screenshot of the interactive relock results screen with some relaxation patches selected

Data Sources and Privacy

OSV-Scanner communicates with the following external services during operation:

OSV.dev API

The primary data source for vulnerability information. OSV-Scanner queries this API to check packages for known vulnerabilities and to identify vendored C/C++ dependencies. Data sent includes package names, versions, ecosystems, and file hashes. Use --offline mode to disable network requests and scan against a local database instead.

deps.dev API

Used for supplementary package information:

Data sent includes package names, versions, and ecosystems. No source code is transmitted.

Package Registries

When using native registry for dependency resolution (instead of deps.dev), OSV-Scanner may query:

Registry URL Used For
Maven Central repo.maven.apache.org/maven2 Maven package metadata and POM files
npm Registry registry.npmjs.org npm package metadata
PyPI pypi.org Python package metadata

Contribute

Report Problems

If you have what looks like a bug, please use the GitHub issue tracking system. Before you file an issue, please search existing issues to see if your issue is already covered.

Contributing code to osv-scanner

See CONTRIBUTING.md for documentation on how to contribute code.

Star History

Star History Chart

osv-scanner (google/osv-scanner)

vulnerability-scanner
Searching Database…

11.2K ·GitHub
Osv-scanner
What is this?OSV-Scanner is Google's open-source command-line vulnerability scanner: it checks your project's dependencies against OSV.dev, an open vulnerability database, and reports which known vulnerabilities affect you.
Is it a library I add to my codebase, or a separate tool I run?It is a standalone CLI tool written in Go, not a library you import — you point it at a project directory or container image and it reports findings. Internally it uses the OSV-Scalibr library to detect dependencies.
Do I need anything else installed for it to scan my project?No, just the scanner binary — it reads your existing package files like package.json, go.mod and pom.xml. It covers 11+ language ecosystems and 19+ lockfile types: npm, pip, yarn, maven, go modules, cargo, gem, composer, nuget and more, plus Linux OS packages.
Will it flag vulnerabilities my code never actually uses?Possibly — to cut that noise, OSV-Scanner offers optional call analysis that checks whether a vulnerable function is really used in your project, resulting in fewer false positives and more actionable alerts.
Can I use it without internet access?Yes. In offline mode it scans your project against a local OSV database: after the initial database download no network connection is required, and the database can also be downloaded manually.
What does it send over the network when I scan?It queries the OSV.dev API, sending package names, versions, ecosystems and file hashes, plus the deps.dev API for supplementary package info — no source code is transmitted. Run it with --offline to disable network requests entirely.
Can it scan Docker images, not just source lockfiles?Yes — it does layer-aware container scanning, finding vulnerable OS packages in Alpine, Debian and Ubuntu base images, plus Go, Java, Node and Python language dependencies inside the image.
How good is the vulnerability data it relies on?OSV.dev aggregates advisories from open, authoritative sources like GitHub Security Advisories, the RustSec Advisory Database and Ubuntu security notices. Anyone can suggest improvements, and the machine-readable OSV format maps affected versions precisely onto your package list.
Can it also check the licenses of my dependencies?Yes — a license scanning mode uses deps.dev data, either as a summary or checked against your own allowlist of licenses in SPDX format.
What are similar projects?grype, oss-scanner, semgrep, gitleaks, trivy, fscan, nuclei, clair
Which topics is it in?dependencies, supply-chain-security, scanner, security-audit, devsecops, vulnerability-scanner, vulnerability, containers, google, security-tools, offline, go
Creator
google
Size
44.6 MB
Stars
11.2K
Updated
CommitOct 12Releasev2.7.0Oct 12
Age
3y
Commits · 90 Days