How to use Google OSV Scanner
December 16, 2022
- Categories
- Security
- OSS
- OSV Scanner
3 days ago (December 13th 2022) Google launched the Open Source Vulnerability (OSV) Scanner, a free tool that gives open source developers easy access to vulnerability information relevant to their project.
The problem
Software projects are commonly built on top of a mountain of dependencies—external software libraries you incorporate into a project to add functionalities without developing them from scratch. Each dependency potentially contains existing known vulnerabilities or new vulnerabilities that could be discovered at any time. There are simply too many dependencies and versions to keep track of them manually, so automation is required.
Scanners provide this automated capability by matching your code and dependencies against lists of known vulnerabilities and notifying you if patches or updates are needed. Scanners bring incredible benefits to project security, which is why the 2021 U.S. Executive Order for Cybersecurity included this type of automation as a requirement for national standards on secure software development.
History
I want to remind you that last year Google improved vulnerability triage for developers and consumers of open source software by publishing the Open Source Vulnerability schema and launching the OSV.dev service which is the first distributed open source vulnerability database that allows all the different open source ecosystems and vulnerability databases to publish and consume information in one simple, precise, and machine readable format (JSON). The OSV project has made lots of progress from the last year. The OSV schema has seen significant adoption from vulnerability databases such as GitHub Security Advisories and Android Security Bulletins. Altogether OSV.dev now supports 16 ecosystems, including all major language ecosystems, Linux distributions (Debian and Alpine), as well as Android, Linux Kernel, and OSS-Fuzz. This means the OSV.dev database is now the BIGGEST open source vulnerability database of its kind, with a total of over 38,000 advisories from 15,000 advisories a year ago.
The OSV-Scanner is the next step. It is providing an officially supported frontend to the OSV database that connects a project’s list of dependencies with the vulnerabilities that affect them.
OSV Scanner
The OSV-Scanner generates reliable, high-quality vulnerability information that closes the gap between a developer’s list of packages and the information in vulnerability databases. Since the OSV.dev database is open source and distributed, it has several benefits in comparison with closed source advisory databases and scanners:
- Each advisory comes from an open and authoritative source (e.g. the RustSec Advisory Database)
- 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 fewer, more actionable vulnerability notifications, which reduces the time needed to resolve them
Running OSV-Scanner on your project will first find all the transitive dependencies that are being used by analyzing manifests, SBOMs, and commit hashes. The scanner then connects this information with the OSV database and displays the vulnerabilities relevant to your project.
How to install OSV Scanner
There are two options to run OSV Scanner against your project.
Install OSV Scanner locally
The first option to run OSV Scanner is to install it in your environment and use it as a CLI tool.
You can download the SLSA3 compliant binaries for Linux, macOS, and Windows from official releases page.
Alternatively, you can install it from source by running:
$ go install github.com/google/osv-scanner/cmd/osv-scanner@v1
This command requires Go 1.18+ to be installed.
Use Docker container
This is the easiest way to use OSV-Scanner because you don't need to install Go or OSV-Scanner in your environment. However Docker is required but you can install Docker easily and very fast on Linux or Windows.
Because Google does not provide an official container image for OSV Scanner yet, I created a daily job to publish a container image for the latest release of OSV-Scanner to Docker Hub. By using this image with the tag latest, you will be sure that you are always using the latest version of OSV Scanner. It is also possible to use a specific version tag if needed.
Run the next command to pull a container image to your local cache:
$ docker pull anmalkov/osv-scanner
How to use OSV Scanner
Scan a directory
Walks through a list of directories to find:
- Lockfiles
- SBOMs
- git directories for the latest commit hash
which is used to build the list of dependencies to be matched against OSV vulnerabilities.
Can be configured to recursively walk through subdirectories with the --recursive / -r flag.
Searching for git commit hash is intended to work with projects that use git submodules or a similar mechanism where dependencies are checked out as real git repositories.
Examples
Using Docker image:
$ docker run -v /path/to/your/dir:/data anmalkov/osv-scanner -r /data
Using CLI tool:
$ ./osv-scanner -r /path/to/your/dir
Input an SBOM
SPDX and CycloneDX SBOMs using Package URLs are supported. The format is auto-detected based on the input file contents.
Examples
Using Docker image:
$ docker run -v /path/to/your/dir-with-sbom-file:/data anmalkov/osv-scanner --sbom=/data/sbom.json
Using CLI tool:
$ ./osv-scanner --sbom=/path/to/your/sbom.json
Input a lockfile
A wide range of lockfiles are supported by utilizing this lockfile package. This is the current list of supported lockfiles:
Cargo.lockpackage-lock.jsonyarn.lockpnpm-lock.yamlcomposer.lockGemfile.lockgo.modmix.lockpoetry.lockpubspec.lockpom.xml*requirements.txt*gradle.lockfilebuildscript-gradle.lockfile
Examples
Using Docker image:
$ docker run -v /path/to/your/dir-with-your-lock-files:/data anmalkov/osv-scanner --lockfile=/data/first-directory/package-lock.json --lockfile=/data/another-directory/yarn.lock
Using CLI tool:
$ ./osv-scanner --lockfile=/path/to/your/package-lock.json --lockfile=/path/to/another/yarn.lock
JSON output
By default osv-scanner outputs a human readable table. To have osv-scanner output JSON instead, pass the --json flag when calling osv-scanner.
When using the --json flag, only the JSON output will be printed to stdout, with all other outputs being directed to stderr. So to save only the json output to file, you can redirect the output with osv-scanner --json ... > /path/to/file.json
Examples
In the next examples, after the scanning, the result in JSON format will be stored in results.json file.
Using Docker image:
$ docker run -v /path/to/your/dir-with-your-lock-file:/data anmalkov/osv-scanner --lockfile=/data/yarn.lock --json > /path/to/results.json
Using CLI tool:
$ ./osv-scanner --lockfile=/path/to/another/yarn.lock --json > /path/to/results.json
Output Format
{
"results": [
{
"packageSource": {
"path": "/absolute/path/to/go.mod",
// One of: lockfile, sbom, git, docker
"type": "lockfile"
},
"packages": [
{
"Package": {
"name": "github.com/gogo/protobuf",
"version": "1.3.1",
"ecosystem": "Go"
},
"vulnerabilities": [
{
"id": "GHSA-c3h9-896r-86jm",
"aliases": [
"CVE-2021-3121"
],
// ... Full OSV
},
{
"id": "GO-2021-0053",
"aliases": [
"CVE-2021-3121",
"GHSA-c3h9-896r-86jm"
],
// ... Full OSV
}
],
// Grouping based on aliases, if two vulnerability share the same alias, or alias each other,
// they are considered the same vulnerability, and is grouped here under the id field.
"groups": [
{
"ids": [
"GHSA-c3h9-896r-86jm",
"GO-2021-0053"
]
}
]
}
]
},
{
"packageSource": {
"path": "/absolute/path/to/Cargo.lock",
"type": "lockfile"
},
"packages": [
{
"Package": {
"name": "regex",
"version": "1.5.1",
"ecosystem": "crates.io"
},
"vulnerabilities": [
{
"id": "GHSA-m5pq-gvj9-9vr8",
"aliases": [
"CVE-2022-24713"
],
// ... Full OSV
},
{
"id": "RUSTSEC-2022-0013",
"aliases": [
"CVE-2022-24713"
],
// ... Full OSV
}
],
"groups": [
{
"ids": [
"GHSA-m5pq-gvj9-9vr8",
"RUSTSEC-2022-0013"
]
}
]
}
]
}
]
}
What’s next for OSV Scanner?
There’s still a lot to do! Google plan for OSV-Scanner is not just to build a simple vulnerability scanner; they want to build the best vulnerability management tool - something that will also minimize the burden of remediating known vulnerabilities.
Links
- OSV distributed database
- Official OSV Scanner repository
- Docker image for OSV Scanner
- Daily job to publish an OSV container image
Recommended content
-
Azure security announcements - December 9th 2022
December 12, 2022
-
Azure security announcements - November 11th 2022
November 17, 2022
-
Azure security announcements - October 28th 2022
November 04, 2022
-
Azure security announcements - October 14th 2022
October 18, 2022
-
Azure security announcements - October 6th 2022
October 12, 2022
-
Azure Security Announcements - September 30th 2022
October 05, 2022
-
Azure Security Announcements - September 16th 2022
September 20, 2022