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 v18 or higher

Getting Started

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

``bash
$ npm i @nodesecure/vulnera

or

$ yarn add @nodesecure/vulnera
`

Usage example

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

await vulnera.setStrategy(
vulnera.strategies.GITHUB_ADVISORY
);

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).

GitHub Advisory | Sonatype - OSS Index | Snyk
:-------------------------:|:-------------------------:|:-------------------------:
| |

Those strategies are described as "string" type with the following TypeScript definition:
`ts
type Kind = "github-advisory" | "snyk" | "sonatype" | "none";
`

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

API

`ts
function setStrategy(name: T): AllStrategy[T];
function getStrategy(): AnyStrategy;

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

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

Strategy extend from the following set of interfaces;

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

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

export interface BaseStrategyOptions {
/**
* @default false
*/
useStandardFormat?: boolean;
}

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).

$3

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[];
}
``

$3

- OSV

Contributors ✨



Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 📖 👀 🛡️ 🐛

Tony Gorez 💻 👀 🐛

Antoine 💻 🐛 📖

OlehSych 💻

Mathieu 💻

PierreD 💻 📖

Kouadio Fabrice Nguessan 💻 🚧

License

MIT