Experimental Features

Table of contents

Features and flags with the experimental prefix might change or be removed with only a minor version update.

Offline mode

OSV-Scanner now supports offline scanning as an experimental feature. Offline scanning checks your project against a local database instead of calling the OSV.dev API.

Specify database location

Our offline features require the use of a local database, the location of which is determined through the use of the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable.

The local database file structure is in this form:


Where {local_db_dir} can be set by the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable.

If the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable is not set, OSV-Scanner will attempt to look for the database in the following locations, in this order:

  1. The location returned by os.UserCacheDir
  2. The location returned by os.TempDir

The database can be downloaded manually or by using the --experimental-local-db flag.

Offline option

The offline database flag --experimental-offline causes OSV-Scanner to scan your project against a previously downloaded local database. OSV-Scanner will not download or update the local database, nor will it send any project or dependency information anywhere. When a local database is not present, you will get an error message. No network connection is required when using this flag.

osv-scanner --experimental-offline ./path/to/your/dir

Local database option

The local database flag --experimental-local-db causes OSV-Scanner to download or update your local database and then scan your project against it.

osv-scanner --experimental-local-db ./path/to/your/dir

Manual database download

Instead of using the --experimental-local-db flag to download the database, it is possible to manually download the database.

A downloadable copy of the OSV database is stored in a GCS bucket maintained by OSV: gs://osv-vulnerabilities

This bucket contains zip files containing all vulnerabilities for each ecosystem at: gs://osv-vulnerabilities/<ECOSYSTEM>/all.zip.

E.g. for PyPI vulnerabilities:

gsutil cp gs://osv-vulnerabilities/PyPI/all.zip .

You can also download over HTTP via https://osv-vulnerabilities.storage.googleapis.com//all.zip .

A list of all current ecosystems is available at gs://osv-vulnerabilities/ecosystems.txt.

Set the location of your manually downloaded database by following the instructions here.


  1. Commit level scanning is not supported.

License scanning

OSV-Scanner supports license checking as an experimental feature. The data comes from the deps.dev API.

License summary

If you want a summary of your dependencies licenses, use the --experimental-licenses-summary flag:

osv-scanner --experimental-licenses-summary path/to/repository

License violations

To set an allowed license list and see the details of packages that do not conform, use the --experimental-licenses flag:

osv-scanner --experimental-licenses="comma-separated list of allowed licenses" path/to/directory

Include your allowed licenses as a comma-separated list. OSV-Scanner recognizes licenses in SPDX format. Please indicate your allowed licenses using SPDX license identifiers.

License violations example

If you wanted to allow the following licenses:

Your command would be in this form:

osv-scanner --experimental-licenses="BSD-3-Clause,Apache-2.0,MIT" path/to/directory