@nodesecure/scanner 2.0.0 → 3.0.0

package/src/utils/index.js

@@ -1,14 +1,16 @@
-export * from "./getTarballComposition.js";
-export * from "./isSensitiveFile.js";
-export * from "./getPackageName.js";
-export * from "./mergeDependencies.js";
-export * from "./semver.js";
-export * from "./dirname.js";
-export * from "./warnings.js";
-
-export const constants = {
-  NPM_TOKEN: typeof process.env.NODE_SECURE_TOKEN === "string" ? { token: process.env.NODE_SECURE_TOKEN } : {},
-  NPM_SCRIPTS: new Set(["preinstall", "postinstall", "preuninstall", "postuninstall"]),
-  EXT_DEPS: new Set(["http", "https", "net", "http2", "dgram", "child_process"]),
-  EXT_JS: new Set([".js", ".mjs", ".cjs"])
-};
+export * from "./getTarballComposition.js";
+export * from "./isSensitiveFile.js";
+export * from "./isGitDependency.js";
+export * from "./getPackageName.js";
+export * from "./mergeDependencies.js";
+export * from "./semver.js";
+export * from "./dirname.js";
+export * from "./warnings.js";
+export * from "./filterDependencyKind.js";
+export * from "./analyzeDependencies.js";
+export * from "./booleanToFlags.js";
+export * from "./addMissingVersionFlags.js";
+
+export const NPM_TOKEN = typeof process.env.NODE_SECURE_TOKEN === "string" ?
+  { token: process.env.NODE_SECURE_TOKEN } :
+  {};

package/src/utils/isGitDependency.js

@@ -0,0 +1,20 @@
+const kGitVersionVariants = ["git:", "git+", "github:"];
+
+/**
+ * @example isGitDependency("github:NodeSecure/scanner") // => true
+ * @example isGitDependency("git+ssh://git@github.com:npm/cli#semver:^5.0") // => true
+ * @example isGitDependency(">=1.0.2 <2.1.2") // => false
+ * @example isGitDependency("http://asdf.com/asdf.tar.gz") // => false
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function isGitDependency(version) {
+  for (const variant of kGitVersionVariants) {
+    if (version.startsWith(variant)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+

package/src/utils/isSensitiveFile.js

@@ -5,6 +5,12 @@ import path from "path";
 const kSensitiveFileName = new Set([".npmrc", ".env"]);
 const kSensitiveFileExtension = new Set([".key", ".pem"]);
 
+/**
+ * @see https://github.com/jandre/safe-commit-hook/blob/master/git-deny-patterns.json
+ *
+ * @param {!string} fileName
+ * @returns {boolean}
+ */
 export function isSensitiveFile(fileName) {
   return kSensitiveFileName.has(path.basename(fileName)) ||
     kSensitiveFileExtension.has(path.extname(fileName));

package/src/utils/mergeDependencies.js

@@ -1,23 +1,26 @@
-export function mergeDependencies(manifest, types = ["dependencies"]) {
-  const dependencies = new Map();
-  const customResolvers = new Map();
-
-  for (const fieldName of types) {
-    if (!Reflect.has(manifest, fieldName)) {
-      continue;
-    }
-    const dep = manifest[fieldName];
-
-    for (const [name, version] of Object.entries(dep)) {
-      // Version can be file:, github:, git+, ./...
-      if (/^([a-zA-Z]+:|git\+|\.\\)/.test(version)) {
-        customResolvers.set(name, version);
-        continue;
-      }
-
-      dependencies.set(name, version);
-    }
-  }
-
-  return { dependencies, customResolvers };
-}
+export function mergeDependencies(manifest, types = ["dependencies"]) {
+  const dependencies = new Map();
+  const customResolvers = new Map();
+
+  for (const fieldName of types) {
+    if (!Reflect.has(manifest, fieldName)) {
+      continue;
+    }
+    const dep = manifest[fieldName];
+
+    for (const [name, version] of Object.entries(dep)) {
+      /**
+       * Version can be file:, github:, git:, git+, ./...
+       * @see https://docs.npmjs.com/cli/v7/configuring-npm/package-json#dependencies
+       */
+      if (/^([a-zA-Z]+:|git\+|\.\\)/.test(version)) {
+        customResolvers.set(name, version);
+        continue;
+      }
+
+      dependencies.set(name, version);
+    }
+  }
+
+  return { dependencies, customResolvers };
+}

package/src/utils/semver.js

@@ -4,7 +4,7 @@ import semver from "semver";
 import { getLocalRegistryURL } from "@nodesecure/npm-registry-sdk";
 
 // Import Internal Dependencies
-import { constants } from "./index.js";
+import { NPM_TOKEN } from "./index.js";
 
 /**
  * @param {!string} version semver range
@@ -31,11 +31,11 @@ export function cleanRange(version) {
 export async function getExpectedSemVer(depName, range) {
   try {
     const { versions, "dist-tags": { latest } } = await pacote.packument(depName, {
-      ...constants.NPM_TOKEN, registry: getLocalRegistryURL()
+      ...NPM_TOKEN, registry: getLocalRegistryURL()
     });
     const currVersion = semver.maxSatisfying(Object.keys(versions), range);
 
-    return [currVersion === null ? latest : currVersion, semver.eq(latest, currVersion)];
+    return currVersion === null ? [latest, true] : [currVersion, semver.eq(latest, currVersion)];
   }
   catch (err) {
     return [cleanRange(range), true];

package/types/logger.d.ts

@@ -6,7 +6,9 @@ export {
 }
 
 interface LoggerEventData {
+  /** UNIX Timestamp */
   startedAt: number;
+  /** Count of triggered event */
   count: number;
 }
 

package/types/scanner.d.ts

@@ -1,64 +1,133 @@
-import { Warning, Dependency, BaseWarning } from "@nodesecure/js-x-ray";
+// Import NodeSecure Dependencies
+import * as JSXRay from "@nodesecure/js-x-ray";
 import { license as License } from "@nodesecure/ntlp";
-import { Strategy, NpmStrategy, NodeStrategy } from "@nodesecure/vuln";
+import * as Vuln from "@nodesecure/vuln";
 import { Flags } from "@nodesecure/flags";
+
+// Import Third-party Dependencies
 import { Maintainer } from "@npm/types";
 
 export = Scanner;
 
 declare namespace Scanner {
   export interface Publisher {
+    /**
+     * Publisher npm user name.
+     */
     name: string;
+    /**
+     * Publisher npm user email.
+     */
+    email: string;
+    /**
+     * First version published.
+     */
     version: string;
+    /**
+     * Date of the first publication
+     * @example 2021-08-10T20:45:08.342Z
+     */
     at: string;
   }
 
-  export interface VersionDescriptor {
+  export interface DependencyVersion {
+    /** Id of the package (useful for usedBy relation) */
+    id: number;
+    /** By whom (id) is used the package */
+    usedBy: Record<string, string>;
+    /** Size on disk of the extracted tarball (in bytes) */
+    size: number;
+    /** Package description */
+    description: string;
+    /** Author of the package. This information is not trustable and can be empty. */
+    author: Maintainer;
+    /**
+     * JS-X-Ray warnings
+     *
+     * @see https://github.com/NodeSecure/js-x-ray/blob/master/WARNINGS.md
+     */
+    warnings: JSXRay.Warning<JSXRay.BaseWarning>[];
+    /** Tarball composition (files and dependencies) */
+    composition: {
+      /** Files extensions (.js, .md, .exe etc..) */
+      extensions: string[];
+      files: string[];
+      /** Minified files (foo.min.js etc..) */
+      minified: string[];
+      required_files: string[];
+      required_thirdparty: string[];
+      required_nodejs: string[];
+      unused: string[];
+      missing: string[];
+    };
+    /**
+     * Package licenses with SPDX expression.
+     *
+     * @see https://github.com/NodeSecure/licenses-conformance
+     * @see https://github.com/NodeSecure/npm-tarball-license-parser
+     */
+    license: License[];
+    /**
+     * Flags (Array of string)
+     *
+     * @see https://github.com/NodeSecure/flags/blob/main/FLAGS.md
+     */
+    flags: Flags[];
+    /**
+     * If the dependency is a GIT repository
+     */
+    gitUrl: null | string;
+  }
+
+  export interface Dependency {
+    /** NPM Registry metadata */
     metadata: {
+      /** Count of dependencies */
       dependencyCount: number;
+      /** Number of releases published on npm */
       publishedCount: number;
       lastUpdateAt: number;
+      /** Last version SemVer */
       lastVersion: number;
       hasChangedAuthor: boolean;
       hasManyPublishers: boolean;
       hasReceivedUpdateInOneYear: boolean;
+      /** Author of the package. This information is not trustable and can be empty. */
       author: Maintainer;
+      /** Package home page */
       homepage: string | null;
-      maintainers: Maintainer[];
+      /**
+       * List of maintainers (list of people in the organization related to the package)
+       */
+      maintainers: { name: string, email: string }[];
+      /**
+       * List of people who published this package
+       */
       publishers: Publisher[];
     }
-    versions: string[];
-    vulnerabilities: (NpmStrategy.Vulnerability | NodeStrategy.Vulnerability)[];
-    [version: string]: {
-      id: number;
-      usedBy: Record<string, string>;
-      size: number;
-      description: string;
-      author: Maintainer;
-      warnings: Warning<BaseWarning>[];
-      composition: {
-        extensions: string[];
-        files: string[];
-        minified: string[];
-        required_files: string[];
-        required_thirdparty: string[];
-        required_nodejs: string[];
-        unused: string[];
-        missing: string[];
-      };
-      license: string | License[];
-      flags: Flags;
-      gitUrl: null | string;
-    };
+    /** List of versions of this package available in the dependency tree (In the payload) */
+    versions: Record<string, DependencyVersion>;
+    /**
+     * Vulnerabilities fetched dependending on the selected vulnerabilityStrategy
+     *
+     * @see https://github.com/NodeSecure/vuln
+     */
+    vulnerabilities: Vuln.Strategy.StandardVulnerability[];
   }
 
   export interface Payload {
+    /** Payload unique id */
     id: string;
+    /** Name of the analyzed package */
     rootDependencyName: string;
+    /** Global warnings list */
     warnings: [];
-    dependencies: Record<string, VersionDescriptor>;
+    /** All the dependencies of the package (flattened) */
+    dependencies: Record<string, Dependency>;
+    /** Version of the scanner used to generate the result */
     version: string;
-    vulnerabilityStrategy: Strategy.Kind;
+    /** Vulnerability strategy name (npm, snyk, node) */
+    vulnerabilityStrategy: Vuln.Strategy.Kind;
   }
 
   export interface VerifyPayload {
@@ -71,16 +140,43 @@ declare namespace Scanner {
     uniqueLicenseIds: string[];
     licenses: License[];
     ast: {
-      dependencies: Record<string, Dependency>;
-      warnings: Warning<BaseWarning>[];
+      dependencies: Record<string, JSXRay.Dependency>;
+      warnings: JSXRay.Warning<JSXRay.BaseWarning>[];
     };
   }
 
   export interface Options {
+    /**
+     * Maximum tree depth
+     *
+     * @default 4
+     */
     readonly maxDepth?: number;
+    /**
+     * Use root package-lock.json. This will have the effect of triggering the Arborist package.
+     *
+     * @default false for from() API
+     * @default true  for cwd()  API
+     */
     readonly usePackageLock?: boolean;
-    readonly vulnerabilityStrategy: Strategy.Kind;
+    /**
+     * 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 forceRootAnalysis?: boolean;
+    /**
+     * Deeper dependencies analysis with cwd() API.
+     *
+     * @default false
+     */
     readonly fullLockMode?: boolean;
   }
 }