2026-11-18 12:38:50 +00:00
2026-11-18 12:38:50 +00:00
2026-11-18 12:35:50 +00:00
2026-11-18 12:35:50 +00:00
2026-11-18 12:38:50 +00:00
2026-11-18 12:35:50 +00:00
2026-11-18 12:38:50 +00:00
2026-11-18 12:35:50 +00:00
2026-11-18 12:35:50 +00:00

@umbrella.zone/interfaces

Shared TypeScript contracts of umbrella.zone, the self-hostable, open-source supply-chain security platform for the foss.global stack: component inventories with coverage, the OSV record and the KEV catalog as read, advisory feed state and attribution, findings, policies and scan reports.

This package intentionally contains contracts only: types plus four constants. Lockfile readers belong in @umbrella.zone/inventory, the advisory mirror, matching and policy evaluation in @umbrella.zone/advisorydb, and the command line in @umbrella.zone/uzscan.

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/interfaces

Usage

import { actionOrder, severityOrder } from '@umbrella.zone/interfaces';
import type { IFinding, IPolicyRule, TPolicyAction, TSeverityLevel } from '@umbrella.zone/interfaces';

// Policies compare `countedAs`, never `level`: an unknown severity counts as high.
const atLeast = (findingArg: IFinding, levelArg: TSeverityLevel) =>
  severityOrder[findingArg.severity.countedAs] >= severityOrder[levelArg];

// The strictest matching action wins.
const strictest = (actionsArg: TPolicyAction[]): TPolicyAction =>
  actionsArg.reduce((a, b) => (actionOrder[b] > actionOrder[a] ? b : a), 'ignore');

const blockCritical: IPolicyRule = {
  id: 'critical',
  title: 'Critical vulnerability',
  when: { severityAtLeast: 'critical' },
  action: 'block',
};

Every type is also reachable through the data namespace (import type { data } from '@umbrella.zone/interfaces', then data.IScanReport).

Inventory contracts

IInventory is one lockfile read into components: its subject (pnpm-lock@9, npm-lock@2 or npm-lock@3, the file as given and the sha256: digest of its bytes), the components, the coverage gaps, the time and the producing tool. A component (IComponent) is one installed package version, unique by its purl (pkg:npm/%40acme/logweave@5.0.0): its OSV ecosystem and name, version, whether an importer declares it directly, the scopes it is reached through (prod, dev, optional, peer), up to componentPathLimit (5) shortest dependency paths as lists of purls, the lockfile's resolved and integrity, and the importers that reach it. Peer variants and nested copies of one version are one component; an aliased dependency is the package it installs.

ICoverageGap is something a scan did not cover, reported instead of dropped. The inventory stage records git, https, file: and link: references (a link to a workspace member is covered through that member's importer), references it does not know (unsupported) and entries it cannot parse (unparsed). The matching stage records components it could not check (unsupported): no comparator, no mirrored source, or an advisory range it cannot evaluate.

Advisory contracts

IOsvRecord is an OSV record as read from an OSV export, written for OSV schema 1.7 and checked against 1.9.2: snake_case as in the schema, list fields that may be null, range events typed as exactly one of introduced, fixed, last_affected and limit, and the 1.8 severity source. IKevCatalog is CISA's Known Exploited Vulnerabilities catalog as read from its JSON feed. Both describe data as it arrives, not validated data. Their text fields (summary, details, references, credits, KEV descriptions) are untrusted: they are never interpreted and never used to compose a title, log line, reason or notice.

IFeedSource names a mirrored feed (osv:<ecosystem> or kev), where a sync reads it, its licence and attribution, and whether it is used for matching or only enrichment. IFeedState is the mirror's state of one source (never, syncing, current, stale, failed) with the generation in use, its sync times, the last error, the record count and the age after which it counts as stale. IMirrorSnapshot holds the states a scan used. IRecordAttribution carries one record's source, home database (GHSA, MAL, …), licence and required notice.

Finding, policy and report contracts

IFinding is one vulnerability affecting one component: its key (groupKey|purl), the group key (the single CVE alias, else the first OSV id), the grouped record ids and their other aliases, the component with its scopes and paths, its kind (malicious or vulnerability), severity, KEV exploited flag, fixed versions, withdrawn and stale flags, and the attribution of every record.

ISeverity is either rated (cvss-v4, cvss-v3, cvss-v2 or database, with its level, score and vector) or unknown: an unknown severity has no level and always counts as high. severityOrder ranks the levels for comparison.

IPolicy is a named list of IPolicyRules. A rule's when is one of three shapes: conditions on a finding (kind, severityAtLeast, exploited, scopes, ecosystems), { staleMirror: true } (a source the scan used is stale or failed) or { coverageGap: true } (the scan has a gap). IPolicyDecision is blocked when any match blocks, warned when any warns, else passed, with every match listed by subject; actionOrder ranks the actions.

IScanReport is the result of one offline scan: the tool and time, the inventory's subject, component count and every gap, the mirror snapshot, the findings (malicious first, then by severity), the policy as applied with its decision, and the exit code (scanExitCodes: 0 passed or warned, 1 could not run, 2 blocked).

Data sources and licences

This package holds no advisory data. It defines how a mirror records each source's terms (IFeedSource.licence and attribution) and how every finding carries the terms of its records (IRecordAttribution). The OSV export has no licence for the whole: each record keeps its home database's licence, for example CC-BY-4.0 for the GitHub Advisory Database and Apache-2.0 for OpenSSF Malicious Packages. Exports carry the notices those licences require.

Exports

  • data: every type and constant below, as a namespace.
  • Root exports: the same, flat.
  • Constants: severityOrder, actionOrder, componentPathLimit, scanExitCodes.
  • Inventory: IInventory, IInventorySubject, IComponent, IComponentLocation, ICoverageGap, TLockfileFormat, TComponentScope, TCoverageGapKind, ITool.
  • Advisory data as read: IOsvRecord, IOsvAffected, IOsvPackage, IOsvRange, IOsvEvent (with IOsvEventIntroduced, IOsvEventFixed, IOsvEventLastAffected, IOsvEventLimit), IOsvSeverity, IOsvReference, IOsvCredit, TOsvRangeType, TOsvSeverityType, TOsvReferenceType, TOsvCreditType, TOsvSpecific, IKevCatalog, IKevVulnerability.
  • Mirror: IFeedSource, IFeedState, IMirrorSnapshot, IRecordAttribution, TFeedKind, TFeedUse, TFeedState.
  • Findings: IFinding, IFindingComponent, IFindingExploited, TFindingKind, ISeverity, ISeverityRated, ISeverityUnknown, TSeverityLevel, TSeveritySource.
  • Policies and reports: IPolicy, IPolicyRule, TPolicyRuleWhen, IPolicyFindingWhen, IPolicyStaleMirrorWhen, IPolicyCoverageGapWhen, IPolicyDecision, TPolicyMatch, IPolicyFindingMatch, IPolicyStaleMirrorMatch, IPolicyCoverageGapMatch, TPolicyAction, TPolicyDecision, IScanReport, IScanReportInventory, IScanReportPolicy, TScanExitCode.

Testing

pnpm test
pnpm exec tsrepo check 'test/**/*'
pnpm run build

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
Shared TypeScript contracts for umbrella.zone: components, inventories, OSV records, findings, policies and reports.
Readme MIT
212 KiB
0 Stars 3 Watchers 0 Forks
Languages
TypeScript 100%