@nodesecure/scanner 2.2.0 → 3.2.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/src/utils/warnings.js

@@ -8,6 +8,7 @@ const kWarningsMessages = Object.freeze({
   iohook: getToken("warnings.keylogging")
 });
 const kPackages = new Set(Object.keys(kWarningsMessages));
+const kAuthors = new Set(["Marak Squires"]);
 
 function getWarning(depName) {
   return `${kDetectedDep(depName)} ${kWarningsMessages[depName]}`;
@@ -21,6 +22,14 @@ export function getDependenciesWarnings(dependencies) {
     }
   }
 
+  // TODO: optimize with @nodesecure/author later
+  for (const [packageName, dependency] of dependencies) {
+    const author = dependency.metadata.author?.name ?? null;
+    if (kAuthors.has(author)) {
+      warnings.push(`'${author}' package '${packageName}' has been detected in the dependency tree`);
+    }
+  }
+
   return warnings;
 }
 

package/types/api.d.ts

@@ -1,12 +1,15 @@
 import Scanner from "./scanner";
-import { Logger } from "./logger";
+import { Logger, LoggerEvents } from "./logger";
 
 export {
   cwd,
   from,
-  verify
+  verify,
+  ScannerLoggerEvents
 }
 
+declare const ScannerLoggerEvents: LoggerEvents;
+
 declare function cwd(path: string, options?: Scanner.Options, logger?: Logger): Promise<Scanner.Payload>;
 declare function from(packageName: string, options?: Scanner.Options, logger?: Logger): Promise<Scanner.Payload>;
 declare function verify(packageName: string): Promise<Scanner.VerifyPayload>;

package/types/logger.d.ts

@@ -2,11 +2,27 @@ import { EventEmitter } from "events";
 
 export {
   Logger,
-  LoggerEventData
+  LoggerEventData,
+  LoggerEvents
+}
+
+interface LoggerEvents {
+  readonly done: "depWalkerFinished";
+  readonly analysis: {
+      readonly tree: "walkTree";
+      readonly tarball: "tarball";
+      readonly registry: "registry";
+  };
+  readonly manifest: {
+      readonly read: "readManifest";
+      readonly fetch: "fetchManifest";
+  };
 }
 
 interface LoggerEventData {
+  /** UNIX Timestamp */
   startedAt: number;
+  /** Count of triggered event */
   count: number;
 }
 

package/types/scanner.d.ts

@@ -1,86 +1,185 @@
-import { Warning, Dependency, BaseWarning } from "@nodesecure/js-x-ray";
-import { license as License } from "@nodesecure/ntlp";
-import { Strategy, NpmStrategy, NodeStrategy } from "@nodesecure/vuln";
-import { Flags } from "@nodesecure/flags";
-import { Maintainer } from "@npm/types";
-
-export = Scanner;
-
-declare namespace Scanner {
-  export interface Publisher {
-    name: string;
-    version: string;
-    at: string;
-  }
-
-  export interface VersionDescriptor {
-    metadata: {
-      dependencyCount: number;
-      publishedCount: number;
-      lastUpdateAt: number;
-      lastVersion: number;
-      hasChangedAuthor: boolean;
-      hasManyPublishers: boolean;
-      hasReceivedUpdateInOneYear: boolean;
-      author: Maintainer;
-      homepage: string | null;
-      maintainers: Maintainer[];
-      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;
-    };
-  }
-
-  export interface Payload {
-    id: string;
-    rootDependencyName: string;
-    warnings: [];
-    dependencies: Record<string, VersionDescriptor>;
-    version: string;
-    vulnerabilityStrategy: Strategy.Kind;
-  }
-
-  export interface VerifyPayload {
-    files: {
-      list: string[];
-      extensions: string[];
-      minified: string[];
-    };
-    directorySize: number;
-    uniqueLicenseIds: string[];
-    licenses: License[];
-    ast: {
-      dependencies: Record<string, Dependency>;
-      warnings: Warning<BaseWarning>[];
-    };
-  }
-
-  export interface Options {
-    readonly maxDepth?: number;
-    readonly usePackageLock?: boolean;
-    readonly vulnerabilityStrategy: Strategy.Kind;
-    readonly forceRootAnalysis?: boolean;
-    readonly fullLockMode?: boolean;
-  }
-}
+// Import NodeSecure Dependencies
+import * as JSXRay from "@nodesecure/js-x-ray";
+import { license as License } from "@nodesecure/ntlp";
+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 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;
+      /**
+       * 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[];
+    }
+    /** 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 type GlobalWarning = string[];
+  export type Dependencies = Record<string, Dependency>;
+
+  export interface Payload {
+    /** Payload unique id */
+    id: string;
+    /** Name of the analyzed package */
+    rootDependencyName: string;
+    /** Global warnings list */
+    warnings: GlobalWarning[];
+    /** All the dependencies of the package (flattened) */
+    dependencies: Dependencies;
+    /** Version of the scanner used to generate the result */
+    scannerVersion: string;
+    /** Vulnerability strategy name (npm, snyk, node) */
+    vulnerabilityStrategy: Vuln.Strategy.Kind;
+  }
+
+  export interface VerifyPayload {
+    files: {
+      list: string[];
+      extensions: string[];
+      minified: string[];
+    };
+    directorySize: number;
+    uniqueLicenseIds: string[];
+    licenses: License[];
+    ast: {
+      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;
+    /**
+     * 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;
+  }
+}