🔎 About

Scanner is a Node.js static analysis tool that recursively walks dependency trees, scans npm tarballs with JS-X-Ray, and enriches results with vulnerability data from Vulnera.

🚧 Requirements

• Node.js version 22 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/scanner
# or
$ yarn add @nodesecure/scanner

👀 Usage example

import * as scanner from "@nodesecure/scanner";
import fs from "node:fs/promises";

// CONSTANTS
const kPackagesToAnalyze = ["mocha", "cacache", "is-wsl"];

const payloads = await Promise.all(
  kPackagesToAnalyze.map((name) => scanner.from(name))
);

const promises = [];
for (let i = 0; i < kPackagesToAnalyze.length; i++) {
  const data = JSON.stringify(payloads[i], null, 2);

  promises.push(fs.writeFile(`${kPackagesToAnalyze[i]}.json`, data));
}
await Promise.allSettled(promises);

📚 API

See types.ts for a complete TypeScript definition.

function workingDir(
  location: string,
  options?: Scanner.WorkingDirOptions,
  logger?: Scanner.Logger
): Promise<Scanner.Payload>;
function from(
  spec: string,
  options?: Scanner.FromOptions,
  logger?: Scanner.Logger
): Promise<Scanner.Payload>;
function verify(
  spec?: string
): Promise<tarball.ScannedPackageResult>;

WorkingDirOptions and FromOptions are described with the following TypeScript interfaces:

type WorkingDirOptions = Options & {
  /**
   * NPM runtime configuration (such as local .npmrc file)
   * It is optionally used to fetch registry authentication tokens
   */
  npmRcConfig?: Config;
  /**
   * Optional cache lookup called after reading the local package.json.
   */
  cacheLookup?: (
    packageJSON: PackageJSON,
    integrity: string | null
  ) => Promise<Payload | null>;
};

type FromOptions = Omit<Options, "includeDevDeps"> & {
  /**
   * Optional cache lookup called after fetching the remote manifest.
   */
  cacheLookup?: (
    manifest: pacote.AbbreviatedManifest & pacote.ManifestResult
  ) => Promise<Payload | null>;
};

interface Options {
  /**
   * Specifies the maximum depth to traverse for each root dependency.
   * A value of 2 would mean only traversing deps and their immediate deps.
   *
   * @default Infinity
   */
  readonly maxDepth?: number;

  /**
   * Maximum concurrency to fetch and scan NPM tarballs
   * @default 8
   */
  readonly maxConcurrency?: number;

  /**
   * Includes development dependencies in the walk.
   * Note that enabling this option can significantly increase I/O and processing time.
   *
   * @default false
   */
  includeDevDeps?: boolean;

  readonly registry?: string | URL;

  /**
   * Enables the use of Arborist for rapidly walking over the dependency tree.
   * When enabled, it triggers different methods based on the presence of `node_modules`:
   * - `loadActual()` if `node_modules` is available.
   * - `loadVirtual()` otherwise.
   *
   * When disabled, it will iterate on all dependencies by using pacote
   */
  packageLock?: {
    /**
     * Fetches all manifests for additional metadata.
     *
     * @default false
     */
    fetchManifest?: boolean;

    /**
     * Specifies the location of the manifest file for Arborist.
     * This is typically the path to the `package.json` file.
     */
    location: string;
  };

  highlight?: {
    contacts?: Contact[];
    packages?: HighlightPackages;
    identifiers?: string[];
  };

  /**
   * Vulnerability strategy name (npm, snyk, node)
   *
   * @default NONE
   */
  readonly vulnerabilityStrategy?: Vuln.Strategy.Kind;

  /**
   * Analyze root package.
   *
   * @default false for from() API
   * @default true  for cwd()  API
   */
  readonly scanRootNode?: boolean;
}

Additional API documentation:

• from
• workingDir
• verify
• extractors
• logger
• Architecture

License

MIT