README
¶
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:
- Languages: C/C++, Dart, Elixir, Go, Java, Javascript, PHP, Python, R, Ruby, Rust.
- Package Managers: npm, pip, yarn, maven, go modules, cargo, gem, composer, nuget and others.
- Operating Systems: Detects vulnerabilities in OS packages on Linux systems.
- Containers: Scans container images for vulnerabilities in their base images and included packages.
- Guided Remediation: Provides recommendations for package version upgrades based on criteria such as dependency depth, minimum severity, fix strategy, and return on investment.
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:
- Covering most open source language and OS ecosystems (including Git), it’s comprehensive.
- Each advisory comes from an open and authoritative source (e.g. GitHub Security Advisories, RustSec Advisory Database, Ubuntu security notices)
- Anyone can suggest improvements to advisories, resulting in a very high quality database.
- The OSV format unambiguously stores information about affected versions in a machine-readable format that precisely maps onto a developer’s list of packages
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 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
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)
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
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
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
osv-reporter
Package main implements the osv-reporter command, which generates GitHub Action output for OSV scanner results.
|
Package main implements the osv-reporter command, which generates GitHub Action output for OSV scanner results. |
|
osv-scanner/fix
Package fix implements the `fix` command for osv-scanner.
|
Package fix implements the `fix` command for osv-scanner. |
|
osv-scanner/internal/cmd
Package cmd provides helper functions for the osv-scanner CLI commands.
|
Package cmd provides helper functions for the osv-scanner CLI commands. |
|
osv-scanner/internal/helper
Package helper provides helper functions for the osv-scanner CLI.
|
Package helper provides helper functions for the osv-scanner CLI. |
|
osv-scanner/internal/testcmd
Package testcmd provides utilities for testing osv-scanner CLI commands.
|
Package testcmd provides utilities for testing osv-scanner CLI commands. |
|
osv-scanner/scan
Package scan implements the `scan` command for osv-scanner.
|
Package scan implements the `scan` command for osv-scanner. |
|
osv-scanner/scan/image
Package image implements the `image` subcommand of the `scan` command.
|
Package image implements the `image` subcommand of the `scan` command. |
|
osv-scanner/scan/source
Package source implements the `source` subcommand of the `scan` command.
|
Package source implements the `source` subcommand of the `scan` command. |
|
osv-scanner/update
Package update implements the `update` command for osv-scanner.
|
Package update implements the `update` command for osv-scanner. |
|
internal
|
|
|
cachedregexp
Package cachedregexp provides a cached version of regexp.MustCompile.
|
Package cachedregexp provides a cached version of regexp.MustCompile. |
|
ci
Package ci provides utility functions for CI integration.
|
Package ci provides utility functions for CI integration. |
|
clients/clientimpl/baseimagematcher
Package baseimagematcher implements a client for matching base images using the deps.dev API.
|
Package baseimagematcher implements a client for matching base images using the deps.dev API. |
|
clients/clientimpl/licensematcher
Package licensematcher implements a client for matching licenses using the deps.dev API.
|
Package licensematcher implements a client for matching licenses using the deps.dev API. |
|
clients/clientimpl/localmatcher
Package localmatcher implements a vulnerability matcher that uses a local database downloaded from osv.dev's export bucket.
|
Package localmatcher implements a vulnerability matcher that uses a local database downloaded from osv.dev's export bucket. |
|
clients/clientimpl/osvmatcher
Package osvmatcher implements two vulnerability matcher using osv.dev's API.
|
Package osvmatcher implements two vulnerability matcher using osv.dev's API. |
|
clients/clientinterfaces
Package clientinterfaces defines interfaces for external accessors used in osv-scanner.
|
Package clientinterfaces defines interfaces for external accessors used in osv-scanner. |
|
cmdlogger
Package cmdlogger provides wrapper for slog logging commands.
|
Package cmdlogger provides wrapper for slog logging commands. |
|
config
Package config manages the configuration for osv-scanner.
|
Package config manages the configuration for osv-scanner. |
|
datasource
Package datasource provides data sources for dependency resolution used by transitive scanning and guided remediation.
|
Package datasource provides data sources for dependency resolution used by transitive scanning and guided remediation. |
|
depsdev
Package depsdev contains constants and mappings for the deps.dev API.
|
Package depsdev contains constants and mappings for the deps.dev API. |
|
grouper
Package grouper groups vulnerabilities by aliases, then sorts them.
|
Package grouper groups vulnerabilities by aliases, then sorts them. |
|
identifiers
Package identifiers provides functions for sorting vulnerability identifiers.
|
Package identifiers provides functions for sorting vulnerability identifiers. |
|
imodels
Package imodels defines internal models for osv-scanner.
|
Package imodels defines internal models for osv-scanner. |
|
imodels/ecosystem
Package ecosystem provides a parser and mappings for ecosystem strings.
|
Package ecosystem provides a parser and mappings for ecosystem strings. |
|
imodels/results
Package results defines the data structures for scan results.
|
Package results defines the data structures for scan results. |
|
output
Package output provides functionality for printing scan results in various formats.
|
Package output provides functionality for printing scan results in various formats. |
|
output/sbom
Package sbom provides functionality to generate SBOMs from scan results.
|
Package sbom provides functionality to generate SBOMs from scan results. |
|
remediation
Package remediation provides logic for Guided Remediation.
|
Package remediation provides logic for Guided Remediation. |
|
remediation/relax
Package relax provides functionality for relaxing version constraints for guided remediation.
|
Package relax provides functionality for relaxing version constraints for guided remediation. |
|
remediation/suggest
Package suggest provides functionality for suggesting version updates.
|
Package suggest provides functionality for suggesting version updates. |
|
remediation/upgrade
Package upgrade provides functionality for parsing upgrade configurations for remediation.
|
Package upgrade provides functionality for parsing upgrade configurations for remediation. |
|
reporter
Package reporter provides functionality for reporting scan results in various formats.
|
Package reporter provides functionality for reporting scan results in various formats. |
|
resolution
Package resolution provides functionality for resolving dependencies and vulnerabilities.
|
Package resolution provides functionality for resolving dependencies and vulnerabilities. |
|
resolution/client
Package client defines the clients for resolving dependencies for various ecosystems.
|
Package client defines the clients for resolving dependencies for various ecosystems. |
|
resolution/clienttest
Package clienttest provides a mock resolution client for testing.
|
Package clienttest provides a mock resolution client for testing. |
|
resolution/depfile
Package depfile provides a temporary abstraction for files that have been opened for extraction.
|
Package depfile provides a temporary abstraction for files that have been opened for extraction. |
|
resolution/lockfile
Package lockfile provides functionality for reading and writing lockfiles.
|
Package lockfile provides functionality for reading and writing lockfiles. |
|
resolution/manifest
Package manifest provides functionality for reading and writing manifest files.
|
Package manifest provides functionality for reading and writing manifest files. |
|
resolution/util
Package util provides utility functions for dependency resolution.
|
Package util provides utility functions for dependency resolution. |
|
scalibrenricher/govulncheck/source
Package source provides an enricher that uses govulncheck to scan Go source code.
|
Package source provides an enricher that uses govulncheck to scan Go source code. |
|
scalibrextract
Package scalibrextract provides functions to easily use scalibr extractors within osv-scanner.
|
Package scalibrextract provides functions to easily use scalibr extractors within osv-scanner. |
|
scalibrextract/filesystem/vendored
Package vendored provides an extractor for vendored C/C++ code.
|
Package vendored provides an extractor for vendored C/C++ code. |
|
scalibrextract/language/java/pomxmlenhanceable
Package pomxmlenhanceable provides an extractor for pom.xml files that can both do offline and transitive scanning.
|
Package pomxmlenhanceable provides an extractor for pom.xml files that can both do offline and transitive scanning. |
|
scalibrextract/language/javascript/nodemodules
Package nodemodules provides an extractor for node_modules directories by reading the .package-lock.json file.
|
Package nodemodules provides an extractor for node_modules directories by reading the .package-lock.json file. |
|
scalibrextract/language/osv/osvscannerjson
Package osvscannerjson extracts osv-scanner's json output.
|
Package osvscannerjson extracts osv-scanner's json output. |
|
scalibrextract/language/python/requirementsenhancable
Package requirementsenhancable provides an extractor for requirements.txt that can both do offline and transitive scanning.
|
Package requirementsenhancable provides an extractor for requirements.txt that can both do offline and transitive scanning. |
|
scalibrextract/vcs/gitrepo
Package gitrepo provides an extractor for git repositories and submodules.
|
Package gitrepo provides an extractor for git repositories and submodules. |
|
scalibrplugin
Package scalibrplugin provides functions related to resolving scalibr plugins
|
Package scalibrplugin provides functions related to resolving scalibr plugins |
|
sourceanalysis
Package sourceanalysis provides functionality for performing source analysis on code.
|
Package sourceanalysis provides functionality for performing source analysis on code. |
|
sourceanalysis/govulncheck
Package govulncheck provides data structures for govulncheck results.
|
Package govulncheck provides data structures for govulncheck results. |
|
spdx
Code generated by gen.go.
|
Code generated by gen.go. |
|
testlogger
Package testlogger provides a slog handler which can handle t.Parallel() tests while being a global logging handler, redirecting it to the correct underlying logger for each test thread.
|
Package testlogger provides a slog handler which can handle t.Parallel() tests while being a global logging handler, redirecting it to the correct underlying logger for each test thread. |
|
testutility
Package testutility provides utility functions for tests.
|
Package testutility provides utility functions for tests. |
|
thirdparty/xml
Package xml implements a simple XML 1.0 parser that understands XML name spaces.
|
Package xml implements a simple XML 1.0 parser that understands XML name spaces. |
|
tui
Package tui provides a terminal user interface for guided remediation.
|
Package tui provides a terminal user interface for guided remediation. |
|
url
Package url provides functionality for converting file paths to file URLs.
|
Package url provides functionality for converting file paths to file URLs. |
|
utility/depgroup
Package depgroups provides functionality for working with dependency groups.
|
Package depgroups provides functionality for working with dependency groups. |
|
utility/maven
Package maven provides utility functions for working with Maven projects.
|
Package maven provides utility functions for working with Maven projects. |
|
utility/purl
Package purl provides functionality for working with PURLs.
|
Package purl provides functionality for working with PURLs. |
|
utility/results
Package results provides utility functions for working with scan results.
|
Package results provides utility functions for working with scan results. |
|
utility/semverlike
Package semverlike provides functionality to parse and compare version strings that are similar to semantic versioning, but with more flexibility.
|
Package semverlike provides functionality to parse and compare version strings that are similar to semantic versioning, but with more flexibility. |
|
utility/severity
Package severity provides functionality for calculating vulnerability severity.
|
Package severity provides functionality for calculating vulnerability severity. |
|
utility/vulns
Package vulns provides utility functions for working with vulnerabilities.
|
Package vulns provides utility functions for working with vulnerabilities. |
|
version
Package version stores the version of osv-scanner.
|
Package version stores the version of osv-scanner. |
|
pkg
|
|
|
models
Package models provides data models for osv-scanner.
|
Package models provides data models for osv-scanner. |
|
osvscanner
Package osvscanner provides the main logic for the OSV-Scanner.
|
Package osvscanner provides the main logic for the OSV-Scanner. |
|
osvscanner/internal/imagehelpers
Package imagehelpers provides helper functions for working with container images.
|
Package imagehelpers provides helper functions for working with container images. |
|
osvscanner/internal/scanners
Package scanners provides functionality for scanning lockfiles.
|
Package scanners provides functionality for scanning lockfiles. |
|
scripts
|
|
|
generate_mock_resolution_universe
Package main generates a mock resolution universe file for testing.
|
Package main generates a mock resolution universe file for testing. |
Click to show internal directories.
Click to hide internal directories.