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 v24 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";

const github = vulnera.setStrategy(
  vulnera.strategies.GITHUB_ADVISORY
);

const vulnerabilities = await github.getVulnerabilities(process.cwd(), {
  useFormat: "Standard"
});
console.log(vulnerabilities);

Available strategy

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

• GitHub Advisory
• Sonatype OSS Index
• OSV
• Snyk

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

type Kind = "github-advisory" | "snyk" | "sonatype" | "osv" | "none";

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

API

function setStrategy<T extends Kind>(name: T): AllStrategy[T];
function getStrategy(): AnyStrategy;

const strategies: Object.freeze({
  GITHUB_ADVISORY: "github-advisory",
  SNYK: "snyk",
  SONATYPE: "sonatype",
  OSV: "osv",
  NONE: "none"
});

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

Strategy extend from the following set of interfaces;

export interface BaseStrategy<T extends Kind> {
  /** Name of the strategy **/
  strategy: T;
  /** Method to hydrate dependency vulnerabilities fetched by the Scanner **/
  hydratePayloadDependencies: (
    dependencies: Dependencies,
    options?: HydratePayloadDepsOptions
  ) => Promise<void>;
}

export interface ExtendedStrategy<
  T extends Kind, VulnFormat
> extends BaseStrategy<T> {
  /** Method to get vulnerabilities using the current strategy **/
  getVulnerabilities: (
    path: string,
    options?: BaseStrategyOptions
  ) => Promise<(VulnFormat | StandardVulnerability)[]>;
}

export type BaseStrategyFormat =
  | "Standard"
  | "OSV";

export interface BaseStrategyOptions {
  useFormat?: BaseStrategyFormat;
}

export interface HydratePayloadDepsOptions extends BaseStrategyOptions {
  /**
   * Absolute path to the location to analyze
   * (with a package.json and/or package-lock.json for NPM Audit for example)
   **/
  path?: string;
}

Where dependencies is the dependencies Map() object of the NodeSecure Scanner.

[!NOTE] the option hydrateDatabase is only useful for some of the strategy (like Node.js Security WG).

Formats

• Standard
• OSV

Databases

• OSV
• NVD
• Snyk
• Sonatype

Contributors ✨

Thanks goes to these wonderful people (emoji key):

License

MIT