@nodesecure/js-x-ray 4.3.0 → 4.4.0

package/README.md

@@ -73,6 +73,38 @@ The analysis will return: `http` (in try), `crypto`, `util` and `fs`.
 
 > ⚠️ There is also a lot of suspicious code example in the root cases directory. Feel free to try the tool on these files.
 
+## Warnings
+
+This section describes how use `warnings` export.
+
+The structure of the `warnings` is as follows:
+```
+/**
+ * @property {object}  warnings                         - The default values for Constants.
+ * @property {string}  warnings[name]                   - The default warning name (parsingError, unsafeImport etc...).
+ * @property {string}  warnings[name].i18n              - i18n token.
+ * @property {string}  warnings[name].code              - Used to perform unit tests.
+ */
+ 
+export const warnings = Object.freeze({
+    parsingError: {
+      i18n: "sast_warnings.ast_error"
+      code: "ast-error",
+    },
+    ...otherWarnings
+  });
+```
+
+We make a call to `i18n` through the package `NodeSecure/i18n` to get the translation.
+
+```
+import * as jsxray from "@nodesecure/js-x-ray";
+import * as i18n from "@nodesecure/i18n";
+
+console.log(i18n.getToken(jsxray.warnings.parsingError.i18n));
+
+```
+
 ## Warnings Legends (v2.0+)
 
 > Node-secure versions equal or lower than 0.7.0 are no longer compatible with the warnings table below.

package/index.d.ts

@@ -1,99 +1,124 @@
-declare class ASTDeps {
-  constructor();
-  removeByName(name: string): void;
-  add(depName: string): void;
-  getDependenciesInTryStatement(): IterableIterator<string>;
-
-  public isInTryStmt: boolean;
-  public dependencies: Record<string, JSXRay.Dependency>;
-  public readonly size: number;
-}
-
-declare namespace JSXRay {
-  type kindWithValue = "parsing-error"
-    | "encoded-literal"
-    | "unsafe-regex"
-    | "unsafe-stmt"
-    | "unsafe-assign"
-    | "short-identifiers"
-    | "suspicious-literal"
-    | "obfuscated-code";
-
-  type WarningLocation = [[number, number], [number, number]];
-  interface BaseWarning {
-    kind: "unsafe-import" | kindWithValue;
-    file?: string;
-    value: string;
-    location: WarningLocation | WarningLocation[];
-  }
-
-  type Warning<T extends BaseWarning> = T extends { kind: kindWithValue } ? T : Omit<T, "value">;
-
-  interface Report {
-    dependencies: ASTDeps;
-    warnings: Warning<BaseWarning>[];
-    idsLengthAvg: number;
-    stringScore: number;
-    isOneLineRequire: boolean;
-  }
-
-  interface SourceLocation {
-    start: {
-      line: number;
-      column: number;
-    };
-    end: {
-      line: number;
-      column: number;
-    }
-  }
-
-  interface Dependency {
-    unsafe: boolean;
-    inTry: boolean;
-    location?: SourceLocation;
-  }
-
-  interface WarningsNames {
-    parsingError: "parsing-error",
-    unsafeImport: "unsafe-import",
-    unsafeStmt: "unsafe-stmt",
-    unsafeRegex: "unsafe-regex",
-    unsafeAssign: "unsafe-assign",
-    encodedLiteral: "encoded-literal",
-    shortIdentifiers: "short-identifiers",
-    suspiciousLiteral: "suspicious-literal",
-    obfuscatedCode: "obfuscated-code"
-  }
-
-  interface RuntimeOptions {
-    module?: boolean;
-    isMinified?: boolean;
-  }
-
-  export function runASTAnalysis(str: string, options?: RuntimeOptions): Report;
-
-  export type ReportOnFile = {
-    ok: true,
-    warnings: Warning<BaseWarning>[];
-    dependencies: ASTDeps;
-    isMinified: boolean;
-  } | {
-    ok: false,
-    warnings: Warning<BaseWarning>[];
-  }
-
-  export interface RuntimeFileOptions {
-    packageName?: string;
-    module?: boolean;
-  }
-
-  export function runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
-
-  export namespace CONSTANTS {
-    export const Warnings: WarningsNames;
-  }
-}
-
-export = JSXRay;
-export as namespace JSXRay;
+declare class ASTDeps {
+  constructor();
+  removeByName(name: string): void;
+  add(depName: string): void;
+  getDependenciesInTryStatement(): IterableIterator<string>;
+
+  public isInTryStmt: boolean;
+  public dependencies: Record<string, JSXRay.Dependency>;
+  public readonly size: number;
+}
+
+declare namespace JSXRay {
+  type kindWithValue = "parsing-error"
+    | "encoded-literal"
+    | "unsafe-regex"
+    | "unsafe-stmt"
+    | "unsafe-assign"
+    | "short-identifiers"
+    | "suspicious-literal"
+    | "obfuscated-code";
+
+  type WarningLocation = [[number, number], [number, number]];
+  interface BaseWarning {
+    kind: "unsafe-import" | kindWithValue;
+    file?: string;
+    value: string;
+    location: WarningLocation | WarningLocation[];
+  }
+
+  type Warning<T extends BaseWarning> = T extends { kind: kindWithValue } ? T : Omit<T, "value">;
+
+  interface Report {
+    dependencies: ASTDeps;
+    warnings: Warning<BaseWarning>[];
+    idsLengthAvg: number;
+    stringScore: number;
+    isOneLineRequire: boolean;
+  }
+
+  interface SourceLocation {
+    start: {
+      line: number;
+      column: number;
+    };
+    end: {
+      line: number;
+      column: number;
+    }
+  }
+
+  interface Dependency {
+    unsafe: boolean;
+    inTry: boolean;
+    location?: SourceLocation;
+  }
+
+  interface WarningsNames {
+    parsingError: {
+      code: "ast-error",
+      i18n: "sast_warnings.ast_error"
+    },
+    unsafeImport: {
+      code: "unsafe-import",
+      i18n: "sast_warnings.unsafe_import"
+    },
+    unsafeRegex: {
+      code: "unsafe-regex",
+      i18n: "sast_warnings.unsafe_regex"
+    },
+    unsafeStmt: {
+      code: "unsafe-stmt",
+      i18n: "sast_warnings.unsafe_stmt"
+    },
+    unsafeAssign: {
+      code: "unsafe-assign",
+      i18n: "sast_warnings.unsafe_assign"
+    },
+    encodedLiteral: {
+      code: "encoded-literal",
+      i18n: "sast_warnings.encoded_literal"
+    },
+    shortIdentifiers: {
+      code: "short-identifiers",
+      i18n: "sast_warnings.short_identifiers"
+    },
+    suspiciousLiteral: {
+      code: "suspicious-literal",
+      i18n: "sast_warnings.suspicious_literal"
+    },
+    obfuscatedCode: {
+      code: "obfuscated-code",
+      i18n: "sast_warnings.obfuscated_code"
+    }
+  }
+
+  interface RuntimeOptions {
+    module?: boolean;
+    isMinified?: boolean;
+  }
+
+  export function runASTAnalysis(str: string, options?: RuntimeOptions): Report;
+
+  export type ReportOnFile = {
+    ok: true,
+    warnings: Warning<BaseWarning>[];
+    dependencies: ASTDeps;
+    isMinified: boolean;
+  } | {
+    ok: false,
+    warnings: Warning<BaseWarning>[];
+  }
+
+  export interface RuntimeFileOptions {
+    packageName?: string;
+    module?: boolean;
+  }
+
+  export function runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
+
+  export const warnings: WarningsNames;
+}
+
+export = JSXRay;
+export as namespace JSXRay;

package/index.js

@@ -1,98 +1,125 @@
-// Import Node.js Dependencies
-import fs from "fs/promises";
-import path from "path";
-
-// Import Third-party Dependencies
-import { walk } from "estree-walker";
-import * as meriyah from "meriyah";
-import isMinified from "is-minified-code";
-
-// Import Internal Dependencies
-import Analysis from "./src/Analysis.js";
-
-export function runASTAnalysis(str, options = Object.create(null)) {
-  const { module = true, isMinified = false } = options;
-
-  // Note: if the file start with a shebang then we remove it because 'parseScript' may fail to parse it.
-  // Example: #!/usr/bin/env node
-  const strToAnalyze = str.charAt(0) === "#" ? str.slice(str.indexOf("\n")) : str;
-  const isEcmaScriptModule = Boolean(module);
-  const { body } = meriyah.parseScript(strToAnalyze, {
-    next: true,
-    loc: true,
-    raw: true,
-    module: isEcmaScriptModule,
-    globalReturn: !isEcmaScriptModule
-  });
-
-  const sastAnalysis = new Analysis();
-  sastAnalysis.analyzeSourceString(str);
-
-  // we walk each AST Nodes, this is a purely synchronous I/O
-  walk(body, {
-    enter(node) {
-      // Skip the root of the AST.
-      if (Array.isArray(node)) {
-        return;
-      }
-
-      const action = sastAnalysis.walk(node);
-      if (action === "skip") {
-        this.skip();
-      }
-    }
-  });
-
-  const dependencies = sastAnalysis.dependencies;
-  const { idsLengthAvg, stringScore, warnings } = sastAnalysis.getResult(isMinified);
-  const isOneLineRequire = body.length <= 1 && dependencies.size <= 1;
-
-  return {
-    dependencies, warnings, idsLengthAvg, stringScore, isOneLineRequire
-  };
-}
-
-export async function runASTAnalysisOnFile(pathToFile, options = {}) {
-  try {
-    const { packageName = null, module = true } = options;
-    const str = await fs.readFile(pathToFile, "utf-8");
-
-    const isMin = pathToFile.includes(".min") || isMinified(str);
-    const data = runASTAnalysis(str, {
-      isMinified: isMin,
-      module: path.extname(pathToFile) === ".mjs" ? true : module
-    });
-    if (packageName !== null) {
-      data.dependencies.removeByName(packageName);
-    }
-
-    return {
-      ok: true,
-      dependencies: data.dependencies,
-      warnings: data.warnings,
-      isMinified: !data.isOneLineRequire && isMin
-    };
-  }
-  catch (error) {
-    return {
-      ok: false,
-      warnings: [
-        { kind: "parsing-error", value: error.message, location: [[0, 0], [0, 0]] }
-      ]
-    };
-  }
-}
-
-export const CONSTANTS = {
-  Warnings: Object.freeze({
-    parsingError: "ast-error",
-    unsafeImport: "unsafe-import",
-    unsafeRegex: "unsafe-regex",
-    unsafeStmt: "unsafe-stmt",
-    unsafeAssign: "unsafe-assign",
-    encodedLiteral: "encoded-literal",
-    shortIdentifiers: "short-identifiers",
-    suspiciousLiteral: "suspicious-literal",
-    obfuscatedCode: "obfuscated-code"
-  })
-};
+// Import Node.js Dependencies
+import fs from "fs/promises";
+import path from "path";
+
+// Import Third-party Dependencies
+import { walk } from "estree-walker";
+import * as meriyah from "meriyah";
+import isMinified from "is-minified-code";
+
+// Import Internal Dependencies
+import Analysis from "./src/Analysis.js";
+
+export function runASTAnalysis(str, options = Object.create(null)) {
+  const { module = true, isMinified = false } = options;
+
+  // Note: if the file start with a shebang then we remove it because 'parseScript' may fail to parse it.
+  // Example: #!/usr/bin/env node
+  const strToAnalyze = str.charAt(0) === "#" ? str.slice(str.indexOf("\n")) : str;
+  const isEcmaScriptModule = Boolean(module);
+  const { body } = meriyah.parseScript(strToAnalyze, {
+    next: true,
+    loc: true,
+    raw: true,
+    module: isEcmaScriptModule,
+    globalReturn: !isEcmaScriptModule
+  });
+
+  const sastAnalysis = new Analysis();
+  sastAnalysis.analyzeSourceString(str);
+
+  // we walk each AST Nodes, this is a purely synchronous I/O
+  walk(body, {
+    enter(node) {
+      // Skip the root of the AST.
+      if (Array.isArray(node)) {
+        return;
+      }
+
+      const action = sastAnalysis.walk(node);
+      if (action === "skip") {
+        this.skip();
+      }
+    }
+  });
+
+  const dependencies = sastAnalysis.dependencies;
+  const { idsLengthAvg, stringScore, warnings } = sastAnalysis.getResult(isMinified);
+  const isOneLineRequire = body.length <= 1 && dependencies.size <= 1;
+
+  return {
+    dependencies, warnings, idsLengthAvg, stringScore, isOneLineRequire
+  };
+}
+
+export async function runASTAnalysisOnFile(pathToFile, options = {}) {
+  try {
+    const { packageName = null, module = true } = options;
+    const str = await fs.readFile(pathToFile, "utf-8");
+
+    const isMin = pathToFile.includes(".min") || isMinified(str);
+    const data = runASTAnalysis(str, {
+      isMinified: isMin,
+      module: path.extname(pathToFile) === ".mjs" ? true : module
+    });
+    if (packageName !== null) {
+      data.dependencies.removeByName(packageName);
+    }
+
+    return {
+      ok: true,
+      dependencies: data.dependencies,
+      warnings: data.warnings,
+      isMinified: !data.isOneLineRequire && isMin
+    };
+  }
+  catch (error) {
+    return {
+      ok: false,
+      warnings: [
+        { kind: "parsing-error", value: error.message, location: [[0, 0], [0, 0]] }
+      ]
+    };
+  }
+}
+
+export const warnings = Object.freeze({
+  parsingError: {
+    code: "ast-error",
+    i18n: "sast_warnings.ast_error"
+  },
+  unsafeImport: {
+    code: "unsafe-import",
+    i18n: "sast_warnings.unsafe_import"
+  },
+  unsafeRegex: {
+    code: "unsafe-regex",
+    i18n: "sast_warnings.unsafe_regex"
+  },
+  unsafeStmt: {
+    code: "unsafe-stmt",
+    i18n: "sast_warnings.unsafe_stmt"
+  },
+  unsafeAssign: {
+    code: "unsafe-assign",
+    i18n: "sast_warnings.unsafe_assign"
+  },
+  encodedLiteral: {
+    code: "encoded-literal",
+    i18n: "sast_warnings.encoded_literal"
+  },
+  shortIdentifiers: {
+    code: "short-identifiers",
+    i18n: "sast_warnings.short_identifiers"
+  },
+  suspiciousLiteral: {
+    code: "suspicious-literal",
+    i18n: "sast_warnings.suspicious_literal"
+  },
+  obfuscatedCode: {
+    code: "obfuscated-code",
+    i18n: "sast_warnings.obfuscated_code"
+  }
+});
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodesecure/js-x-ray",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "JavaScript AST XRay analysis",
   "type": "module",
   "exports": "./index.js",
@@ -48,10 +48,10 @@
     "@slimio/is": "^1.5.1",
     "@small-tech/esm-tape-runner": "^2.0.0",
     "@small-tech/tap-monkey": "^1.3.0",
-    "@types/node": "^17.0.23",
+    "@types/node": "^17.0.31",
     "cross-env": "^7.0.3",
-    "eslint": "^8.12.0",
+    "eslint": "^8.15.0",
     "pkg-ok": "^3.0.0",
-    "tape": "^5.5.2"
+    "tape": "^5.5.3"
   }
 }