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:
{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:
- The location returned by
os.UserCacheDir - 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/
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
- 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