@umbrella.zone/advisorydb
The advisory mirror of umbrella.zone, the self-hostable, open-source supply-chain security platform for the foss.global stack. It mirrors the OSV export per ecosystem and the CISA Known Exploited Vulnerabilities catalog into an atomic filesystem store, compares versions, evaluates OSV ranges, matches component inventories offline, scores CVSS vectors, attributes every record to its source and applies policies.
No dependency list ever leaves the machine: syncs download whole feeds, and matching reads only the local store.
Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.
Install
pnpm add @umbrella.zone/advisorydb
Usage
Sync the mirror
import { FilesystemStore, syncMirror } from '@umbrella.zone/advisorydb';
const store = new FilesystemStore('/var/cache/umbrella.zone/mirror');
// npm from the OSV export (full the first time, then incremental) and the KEV catalog.
const reports = await syncMirror(store, { ecosystems: ['npm'] });
for (const report of reports) {
console.log(report.sourceId, report.ok ? report.result?.mode : report.error);
}
store.syncOsv(ecosystem, options) and store.syncKev(options) sync one source. A failed sync throws SyncError, keeps the last good data and records the failure in the source's state. Chainguard and Wolfi are refused (SourceRefusedError): their licence forbids redistribution and commercial use.
Syncs read the export fresh: on Cloud Storage they take each file's current generation from the JSON API and download exactly that generation, because the bucket's caches serve older copies for up to an hour. The mirror never shrinks and never goes back. A modified_id.csv older than the one applied last is refused, keeping the data in use. Records the export no longer lists are kept, unless OSV moved them to its [EMPTY] folder (records without an ecosystem, typically withdrawn). A record copy older than the one held is never applied. result.notes and the stored state's lastSyncNotes say what happened.
Match an inventory and apply a policy
import { ciPolicy, evaluatePolicy, FilesystemStore, matchInventory, sourceIdsForInventory } from '@umbrella.zone/advisorydb';
import type { IInventory } from '@umbrella.zone/interfaces';
declare const inventory: IInventory; // from @umbrella.zone/inventory
const store = new FilesystemStore('/var/cache/umbrella.zone/mirror');
const snapshot = await store.getSnapshot({ sourceIds: sourceIdsForInventory(inventory) });
const { findings, coverage } = await matchInventory(inventory, { store, snapshot });
const decision = evaluatePolicy(findings, [...inventory.coverage, ...coverage], snapshot, ciPolicy);
console.log(decision.decision); // 'passed' | 'warned' | 'blocked'
matchInventory returns the findings (malicious first, then by severity, then by key) and the matching-stage coverage gaps: components it could not check because their ecosystem has no comparator or no mirrored data, their version cannot be ordered, or an advisory range cannot be evaluated. It reads exactly the generations the snapshot names.
What a finding holds
- Records that affect the component, grouped by
aliasesandupstream(neverrelated); the group key is the single CVE id, else the first record id. kind:maliciousfor OpenSSF Malicious Packages records (MAL-), elsevulnerability.severity: the most severe rating of the group, from each record's own CVSS v4.0 vector, then v3.x (scored here), then its database's level, then CVSS v2; unknown when nothing rates it, counted as high.exploited: whether a CVE id of the group is in the KEV catalog, with the date it was added.fixedIn: the fixed versions above the installed one, ascending.withdrawn,staleand one attribution per record (source, home database, licence, notice).
The ci policy
| Rule | When | Action |
|---|---|---|
malicious |
a known malicious package | block |
critical |
a critical vulnerability | block |
exploited |
a vulnerability in the CISA KEV catalog | block |
vulnerability |
a vulnerability rated low or above (unknown counts as high) | warn |
stale-mirror |
a source the scan used is stale, failed or never synced (KEV counts when the policy relies on exploited) |
warn |
coverage-gap |
the scan has a coverage gap | warn |
The strictest matching action decides; withdrawn findings are never evaluated. A staleMirror rule fails closed: besides a stale or failed source, an OSV source the inventory's ecosystems need that was never synced matches it, and so does a never-synced KEV catalog when the policy has a rule on exploited (mirrorIsStale). Pass the snapshot of the sources the scan used (sourceIdsForInventory). validatePolicy checks policies read from configuration.
Building blocks
- Versions:
semverComparator,compareSemver,isSemverVersion,ComparatorRegistry,defaultComparators,comparatorForRange. Ecosystems without a comparator are reported as coverage gaps; new comparators register in the registry. - OSV:
evaluateAffected(oneaffected[]entry and one version),sortVersions,attributeRecord,recordDatabase,databaseTerms. - Severity:
scoreCvssVector,rateRecord,mostSevere,levelFromScore. - Store:
FilesystemStore(getState,getSnapshot,readOsvRecords,readKevEntries,syncOsv,syncKev),IMirrorReaderfor other stores.
Data sources and licences
- OSV.dev export (https://google.github.io/osv.dev/data/):
https://storage.googleapis.com/osv-vulnerabilities/<ecosystem>/all.zip,modified_id.csvand<id>.json. The export has no licence of its own; every record keeps its home database's licence, and every finding carries it with the notice it requires. For npm (232,645 records on 2026-11-18) these are OpenSSF Malicious Packages (Apache 2.0) and the GitHub Advisory Database (CC BY 4.0), plus single records of the Global Security Database (CC0 1.0) and the Erlang Ecosystem Foundation CNA (CC BY 4.0). Records from Ubuntu and the Alpine SecDB are CC BY-SA 4.0, so exports that contain them are share-alike. Chainguard and Wolfi (CC BY-NC-ND 4.0) are never mirrored. - CISA Known Exploited Vulnerabilities Catalog (https://www.cisa.gov/known-exploited-vulnerabilities-catalog):
https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json, CC0 1.0. It only marks findings as exploited; its use implies no endorsement by CISA or DHS. - CVSS scores are computed with the metæffekt CVSS calculator (
ae-cvss-calculator, Apache 2.0) from the vectors the records state. - Test vectors: the SemVer comparison vectors of OSV-SCALIBR (Apache 2.0, Google LLC) are vendored in
test/vectors/osv-scalibr/with their licence and source.
Testing
pnpm test
pnpm exec tsrepo check 'test/**/*'
pnpm run build
The tests use a local fixture HTTP server and never reach the network.
License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.