@nodesecure/vulnera

The vuln-era has begun! Programmatically fetch security vulnerabilities with one or many strategies. Originally designed to run and analyze Scanner dependencies it now also runs independently from an npm Manifest.

Requirements

Node.js v16 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/vulnera
# or
$ yarn add @nodesecure/vulnera

Usage example

import * as vulnera from "@nodesecure/vulnera";

// Default strategy is currently "none".
await vulnera.setStrategy(vulnera.strategies.NPM_AUDIT);

const definition = await vulnera.getStrategy();
console.log(definition.strategy);

const vulnerabilities = await definition.getVulnerabilities(process.cwd(), {
  useStandardFormat: true
});
console.log(vulnerabilities);

Available strategy

The default strategy is NONE which mean no strategy at all (we execute nothing).

NPM Audit	Node.js Security WG - Database	Sonatype - OSS Index	[COMING SOON] Snyk

Those strategies are described as "string" type with the following TypeScript definition:

type Kind = "npm" | "node" | "sonatype" | "snyk" | "none";

To add a strategy or better understand how the code works, please consult the following guide.

API

See types/api.d.ts for a complete TypeScript definition.

function setStrategy(name?: Strategy.Kind, options?: Strategy.Options): Promise<Strategy.Definition>;
function getStrategy(): Promise<Strategy.Definition>;

const strategies: {
  SECURITY_WG: "node";
  NPM_AUDIT: "npm";
  SONATYPE: "sonatype";
  SNYK: "snyk";
  NONE: "none";
};

/** Equal to strategies.NONE by default **/
const defaultStrategyName: string;

Strategy Kind, HydratePayloadDependenciesOptions, Options are described by the following interfaces:

export interface Options {
  /** Force hydratation of the strategy local database (if the strategy has one obviously) **/
  hydrateDatabase?: boolean;
}

export interface HydratePayloadDependenciesOptions {
  /**
   * Absolute path to the location to analyze (with a package.json and/or package-lock.json)
   * Useful to NPM Audit strategy
   **/
  path?: string;
  useStandardFormat?: boolean;
}

export interface GetVulnerabilitiesOptions {
  useStandardFormat?: boolean;
}

export interface Definition<T> {
  /** Name of the strategy **/
  strategy: Kind;
  /** Method to hydrate (insert/push) vulnerabilities in the dependencies retrieved by the Scanner **/
  hydratePayloadDependencies: (
    dependencies: Dependencies,
    options?: HydratePayloadDependenciesOptions
  ) => Promise<void>;
  /** Method to get vulnerabilities using the current strategy **/
  getVulnerabilities: (
    path: string,
    options?: GetVulnerabilitiesOptions
  ) => Promise<T | StandardVulnerability>;
  /** Hydrate local database (if the strategy need one obviously) **/
  hydrateDatabase?: () => Promise<void>;
  /** Method to delete the local vulnerabilities database (if available) **/
  deleteDatabase?: () => Promise<void>;
}

Where dependencies is the dependencies Map() object of the scanner.

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.

export interface StandardVulnerability {
  /** Unique identifier for the vulnerability **/
  id?: string;
  /** Vulnerability origin, either Snyk, NPM 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[];
}