github_advisory.md

GitHub Advisory strategy

Important

This strategy was previously known as NPM

NPM Audit is a feature provided by the npm team. This allows to identify anomalies in a package.json/package-lock.json.

Under the hood we use @npmcli/arborist to fetch vulnerabilities (directly as JSON).

const { vulnerabilities } = (await arborist.audit()).toJSON();

This strategy doesn't require the synchronization of a local database.

Important

This strategy currently only work with a local project analysis (with a package.json/package-lock.json)

import * as vulnera from "@nodesecure/vulnera";
import { loadRegistryURLFromLocalSystem } from "@nodesecure/npm-registry-sdk";

// Before walking the dependency tree (at runtime)
loadRegistryURLFromLocalSystem();

const dependencies = new Map();
// ...do work on dependencies...

const definition = await vulnera.setStrategy(vulnera.strategies.GITHUB_ADVISORY);
await definition.hydratePayloadDependencies(dependencies, {
  // path where we have to run npm audit (default equal to process.cwd())
  path: process.cwd()
});

Note that it is important to call loadRegistryURLFromLocalSystem before running hydratePayloadDependencies method. The internal method will retrieve the correct URL for the registry (could be useful if the developer use a private registry for example).

Audit a specific manifest

For audit a specific manifest (package.json, lock-file or nodes_modules), there is the getVulnerabilities function that takes the path of the manifest and returns the vulnerabilities.

async function getVulnerabilities(path, options = {}) {
  const { useStandardFormat } = options;

  const formatVulnerabilities = standardizeVulnsPayload(useStandardFormat);
  const registry = getLocalRegistryURL();
  const isPnpm = await hasPnpmLockFile(path);

  const vulnerabilities = isPnpm ?
    await pnpmAudit(path, registry) :
    await npmAudit(path, registry);

  if (useStandardFormat) {
    return formatVulnerabilities(
      isPnpm ? VULN_MODE.GITHUB_ADVISORY + "_pnpm" : VULN_MODE.GITHUB_ADVISORY,
      vulnerabilities
    );
  }

  return vulnerabilities;
}

Example with Standard NodeSecure format:

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

const definition = await vulnera.setStrategy(vulnera.strategies.GITHUB_ADVISORY);
const vulnerabilites = await definition.getVulnerabilities(
  './package.json',
  { useStandardFormat: true }
);

Work natively with pnpm

Vulnera use @pnpm/audit to support the package manager pnpm and his lock file pnpm-lock.