Merge pull request #285 from NodeSecure/use-format-v2

refactor!: prepare API to use multiple formats such as OSV

Author: fraxken

README.md

@@ -45,7 +45,7 @@ const definition = await vulnera.getStrategy();
 console.log(definition.strategy);
 
 const vulnerabilities = await definition.getVulnerabilities(process.cwd(), {
-  useStandardFormat: true
+  useFormat: "Standard"
 });
 console.log(vulnerabilities);
 ```
@@ -105,11 +105,10 @@ export interface ExtendedStrategy<
   ) => Promise<(VulnFormat | StandardVulnerability)[]>;
 }
 
+export type BaseStrategyFormat = "Standard";
+
 export interface BaseStrategyOptions {
-  /**
-   * @default false
-   */
-  useStandardFormat?: boolean;
+  useFormat?: BaseStrategyFormat;
 }
 
 export interface HydratePayloadDepsOptions extends BaseStrategyOptions {
@@ -126,45 +125,8 @@ Where `dependencies` is the dependencies **Map()** object of the NodeSecure Scan
 > [!NOTE] 
 > the option **hydrateDatabase** is only useful for some of the strategy (like Node.js Security WG).
 
-### Standard vulnerability format
-We provide an high level format that work for all available strategy. It can be activated with the option `useStandardFormat`.
-
-```ts
-export interface StandardVulnerability {
-  /** Unique identifier for the vulnerability **/
-  id?: string;
-  /** Vulnerability origin, either Snyk, Sonatype, GitHub or NodeSWG **/
-  origin: Origin;
-  /** Package associated with the vulnerability **/
-  package: string;
-  /** Vulnerability title **/
-  title: string;
-  /** Vulnerability description **/
-  description?: string;
-  /** Vulnerability link references on origin's website **/
-  url?: string;
-  /** Vulnerability severity levels given the strategy **/
-  severity?: Severity;
-  /** Common Vulnerabilities and Exposures dictionary */
-  cves?: string[];
-  /**
-   * Common Vulnerability Scoring System (CVSS) provides a way to capture
-   * the principal characteristics of a vulnerability,
-   * and produce a numerical score reflecting its severity,
-   * as well as a textual representation of that score. **/
-  cvssVector?: string;
-  /** CVSS Score **/
-  cvssScore?: number;
-  /** The range of vulnerable versions provided when too many versions are vulnerables */
-  vulnerableRanges: string[];
-  /** The set of versions that are vulnerable **/
-  vulnerableVersions: string[];
-  /** The set of versions that are patched **/
-  patchedVersions?: string;
-  /** Overview of available patches to get rid of listed vulnerabilities **/
-  patches?: Patch[];
-}
-```
+### Formats
+- [Standard](./docs/formats/standard.md)
 
 ### Databases
 - [OSV](./docs/database/osv.md)

docs/formats/standard.md

@@ -0,0 +1,40 @@
+# Standard vulnerability format
+
+We provide a high-level format that works for all available strategies. It can be activated with the option `useFormat` equal `Standard`.
+
+```ts
+export interface StandardVulnerability {
+  /** Unique identifier for the vulnerability **/
+  id?: string;
+  /** Vulnerability origin, either Snyk, Sonatype, GitHub or NodeSWG **/
+  origin: Origin;
+  /** Package associated with the vulnerability **/
+  package: string;
+  /** Vulnerability title **/
+  title: string;
+  /** Vulnerability description **/
+  description?: string;
+  /** Vulnerability link references on origin's website **/
+  url?: string;
+  /** Vulnerability severity levels given the strategy **/
+  severity?: Severity;
+  /** Common Vulnerabilities and Exposures dictionary */
+  cves?: string[];
+  /**
+   * Common Vulnerability Scoring System (CVSS) provides a way to capture
+   * the principal characteristics of a vulnerability,
+   * and produce a numerical score reflecting its severity,
+   * as well as a textual representation of that score. **/
+  cvssVector?: string;
+  /** CVSS Score **/
+  cvssScore?: number;
+  /** The range of vulnerable versions provided when too many versions are vulnerables */
+  vulnerableRanges: string[];
+  /** The set of versions that are vulnerable **/
+  vulnerableVersions: string[];
+  /** The set of versions that are patched **/
+  patchedVersions?: string;
+  /** Overview of available patches to get rid of listed vulnerabilities **/
+  patches?: Patch[];
+}
+```

docs/github_advisory.md

@@ -41,17 +41,17 @@ For audit a specific manifest (package.json, lock-file or nodes_modules), there
 
 ```js
 async function getVulnerabilities(path, options = {}) {
-  const { useStandardFormat } = options;
+  const { useFormat } = options;
 
-  const formatVulnerabilities = standardizeVulnsPayload(useStandardFormat);
+  const formatVulnerabilities = formatVulnsPayload(useFormat);
   const registry = getLocalRegistryURL();
   const isPnpm = await hasPnpmLockFile(path);
 
   const vulnerabilities = isPnpm ?
     await pnpmAudit(path, registry) :
     await npmAudit(path, registry);
 
-  if (useStandardFormat) {
+  if (useFormat) {
     return formatVulnerabilities(
       isPnpm ? VULN_MODE.GITHUB_ADVISORY + "_pnpm" : VULN_MODE.GITHUB_ADVISORY,
       vulnerabilities
@@ -69,7 +69,7 @@ import * as vulnera from "@nodesecure/vulnera";
 const definition = await vulnera.setStrategy(vulnera.strategies.GITHUB_ADVISORY);
 const vulnerabilites = await definition.getVulnerabilities(
   './package.json',
-  { useStandardFormat: true }
+  { useFormat: "Standard" }
 );
 ```
 

src/formats/index.ts

@@ -0,0 +1,26 @@
+// Import Internal Dependencies
+import type { BaseStrategyFormat } from "../strategies/types/api.js";
+
+import {
+  standardVulnerabilityMapper,
+  type StandardizeKind
+} from "./standard/index.js";
+
+export function formatVulnsPayload(
+  format: BaseStrategyFormat | null = null
+) {
+  return function formatVulnerabilities(
+    strategy: StandardizeKind,
+    vulnerabilities: any[]
+  ) {
+    if (format === "Standard") {
+      return standardVulnerabilityMapper(
+        strategy,
+        vulnerabilities
+      );
+    }
+
+    // identity function
+    return vulnerabilities;
+  };
+}

src/formats/standard/index.ts

@@ -1,5 +1,5 @@
 // Import Internal Dependencies
-import { VULN_MAPPERS } from "./mappers.js";
+import { STANDARD_VULN_MAPPERS } from "./mappers.js";
 import type { Kind } from "../../constants.js";
 
 export type Severity = "info" | "low" | "medium" | "high" | "critical";
@@ -47,32 +47,15 @@ export interface StandardVulnerability {
   patches?: StandardPatch[];
 }
 
-export type StandardizeKind = keyof typeof VULN_MAPPERS;
+export type StandardizeKind = keyof typeof STANDARD_VULN_MAPPERS;
 
-function useStrategyVulnerabilityMapper(
+export function standardVulnerabilityMapper(
   strategy: StandardizeKind,
   vulnerabilities: any[]
 ): StandardVulnerability[] {
-  if (!(strategy in VULN_MAPPERS)) {
+  if (!(strategy in STANDARD_VULN_MAPPERS)) {
     return [];
   }
 
-  return vulnerabilities.map(VULN_MAPPERS[strategy]);
+  return vulnerabilities.map(STANDARD_VULN_MAPPERS[strategy]);
 }
-
-export function standardizeVulnsPayload(useStandardFormat = false) {
-  return function formatVulnerabilities(
-    strategy: StandardizeKind,
-    vulnerabilities: any[]
-  ) {
-    if (useStandardFormat) {
-      return useStrategyVulnerabilityMapper(
-        strategy, vulnerabilities
-      );
-    }
-
-    // identity function
-    return vulnerabilities;
-  };
-}
-

src/formats/standard/mappers.ts

@@ -91,7 +91,7 @@ function mapFromSonatype(vuln: SonatypeVulnerability): StandardVulnerability {
   };
 }
 
-export const VULN_MAPPERS = Object.freeze({
+export const STANDARD_VULN_MAPPERS = Object.freeze({
   [VULN_MODE.GITHUB_ADVISORY]: mapFromNPM,
   "github-advisory_pnpm": mapFromPnpm,
   [VULN_MODE.SNYK]: mapFromSnyk,

src/index.ts

@@ -44,8 +44,9 @@ import type {
 
 import type {
   BaseStrategy,
-  ExtendedStrategy,
   BaseStrategyOptions,
+  BaseStrategyFormat,
+  ExtendedStrategy,
   HydratePayloadDepsOptions
 } from "./strategies/types/api.js";
 
@@ -104,6 +105,7 @@ export const defaultStrategyName = VULN_MODE.NONE;
 export type {
   Kind,
   BaseStrategyOptions,
+  BaseStrategyFormat,
   BaseStrategy,
   ExtendedStrategy,
   HydratePayloadDepsOptions,

src/strategies/github-advisory.ts

@@ -11,7 +11,8 @@ import { readWantedLockfile } from "@pnpm/lockfile-file";
 
 // Import Internal Dependencies
 import { VULN_MODE, NPM_TOKEN } from "../constants.js";
-import { type StandardVulnerability, standardizeVulnsPayload } from "../formats/standard/index.js";
+import type { StandardVulnerability } from "../formats/standard/index.js";
+import { formatVulnsPayload } from "../formats/index.js";
 import type { Dependencies } from "./types/scanner.js";
 import type {
   BaseStrategyOptions,
@@ -72,9 +73,9 @@ async function getVulnerabilities(
   lockDirOrManifestPath: string,
   options: BaseStrategyOptions = {}
 ): Promise<(GithubVulnerability | StandardVulnerability)[]> {
-  const { useStandardFormat } = options;
+  const { useFormat } = options;
 
-  const formatVulnerabilities = standardizeVulnsPayload(useStandardFormat);
+  const formatVulnerabilities = formatVulnsPayload(useFormat);
   const registry = getLocalRegistryURL();
 
   const lockfileDir = path.extname(lockDirOrManifestPath) === "" ?
@@ -89,7 +90,7 @@ async function getVulnerabilities(
     await pnpmAudit(lockfileDir, registry) :
     await npmAudit(lockDirOrManifestPath, registry);
 
-  if (useStandardFormat) {
+  if (useFormat) {
     return formatVulnerabilities(
       isPnpm ? "github-advisory_pnpm" : VULN_MODE.GITHUB_ADVISORY,
       vulnerabilities
@@ -103,12 +104,12 @@ async function hydratePayloadDependencies(
   dependencies: Dependencies,
   options: HydratePayloadDepsOptions
 ): Promise<void> {
-  const { path, useStandardFormat } = options;
+  const { path, useFormat } = options;
   if (!path) {
     throw new Error("path argument is required for <github-advisory> strategy");
   }
 
-  const formatVulnerabilities = standardizeVulnsPayload(useStandardFormat);
+  const formatVulnerabilities = formatVulnsPayload(useFormat);
   const registry = getLocalRegistryURL();
 
   try {

src/strategies/snyk.ts

@@ -5,14 +5,14 @@ import { readFile } from "node:fs/promises";
 
 // Import Internal Dependencies
 import { VULN_MODE } from "../constants.js";
-import { standardizeVulnsPayload } from "../formats/standard/index.js";
 import type { Dependencies } from "./types/scanner.js";
 import type {
   HydratePayloadDepsOptions,
   BaseStrategy
 } from "./types/api.js";
 import { type SnykAuditResponse } from "../formats/snyk/index.js";
 import { snyk } from "../database/index.js";
+import { formatVulnsPayload } from "../formats/index.js";
 
 export type SnykStrategyDefinition = BaseStrategy<"snyk">;
 
@@ -78,8 +78,8 @@ function extractSnykVulnerabilities(
   options: HydratePayloadDepsOptions
 ) {
   const { ok, issues } = snykAudit;
-  const { useStandardFormat } = options;
-  const formatVulnerabilities = standardizeVulnsPayload(useStandardFormat);
+  const { useFormat } = options;
+  const formatVulnerabilities = formatVulnsPayload(useFormat);
 
   if (!ok) {
     const vulnerabilities = formatVulnerabilities(VULN_MODE.SNYK, issues.vulnerabilities);

src/strategies/sonatype.ts

@@ -4,12 +4,12 @@ import * as httpie from "@myunisoft/httpie";
 // Import Internal Dependencies
 import * as utils from "../utils.js";
 import { VULN_MODE } from "../constants.js";
-import { standardizeVulnsPayload } from "../formats/standard/index.js";
 import type { Dependencies, Dependency } from "./types/scanner.js";
 import type {
   BaseStrategyOptions,
   BaseStrategy
 } from "./types/api.js";
+import { formatVulnsPayload } from "../formats/index.js";
 
 // CONSTANTS
 const kSonatypeApiURL = "https://ossindex.sonatype.org/api/v3/component-report";
@@ -135,8 +135,8 @@ async function hydratePayloadDependencies(
     Array.from(dependencies).flatMap(createPackageURLCoordinates)
   );
 
-  const formatVulnerabilities = standardizeVulnsPayload(
-    options.useStandardFormat
+  const formatVulnerabilities = formatVulnsPayload(
+    options.useFormat
   );
   for (const sonatypeResponse of packageURLsData) {
     const packageName = extractNameFromPackageURL(sonatypeResponse.coordinates);