2026-11-18 15:08:53 +00:00
2026-11-18 15:08:53 +00:00
2026-11-18 13:30:38 +00:00
2026-11-18 13:30:38 +00:00
2026-11-18 15:08:53 +00:00
2026-11-18 13:30:38 +00:00
2026-11-18 15:08:53 +00:00
2026-11-18 13:30:38 +00:00
2026-11-18 13:30:38 +00:00
2026-11-18 13:30:38 +00:00

@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 aliases and upstream (never related); the group key is the single CVE id, else the first record id.
  • kind: malicious for OpenSSF Malicious Packages records (MAL-), else vulnerability.
  • 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, stale and 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 (one affected[] entry and one version), sortVersions, attributeRecord, recordDatabase, databaseTerms.
  • Severity: scoreCvssVector, rateRecord, mostSevere, levelFromScore.
  • Store: FilesystemStore (getState, getSnapshot, readOsvRecords, readKevEntries, syncOsv, syncKev), IMirrorReader for 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.csv and <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.

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.

S
Description
Offline advisory mirror (OSV, CISA KEV), version comparators and matching for umbrella.zone.
Readme MIT
253 KiB
0 Stars 3 Watchers 0 Forks
Languages
TypeScript 100%