Offline Mode

Experimental

Table of contents

• Offline Mode
  • Specify database location
  • Offline option
  • Local database option
  • Manual database download
  • Limitations

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.

This feature is experimental and might change or be removed with only a minor version update.

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:

{local_db_dir}/
  osv-scanner/
    npm/all.zip
    PyPI/all.zip
    …
    {ecosystem}/all.zip

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.

Limitations

1. Commit level scanning is not supported.