feat: implement OSV format

Author: fraxken

README.md

@@ -102,7 +102,9 @@ export interface ExtendedStrategy<
   ) => Promise<(VulnFormat | StandardVulnerability)[]>;
 }
 
-export type BaseStrategyFormat = "Standard";
+export type BaseStrategyFormat =
+  | "Standard"
+  | "OSV";
 
 export interface BaseStrategyOptions {
   useFormat?: BaseStrategyFormat;
@@ -124,6 +126,7 @@ Where `dependencies` is the dependencies **Map()** object of the NodeSecure Scan
 
 ### Formats
 - [Standard](./docs/formats/standard.md)
+- [OSV](./docs/formats/osv.md)
 
 ### Databases
 - [OSV](./docs/database/osv.md)

docs/database/osv.md

@@ -8,33 +8,7 @@ Lean more at [osv.dev](https://osv.dev/)
 
 ## Format
 
-The OSV interface is exported as root like `StandardVulnerability`.
-
-```ts
-export interface OSV {
-  schema_version: string;
-  id: string;
-  modified: string;
-  published: string;
-  withdraw: string;
-  aliases: string[];
-  related: string[];
-  summary: string;
-  details: string;
-  severity: OSVSeverity[];
-  affected: OSVAffected[];
-  references: {
-    type: OSVReferenceType;
-    url: string;
-  }[];
-  credits: {
-    name: string;
-    contact: string[];
-    type: OSVCreditType;
-  }[];
-  database_specific: Record<string, any>;
-}
-```
+See the [OSV format](../formats/osv.md) documentation.
 
 ## API
 

docs/formats/osv.md

@@ -0,0 +1,89 @@
+# OSV vulnerability format
+
+The [Open Source Vulnerability (OSV) schema](https://ossf.github.io/osv-schema/) is an open, precise, and human-readable format for describing vulnerabilities, maintained by the OpenSSF. It is designed to be interoperable across ecosystems and tooling.
+
+This format can be activated with the `useFormat` option set to `"OSV"`.
+
+## TypeScript interfaces
+
+```ts
+export interface OSV {
+  schema_version?: string;
+  id: string;
+  modified: string;
+  published: string;
+  withdraw?: string;
+  aliases: string[];
+  upstream: string[];
+  related?: string[];
+  summary: string;
+  details: string;
+  severity: OSVSeverity[];
+  affected: OSVAffected[];
+  references: {
+    type: OSVReferenceType;
+    url: string;
+  }[];
+  credits: {
+    name: string;
+    contact: string[];
+    type: OSVCreditType;
+  }[];
+  database_specific: Record<string, any>;
+}
+
+export interface OSVAffected {
+  package: {
+    ecosystem: "npm";
+    name: string;
+    purl: string;
+  };
+  severity: OSVSeverity[];
+  ranges: OSVRange[];
+  versions: string[];
+  ecosystem_specific: Record<string, any>;
+  database_specific: Record<string, any>;
+}
+
+export interface OSVRange {
+  type: string;
+  repo?: string; // Only required for GIT type
+  events: {
+    introduced?: string;
+    fixed?: string;
+    last_affected?: string;
+    limit?: string;
+  }[];
+  database_specific: Record<string, any>;
+}
+
+export interface OSVSeverity {
+  type: string;
+  score: string;
+}
+
+export type OSVReferenceType =
+  | "ADVISORY"
+  | "ARTICLE"
+  | "DETECTION"
+  | "DISCUSSION"
+  | "REPORT"
+  | "FIX"
+  | "GIT"
+  | "INTRODUCED"
+  | "PACKAGE"
+  | "EVIDENCE"
+  | "WEB";
+
+export type OSVCreditType =
+  | "FINDER"
+  | "REPORTER"
+  | "ANALYST"
+  | "COORDINATOR"
+  | "REMEDIATION_DEVELOPER"
+  | "REMEDIATION_REVIEWER"
+  | "REMEDIATION_VERIFIER"
+  | "TOOL"
+  | "SPONSOR"
+  | "OTHER";
+```

src/formats/index.ts

@@ -5,12 +5,16 @@ import {
   standardVulnerabilityMapper,
   type StandardizeKind
 } from "./standard/index.ts";
+import {
+  osvVulnerabilityMapper,
+  type OSVKind
+} from "./osv/index.ts";
 
 export function formatVulnsPayload(
   format: BaseStrategyFormat | null = null
 ) {
   return function formatVulnerabilities(
-    strategy: StandardizeKind,
+    strategy: StandardizeKind | OSVKind,
     vulnerabilities: any[]
   ) {
     if (format === "Standard") {
@@ -19,6 +23,12 @@ export function formatVulnsPayload(
         vulnerabilities
       );
     }
+    if (format === "OSV") {
+      return osvVulnerabilityMapper(
+        strategy,
+        vulnerabilities
+      );
+    }
 
     // identity function
     return vulnerabilities;

src/formats/osv/index.ts

@@ -1,15 +1,18 @@
+// Import Internal Dependencies
+import { OSV_VULN_MAPPERS } from "./mappers.ts";
 
 /**
  * @see https://ossf.github.io/osv-schema/
  */
 export interface OSV {
-  schema_version: string;
+  schema_version?: string;
   id: string;
   modified: string;
   published: string;
-  withdraw: string;
+  withdraw?: string;
   aliases: string[];
-  related: string[];
+  upstream: string[];
+  related?: string[];
   summary: string;
   details: string;
   severity: OSVSeverity[];
@@ -64,7 +67,7 @@ export interface OSVAffected {
 
 export interface OSVRange {
   type: string;
-  repo: string;
+  repo?: string;
   events: {
     introduced?: string;
     fixed?: string;
@@ -78,3 +81,16 @@ export interface OSVSeverity {
   type: string;
   score: string;
 }
+
+export type OSVKind = keyof typeof OSV_VULN_MAPPERS;
+
+export function osvVulnerabilityMapper(
+  strategy: OSVKind,
+  vulnerabilities: any[]
+): OSV[] {
+  if (!(strategy in OSV_VULN_MAPPERS)) {
+    return [];
+  }
+
+  return vulnerabilities.map(OSV_VULN_MAPPERS[strategy]);
+}