The **vuln-*era*** has begun! Programmatically fetch security vulnerabilities with one or many strategies. Originally designed to run and analyze [Scanner](https://github.com/NodeSecure/scanner) dependencies it now also runs independently from an npm Manifest. ## Requirements - [Node.js](https://nodejs.org/en/) v18 or higher ## Getting Started This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com). ```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](./docs/github_advisory.md) | [Sonatype - OSS Index](./docs/sonatype.md) | 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](./docs/adding_new_strategy.md). ## 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). ### 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[]; } ``` ### Databases - [OSV](./docs/database/osv.md) ## Contributors ✨ [](#contributors-) Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

Gentilhomme 💻 📖 👀 🛡️ 🐛

Tony Gorez 💻 👀 🐛

Antoine 💻 🐛 📖

OlehSych 💻

Mathieu 💻

PierreD 💻 📖

Kouadio Fabrice Nguessan 💻 🚧

## License MIT