How to use Google OSV Scanner

December 16, 2022

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.lock
  • package-lock.json
  • yarn.lock
  • pnpm-lock.yaml
  • composer.lock
  • Gemfile.lock
  • go.mod
  • mix.lock
  • poetry.lock
  • pubspec.lock
  • pom.xml*
  • requirements.txt*
  • gradle.lockfile
  • buildscript-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

Recommended content

Comments

Leave your comment