OSV

Threat Intelligence

Overview

The OSV connector synchronizes the Open Source Vulnerabilities advisory catalog into the Brinqa platform. Each package ecosystem OSV publishes is its own object type, and every object type maps to the SecurityAdvisory model. A sync downloads the ecosystem's all.zip archive from the public OSV export, walks its entries and maps each OSV record.

Object types are not compiled into the connector. The export publishes its own ecosystem index, so the type set is read from ecosystems.txt when the schema is resolved and one object type is built per ecosystem. An ecosystem added upstream becomes an object type on the next schema resolution with no code change.

Because each ecosystem is its own object type, only the ecosystems that matter to a deployment need to be enabled, and each syncs exactly one archive. The ecosystem attribute on a record is read from its affected packages rather than from the object type it arrived under, and is therefore multi-valued: a record exported under npm can affect packages in PyPI too.

OSV is a vulnerability database rather than a scanner and holds no customer inventory, so this connector contributes advisory definitions only. Correlation to Package and Software assets is performed by the platform against inventory supplied by other connectors.

---

Data retrieved from OSV

Connector Object	Required	Maps to Data Model
Ecosystem Advisory	Yes	Security Advisory

Model relationships

note

For detailed steps on how to view the data retrieved from OSV in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select OSV from the Connector dropdown and provide the following:

Setting	Required	Default	Description
OSV URL	Yes	https://storage.googleapis.com	Base URL of the OSV vulnerability export, e.g https://storage.googleapis.com
Maximum retries	No	5	Maximum number of retry attempts before giving up a request

Authentication

Method

None. The OSV export is public and unauthenticated, so the connector has no credential property.

Endpoint

Method	URL	Purpose
GET	{url}/osv-vulnerabilities/ecosystems.txt	Ecosystem index — the object type set
GET	{url}/osv-vulnerabilities/{ecosystem}/all.zip	One ecosystem's whole export

Both are plain object reads. The Cloud Storage JSON API is not used, so a mirror only has to serve these two objects over HTTP rather than implement a bucket-listing API.

{url} is configurable and defaults to https://storage.googleapis.com, so the connector can be pointed at a mirror. The bucket name is fixed by the OSV project and is not a configuration property.

Ecosystem directory names are used verbatim in the path and percent-encoded by the HTTP layer, so Red Hat is requested as Red%20Hat/all.zip.

Usage

Connectivity is verified by reading osv-vulnerabilities/ecosystems.txt — the same object the object types are derived from, so a successful test also proves the schema can be resolved.

---

Sync Behavior

Every run is a full sync. The connector has no incremental (delta) mode: it hands out no sync token, and a token supplied by the platform is ignored.

A run of one ecosystem object type is a single request:

1. GET {ecosystem}/all.zip, spooled to a temporary file.
2. Walk the archive entry by entry. Entries are flat within an ecosystem — GHSA-222w-xmc5-jhp3.json, not Maven/GHSA-222w-xmc5-jhp3.json.
3. Skip anything that is not a .json record — the only filter the walk applies.
4. Parse each record off the archive stream and hand it to the platform.
5. Delete the temporary file, however the walk ends.

The archive is spooled to disk rather than parsed from the live response. Unpacking a large ecosystem takes minutes, so streaming would hold the connection open for the whole walk and expose it to the read timeout. Spooling also confines the retry to the transfer: a failure mid-download costs another download, never a re-walk of records already handed to the platform.

Memory is bounded by one record regardless of ecosystem size — entries are parsed one at a time off the archive stream, never collected.

No record class is filtered. Malicious package reports, withdrawn records and records no database reviewed are all synced, each carrying the distinction on the object — RECORD_TYPE, WITHDRAWN and REVIEWED — so the platform can act on it rather than the connector deciding for it. Scope is set by which ecosystem object types are enabled.

An entry that cannot be parsed is skipped with a warning. A failed archive download fails the sync, since the archive is the ecosystem's entire content rather than one record.

Duplication across ecosystems

An advisory affecting packages in several ecosystems is exported into each of their directories, so each of those object types emits its own copy. Each type is a separate namespace, so the copies do not collide on the uid; they converge in the target model, where the OSV id is the identifier.

Enabling fewer ecosystems is what keeps this in check. There is no cross-ecosystem deduplication in the connector, because a sync sees only one ecosystem's archive and object types are synced independently.

---

How to obtain OSV credentials

Configure the OSV connector

The OSV connector reads the public OSV vulnerability export — a free, open vulnerability catalog run by Google that aggregates advisories from the GitHub Advisory Database, PyPI, Go, Rust, the Linux distributions and others.

What the connector connects to

Requirement	Detail
Service	OSV — https://osv.dev
Address the connector uses	https://storage.googleapis.com (the default)
Authentication	None. No username, password, API key or token.
Network access required	Outbound HTTPS (port 443) to storage.googleapis.com
Cost or licensing	None. No account or subscription is needed.

OSV publishes its data as public files that anyone can download, which is why there are no credentials to obtain, store or rotate. The only prerequisite is that the platform can reach storage.googleapis.com — if outbound traffic is filtered, have that address allowed before you begin.

Steps

1. Create a new OSV connector instance.

2. Leave OSV URL at its default unless you are pointing the connector at an internal mirror of the OSV export.

3. Select the ecosystems to synchronize. An ecosystem is a software packaging platform — Maven for Java, npm for JavaScript, PyPI for Python, Go, NuGet, RubyGems and so on. The connector reads the ecosystem index from the export and offers one object type per ecosystem, so enable only those your organization builds in — a sync downloads that ecosystem's whole archive, and enabling every one transfers roughly 1.5 GB per run.

Note: Object types are named after the ecosystem directory, with spaces replaced by underscores — Red Hat appears as Red_Hat. The [EMPTY] directory, where OSV exports withdrawn and unclassified records, appears as Withdrawn.

4. Test the connection. The connector verifies connectivity by reading the ecosystem index from the export bucket — the same object the object types are derived from. Since no credentials are involved, a failure here almost always means outbound access to storage.googleapis.com is blocked.

5. Run the sync. Every run is a complete refresh; there is no incremental option, because OSV rebuilds its published archives roughly hourly rather than publishing per-record state to resume from.

Note: An enabled ecosystem synchronizes every record it exports. Malicious package reports from the OSV Malicious Packages database, records withdrawn by their publisher and records no database reviewed are all included; each object carries Record type, Withdrawn and Reviewed so they can be told apart downstream. npm therefore contributes all 226,915 of its records, of which 219,745 are malicious package reports.

For additional information, see the OSV documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Ecosystem Advisory

Source Field Name	SDM Attribute
affected[].database_specific.last_known_affected_version_range	LAST_KNOWN_AFFECTED
affected[].package.ecosystem	ECOSYSTEMS
affected[].package.name	AFFECTED_PACKAGES
affected[].package.purl	PURLS
affected[].package.purl, else affected[].package.name	AFFECTED
affected[].ranges[].events[]	AFFECTED_RANGES
affected[].ranges[].repo	REPOSITORIES
affected[].ranges[].type	RANGE_TYPES
affected[].versions	AFFECTED_VERSIONS
aliases	ALIASES
aliases matching CVE-*	CVE_IDS
aliases matching CVE-*	CVE_RECORDS
constant	VENDOR
credits[].contact	CREDIT_CONTACTS
credits[].name	CREDITS
credits[].type	CREDIT_TYPES
database_specific.cwe_ids	CWE_IDS
database_specific.cwe_ids	WEAKNESSES
database_specific.github_reviewed	REVIEWED
database_specific.github_reviewed_at	REVIEWED_DATE
database_specific.nvd_published_at	NVD_PUBLISHED_DATE
database_specific.severity, else ecosystem_specific.severity, else the band of the highest-version CVSS vector, else the non-CVSS severity[] entry	SOURCE_SEVERITY
derived from fixed events	RECOMMENDATION
derived from SEVERITY	SEVERITY_SCORE
derived from SOURCE_SEVERITY	SEVERITY
details	DESCRIPTION
fixed events	FIXED_VERSIONS
https://osv.dev/vulnerability/{id}	URL
id	UID
id + summary	NAME
id prefix	SOURCE_DATABASE
id prefix	RECORD_TYPE
modified	SOURCE_LAST_MODIFIED
published	PUBLISHED_DATE
references[].type	REFERENCE_TYPES
references[].url	REFERENCES
related, upstream, non-CVE aliases	RELATES_TO
schema_version	SCHEMA_VERSION
severity[] and affected[].severity entries of type CVSS_V2 / CVSS_V3 / CVSS_V4	CVSS_V2_, CVSS_V3_, CVSS_V4_*
severity[].source	CVSS_SOURCES
summary	SUMMARY
sync time	LAST_CAPTURED
withdrawn	WITHDRAWN

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Ecosystem Advisory

Operation options

Option	Type	Default	Description
maxRetries	Integer	the maxRetries configuration	Retry attempts for the archive download on this operation

Delta sync

Not supported. The connector performs a full sync of Ecosystem Advisory on every run and applies no incremental date filter.

API

• Type: REST — plain HTTP object reads: a text index, plus one zip archive per ecosystem · Endpoint: GET /osv-vulnerabilities/{ecosystem}/all.zip
• Default filters: none — every .json entry in the archive is a record and is synced

note

• An advisory affecting more than one ecosystem is exported into each of them, so it arrives once per enabled ecosystem object type. The connector does not deduplicate across ecosystems.
• Every record an enabled ecosystem exports is synced, including malicious package reports, withdrawn records and records no database reviewed. RECORD_TYPE, WITHDRAWN and REVIEWED carry the distinction on each object.

---

Changelog

Changelog

The OSV connector has undergone the following changes:

Version	Description	Migration Steps
3.0.1	Overview The OSV connector integrates with Open Source Vulnerabilities to synchronize the public advisory catalog as security advisory records. Each package ecosystem OSV publishes is offered as its own object type, so a deployment enables only the ecosystems it cares about. Category: Threat Intelligence Models	N/A