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

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

type Kind = "github-advisory" | "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",
  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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/thomas-gentilhomme/"><img src="https://avatars.githubusercontent.com/u/4438263?v=4?s=100" width="100px;" alt="Gentilhomme"/> Gentilhomme</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=fraxken" title="Code">💻</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=fraxken" title="Documentation">📖</a> <a href="https://github.com/NodeSecure/vulnera/pulls?q=is%3Apr+reviewed-by%3Afraxken" title="Reviewed Pull Requests">👀</a> <a href="#security-fraxken" title="Security">🛡️</a> <a href="https://github.com/NodeSecure/vulnera/issues?q=author%3Afraxken" title="Bug reports">🐛</a></td> <td align="center" valign="top" width="14.28%"><a href="http://tonygo.dev"><img src="https://avatars.githubusercontent.com/u/22824417?v=4?s=100" width="100px;" alt="Tony Gorez"/> Tony Gorez</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=tony-go" title="Code">💻</a> <a href="https://github.com/NodeSecure/vulnera/pulls?q=is%3Apr+reviewed-by%3Atony-go" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/NodeSecure/vulnera/issues?q=author%3Atony-go" title="Bug reports">🐛</a></td> <td align="center" valign="top" width="14.28%"><a href="https://antoinecoulon.me/"><img src="https://avatars.githubusercontent.com/u/43391199?v=4?s=100" width="100px;" alt="Antoine"/> Antoine</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=antoine-coulon" title="Code">💻</a> <a href="https://github.com/NodeSecure/vulnera/issues?q=author%3Aantoine-coulon" title="Bug reports">🐛</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=antoine-coulon" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/OlehSych"><img src="https://avatars.githubusercontent.com/u/34604102?v=4?s=100" width="100px;" alt="OlehSych"/> OlehSych</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=OlehSych" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/Mathieuka"><img src="https://avatars.githubusercontent.com/u/34446722?v=4?s=100" width="100px;" alt="Mathieu"/> Mathieu</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=Mathieuka" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/PierreDemailly"><img src="https://avatars.githubusercontent.com/u/39910767?v=4?s=100" width="100px;" alt="PierreD"/> PierreD</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=PierreDemailly" title="Code">💻</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=PierreDemailly" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/fabnguess"><img src="https://avatars.githubusercontent.com/u/72697416?v=4?s=100" width="100px;" alt="Kouadio Fabrice Nguessan"/> Kouadio Fabrice Nguessan</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=fabnguess" title="Code">💻</a> <a href="#maintenance-fabnguess" title="Maintenance">🚧</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/AntonioliBenjamin"><img src="https://avatars.githubusercontent.com/u/111560667?v=4?s=100" width="100px;" alt="benjamin antonioli"/> benjamin antonioli</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=AntonioliBenjamin" title="Code">💻</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=AntonioliBenjamin" title="Tests">⚠️</a></td> <td align="center" valign="top" width="14.28%"><a href="https://securityinit.tistory.com/"><img src="https://avatars.githubusercontent.com/u/78394999?v=4?s=100" width="100px;" alt="HoyeongJeon"/> HoyeongJeon</a> <a href="https://github.com/NodeSecure/vulnera/commits?author=HoyeongJeon" title="Code">💻</a></td> </tr> </tbody> </table>

License

MIT

Vulnera

Install / Use

README