Contributing A New Data Source

Data contributions are welcome. OSV.dev readily accepts security related records from open source projects, given they are provided in the OSV format. Publishing records to OSV is straightforward: reserve a prefix in the OSV-Schema, and then prepare and publish your data via a Git repository or other supported method.

The step by step instructions are as follows:

Open an issue using the ‘new data source’ template.
Prepare your data - refer to the OSV Schema documentation for information on how to properly format the data so it can be accepted.
Create a PR to reserve an ID prefix and define a new ecosystem (example). We review the records you start publishing for OSV Schema correctness and quality as part of reviewing and merging this PR.
Prepare and publish your records via a public Git repository (example). If this method isn’t ideal, we also support publishing records through REST API or GCS buckets (example).
To support API querying, if you are contributing a new ecosystem, please create a PR to extend purl_helpers.py and create a new ecosystem in _ecosystems.py. You can refer to existing examples showing how to implement support for Semver and non-Semver ecosystems.
Create a PR to start importing the records you are publishing into our test instance of OSV.dev and validate everything is working as intended there.
After successful import, review the OSV-linter results by querying http://api.test.osv.dev/v1experimental/importfindings/{source_name} to identify and address any important record linting issues (allow up to a 1-day delay).
Create a PR to start importing the records you are publishing into our production environment

source.yaml Examples

Git (preferred)

- name: 
  type: 0   # 0: GIT, 1: GCS, 2: REST
  repo_url:    # The repo URL for the source
  db_prefix: # DB prefix, if the database allocates its own. https://ossf.github.io/osv-schema/#id-modified-fields
  human_link: # HTTP link prefix to individual vulnerability records for humans. 
  link: # HTTP link prefix to individual OSV source records. 
  directory_path: # Vulnerability data not under this path is ignored by the importer.
  extension: '.json' # Default extension.
  ignore_patterns: # Patterns of files to exclude (regex).

Advanced and optional fields

  # Optional
  repo_username:  # The username to use for SSH auth if needed
  repo_branch: # Optional branch for repo
  
  # Default Advanced values
  editable: False # Whether this repository is editable.
  ignore_git: False # If true, don't analyze any Git ranges.
  detect_cherrypicks: False # Whether to detect cherrypicks or not (slow for large repos).
  consider_all_branches: False # Whether to consider all branches when analyzing GIT ranges.
  versions_from_repo: False # Whether to populate "affected[].versions" from Git ranges.
  strict_validation: False # Apply strict validation (JSON Schema + linter checks) to this source.

REST

- name: 
  type: 2 # 0: GIT, 1: GCS, 2: REST
  rest_api_url: # URL pointing to a REST endpoint containing at least all of the vulnerabilities' IDs and date modified
  db_prefix: # DB prefix, as reserved in ossf. https://ossf.github.io/osv-schema/#id-modified-fields
  human_link: # The human readable link
  link:  # The base link
  directory_path: # Vulnerability data not under this path is ignored by the importer
  extension: # Extension for vulnerability data
  ignore_patterns:  # Patterns of files to exclude (regex).

Advanced and optional fields

  detect_cherrypicks: False # Whether to detect cherrypicks or not (slow for large repos)
  ignore_git: False # If true, don't analyze any Git ranges.
  editable: False # Whether this repository is editable.
  versions_from_repo: False # Whether to populate "affected[].versions" from Git ranges.
  strict_validation: False # Apply strict validation (JSON Schema + linter checks) to this source.

GCS

- name: 
  type: 1 # 0: GIT, 1: GCS, 2: REST
  bucket:  # Bucket name
  db_prefix:  # DB prefix, as reserved in ossf. https://ossf.github.io/osv-schema/#id-modified-fields
  human_link:  # The human readable link
  link:  # The base link
  directory_path: # Vulnerability data not under this path is ignored by the importer
  extension: '.json' # Extension for vulnerability data
  ignore_patterns: # Patterns of files to exclude (regex).

Advanced and optional fields

  detect_cherrypicks: False # Whether to detect cherrypicks or not (slow for large repos)
  ignore_git: False # If true, don't analyze any Git ranges.
  editable: False # Whether this repository is editable.
  versions_from_repo: False # Whether to populate "affected[].versions" from Git ranges.
  strict_validation: False # Apply strict validation (JSON Schema + linter checks) to this source.

Do you have a question, suggestion or feedback? Please open an issue.

via REST API

Contributing A New Data Source

Git (preferred)

REST

GCS

Table of contents