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/) v24 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";
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](./docs/github_advisory.md)
- [Sonatype OSS Index](./docs/sonatype.md)
- [OSV](./docs/osv.md)
Those strategies are described as "string" **type** with the following TypeScript definition:
```ts
type Kind = "github-advisory" | "sonatype" | "osv" | "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",
SONATYPE: "sonatype",
OSV: "osv",
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 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](./docs/formats/standard.md)
- [OSV](./docs/formats/osv.md)
### Databases
- [OSV](./docs/database/osv.md)
- [NVD](./docs/database/nvd.md)
- [Sonatype](./docs/database/sonatype.md)
## Contributors ✨
[](#contributors-)
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
