@nodesecure/js-x-ray 7.3.0 → 8.0.0

package/README.md

@@ -85,6 +85,11 @@ The analysis will return: `http` (in try), `crypto`, `util` and `fs`.
 > [!TIP]
 > There is also a lot of suspicious code example in the `./examples` cases directory. Feel free to try the tool on these files.
 
+## API
+
+- [AstAnalyser](./docs/api/AstAnalyser.md)
+- [EntryFilesAnalyser](./docs/api/EntryFilesAnalyser.md)
+
 ## Warnings
 
 This section describes how use `warnings` export.
@@ -118,7 +123,7 @@ import * as i18n from "@nodesecure/i18n";
 console.log(i18n.getTokenSync(jsxray.warnings["parsing-error"].i18n));
 ```
 
-## Warnings Legends
+### Legends
 
 This section describe all the possible warnings returned by JSXRay. Click on the warning **name** for additional information and examples.
 
@@ -131,161 +136,10 @@ This section describe all the possible warnings returned by JSXRay. Click on the
 | [encoded-literal](./docs/encoded-literal.md) | ❌ | An encoded literal has been detected (it can be an hexa value, unicode sequence or a base64 string) |
 | [short-identifiers](./docs/short-identifiers.md) | ❌ | This mean that all identifiers has an average length below 1.5. |
 | [suspicious-literal](./docs/suspicious-literal.md) | ❌ | A suspicious literal has been found in the source code. |
-| [suspicious-file](./docs/suspicious-file.md) | ✔️ | A suspicious file with more than ten encoded-literal in it |
+| [suspicious-file](./docs/suspicious-file.md) | ❌ | A suspicious file with more than ten encoded-literal in it |
 | [obfuscated-code](./docs/obfuscated-code.md) | ✔️ | There's a very high probability that the code is obfuscated. |
-| [weak-crypto](./docs/weak-crypto.md) | ✔️ | The code probably contains a weak crypto algorithm (md5, sha1...) |
-| [shady-link](./docs/shady-link.md) | ✔️ | The code contains shady/unsafe link |
-
-## Custom Probes
-
-You can also create custom probes to detect specific pattern in the code you are analyzing.
-
-A probe is a pair of two functions (`validateNode` and `main`) that will be called on each node of the AST. It will return a warning if the pattern is detected.
-Below a basic probe that detect a string assignation to `danger`:
-
-```ts
-export const customProbes = [
-  {
-    name: "customProbeUnsafeDanger",
-    validateNode: (node, sourceFile) => [
-      node.type === "VariableDeclaration" && node.declarations[0].init.value === "danger"
-    ],
-    main: (node, options) => {
-      const { sourceFile, data: calleeName } = options;
-      if (node.declarations[0].init.value === "danger") {
-        sourceFile.addWarning("unsafe-danger", calleeName, node.loc);
-
-        return ProbeSignals.Skip;
-      }
-
-      return null;
-    }
-  }
-];
-```
-
-You can pass an array of probes to the `runASTAnalysis/runASTAnalysisOnFile` functions as `options`, or directly to the `AstAnalyser` constructor.
-
-| Name             | Type                             | Description                                                           | Default Value   |
-|------------------|----------------------------------|-----------------------------------------------------------------------|-----------------|
-| `customParser`   | `SourceParser \| undefined`      | An optional custom parser to be used for parsing the source code.    | `JsSourceParser` |
-| `customProbes`   | `Probe[] \| undefined`           | An array of custom probes to be used during AST analysis.            | `[]`            |
-| `skipDefaultProbes` | `boolean \| undefined`        | If `true`, default probes will be skipped and only custom probes will be used. | `false`         |
-
-
-Here using the example probe upper:
-
-```ts
-import { AstAnalyser } from "@nodesecure/js-x-ray";
-
-// add your customProbes here (see example above)
-
-const scanner = new AstAnalyser({
-  customProbes,
-  skipDefaultProbes: true
-});
-
-const result = scanner.analyse("const danger = 'danger';");
-
-console.log(result);
-```
-
-Result:
-
-```sh
-✗ node example.js
-{
-  idsLengthAvg: 0,
-  stringScore: 0,
-  warnings: [ { kind: 'unsafe-danger', location: [Array], source: 'JS-X-Ray' } ],
-  dependencies: Map(0) {},
-  isOneLineRequire: false
-}
-```
-
-Congrats, you have created your first custom probe! 🎉
-
-> [!TIP]
-> Check the types in [index.d.ts](index.d.ts) and [types/api.d.ts](types/api.d.ts) for more details about the `options`
-
-## API
-
-- [AstAnalyser](./docs/api/AstAnalyser.md)
-- [EntryFilesAnalyser](./docs/api/EntryFilesAnalyser.md)
-
-Legacy APIs waiting to be deprecated;
-
-<details>
-<summary>runASTAnalysis(str: string, options?: RuntimeOptions & AstAnalyserOptions): Report</summary>
-
-```ts
-interface RuntimeOptions {
-  module?: boolean;
-  removeHTMLComments?: boolean;
-  isMinified?: boolean;
-  initialize?: (sourceFile: SourceFile) => void;
-  finalize?: (sourceFile: SourceFile) => void;
-}
-```
-
-```ts
-interface AstAnalyserOptions {
-  customParser?: SourceParser;
-  customProbes?: Probe[];
-  skipDefaultProbes?: boolean;
-}
-```
-
-The method take a first argument which is the code you want to analyse. It will return a Report Object:
-
-```ts
-interface Report {
-  dependencies: ASTDeps;
-  warnings: Warning[];
-  idsLengthAvg: number;
-  stringScore: number;
-  isOneLineRequire: boolean;
-}
-```
-
-</details>
-
-<details>
-<summary>runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions & AstAnalyserOptions): Promise< ReportOnFile ></summary>
-
-```ts
-interface RuntimeFileOptions {
-  module?: boolean;
-  removeHTMLComments?: boolean;
-  packageName?: string;
-  initialize?: (sourceFile: SourceFile) => void;
-  finalize?: (sourceFile: SourceFile) => void;
-}
-```
-
-```ts
-interface AstAnalyserOptions {
-  customParser?: SourceParser;
-  customProbes?: Probe[];
-  skipDefaultProbes?: boolean;
-}
-```
-
-Run the SAST scanner on a given JavaScript file.
-
-```ts
-export type ReportOnFile = {
-  ok: true,
-  warnings: Warning[];
-  dependencies: ASTDeps;
-  isMinified: boolean;
-} | {
-  ok: false,
-  warnings: Warning[];
-}
-```
-
-</details>
+| [weak-crypto](./docs/weak-crypto.md) | ❌ | The code probably contains a weak crypto algorithm (md5, sha1...) |
+| [shady-link](./docs/shady-link.md) | ❌ | The code contains shady/unsafe link |
 
 ## Workspaces
 

package/index.d.ts

@@ -7,8 +7,6 @@ import {
 
   SourceParser,
   JsSourceParser,
-  runASTAnalysis,
-  runASTAnalysisOnFile,
   Report,
   ReportOnFile,
   RuntimeFileOptions,
@@ -34,8 +32,6 @@ export {
   EntryFilesAnalyserOptions,
   JsSourceParser,
   SourceParser,
-  runASTAnalysis,
-  runASTAnalysisOnFile,
   Report,
   ReportOnFile,
   RuntimeFileOptions,

package/index.js

@@ -1,70 +1,4 @@
-// Import Internal Dependencies
-import { warnings } from "./src/warnings.js";
-import { JsSourceParser } from "./src/JsSourceParser.js";
-import { AstAnalyser } from "./src/AstAnalyser.js";
-import { EntryFilesAnalyser } from "./src/EntryFilesAnalyser.js";
-
-function runASTAnalysis(
-  str,
-  options = Object.create(null)
-) {
-  process.emitWarning(
-    'The runASTAnalysis API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.',
-    {
-      code: 'DeprecationWarning',
-      detail: 'The runASTAnalysis API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.'
-    }
-  );
-
-  const {
-    customParser = new JsSourceParser(),
-    customProbes = [],
-    skipDefaultProbes = false,
-    ...opts
-  } = options;
-
-  const analyser = new AstAnalyser({
-    customParser,
-    customProbes,
-    skipDefaultProbes
-  });
-
-  return analyser.analyse(str, opts);
-}
-
-async function runASTAnalysisOnFile(
-  pathToFile,
-  options = {}
-) {
-  process.emitWarning(
-    'The runASTAnalysisOnFile API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.',
-    {
-      code: 'DeprecationWarning',
-      detail: 'The runASTAnalysisOnFile API is deprecated and will be removed in v8. Please use the AstAnalyser class instead.'
-    }
-  );
-
-  const {
-    customProbes = [],
-    customParser = new JsSourceParser(),
-    skipDefaultProbes = false,
-    ...opts
-  } = options;
-
-  const analyser = new AstAnalyser({
-    customParser,
-    customProbes,
-    skipDefaultProbes
-  });
-
-  return analyser.analyseFile(pathToFile, opts);
-}
-
-export {
-  warnings,
-  AstAnalyser,
-  EntryFilesAnalyser,
-  JsSourceParser,
-  runASTAnalysis,
-  runASTAnalysisOnFile
-};
+export { warnings } from "./src/warnings.js";
+export { JsSourceParser } from "./src/JsSourceParser.js";
+export { AstAnalyser } from "./src/AstAnalyser.js";
+export { EntryFilesAnalyser } from "./src/EntryFilesAnalyser.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodesecure/js-x-ray",
-  "version": "7.3.0",
+  "version": "8.0.0",
   "description": "JavaScript AST XRay analysis",
   "type": "module",
   "exports": "./index.js",
@@ -8,8 +8,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "lint": "eslint src test",
-    "prepublishOnly": "pkg-ok",
+    "lint": "eslint src workspaces test",
     "test-only": "glob -c \"node --test-reporter=spec --test\" \"./test/**/*.spec.js\"",
     "test": "c8 --all --src ./src -r html npm run test-only",
     "check": "npm run lint && npm run test-only"
@@ -44,23 +43,21 @@
   },
   "homepage": "https://github.com/NodeSecure/js-x-ray#readme",
   "dependencies": {
-    "@nodesecure/estree-ast-utils": "^1.3.1",
+    "@nodesecure/estree-ast-utils": "^1.5.0",
     "@nodesecure/sec-literal": "^1.2.0",
+    "digraph-js": "^2.2.3",
     "estree-walker": "^3.0.1",
     "frequency-set": "^1.0.2",
     "is-minified-code": "^2.0.0",
-    "meriyah": "^4.3.3",
+    "meriyah": "^5.0.0",
     "safe-regex": "^2.1.1",
     "ts-pattern": "^5.0.6"
   },
   "devDependencies": {
-    "@nodesecure/eslint-config": "^1.6.0",
-    "@types/node": "^20.6.2",
+    "@openally/config.eslint": "^1.0.0",
+    "@types/node": "^22.0.0",
     "c8": "^10.1.2",
-    "cross-env": "^7.0.3",
-    "eslint": "^9.0.0",
     "glob": "^11.0.0",
-    "iterator-matcher": "^2.1.0",
-    "pkg-ok": "^3.0.0"
+    "iterator-matcher": "^2.1.0"
   }
 }

package/src/Deobfuscator.js

@@ -63,6 +63,9 @@ export class Deobfuscator {
    * @param {*} node
    */
   #extractCounterIdentifiers(nc, node) {
+    if (node === null) {
+      return;
+    }
     const { type } = nc;
 
     switch (type) {

package/src/EntryFilesAnalyser.js

@@ -3,6 +3,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+// Import Third-party Dependencies
+import { DiGraph } from "digraph-js";
+
 // Import Internal Dependencies
 import { AstAnalyser } from "./AstAnalyser.js";
 
@@ -10,70 +13,106 @@ import { AstAnalyser } from "./AstAnalyser.js";
 const kDefaultExtensions = ["js", "cjs", "mjs", "node"];
 
 export class EntryFilesAnalyser {
-  /**
-   * @constructor
-   * @param {object} [options={}]
-   * @param {AstAnalyser} [options.astAnalyzer=new AstAnalyser()]
-   * @param {function} [options.loadExtensions]
-  */
+  #rootPath = null;
+
   constructor(options = {}) {
-    this.astAnalyzer = options.astAnalyzer ?? new AstAnalyser();
-    const rawAllowedExtensions = options.loadExtensions
-      ? options.loadExtensions(kDefaultExtensions)
+    const {
+      astAnalyzer = new AstAnalyser(),
+      loadExtensions,
+      rootPath = null
+    } = options;
+
+    this.astAnalyzer = astAnalyzer;
+    const rawAllowedExtensions = loadExtensions
+      ? loadExtensions(kDefaultExtensions)
       : kDefaultExtensions;
 
     this.allowedExtensions = new Set(rawAllowedExtensions);
+    this.#rootPath = options.rootPath === null ?
+      null : fileURLToPathExtended(rootPath);
   }
 
-  /**
-   * Asynchronously analyze a set of entry files yielding analysis reports.
-   *
-   * @param {(string | URL)[]} entryFiles
-   * @yields {Object} - Yields an object containing the analysis report for each file.
-  */
-  async* analyse(entryFiles) {
-    this.analyzedDeps = new Set();
-
-    for (const file of entryFiles) {
-      yield* this.#analyzeFile(file);
+  async* analyse(
+    entryFiles,
+    options = {}
+  ) {
+    this.dependencies = new DiGraph();
+
+    for (const entryFile of new Set(entryFiles)) {
+      const normalizedEntryFile = path.normalize(
+        fileURLToPathExtended(entryFile)
+      );
+
+      yield* this.#analyseFile(
+        normalizedEntryFile,
+        this.#getRelativeFilePath(normalizedEntryFile),
+        options
+      );
     }
   }
 
-  async* #analyzeFile(file) {
-    const filePath = file instanceof URL ? fileURLToPath(file) : file;
-    const report = await this.astAnalyzer.analyseFile(file);
+  #getRelativeFilePath(file) {
+    return this.#rootPath ? path.relative(this.#rootPath, file) : file;
+  }
 
-    yield { url: filePath, ...report };
+  async* #analyseFile(
+    file,
+    relativeFile,
+    options
+  ) {
+    this.dependencies.addVertex({
+      id: relativeFile,
+      adjacentTo: [],
+      body: {}
+    });
+
+    const report = await this.astAnalyzer.analyseFile(
+      file,
+      options
+    );
+    yield { file: relativeFile, ...report };
 
     if (!report.ok) {
       return;
     }
 
-    yield* this.#analyzeDeps(
-      report.dependencies,
-      path.dirname(filePath)
-    );
-  }
-
-  async* #analyzeDeps(deps, basePath) {
-    for (const [name] of deps) {
-      const depPath = await this.#getInternalDepPath(name, basePath);
-
-      if (depPath && !this.analyzedDeps.has(depPath)) {
-        this.analyzedDeps.add(depPath);
+    for (const [name] of report.dependencies) {
+      const depFile = await this.#getInternalDepPath(
+        path.join(path.dirname(file), name)
+      );
+      if (depFile === null) {
+        continue;
+      }
 
-        yield* this.#analyzeFile(depPath);
+      const depRelativeFile = this.#getRelativeFilePath(depFile);
+      if (!this.dependencies.hasVertex(depRelativeFile)) {
+        this.dependencies.addVertex({
+          id: depRelativeFile,
+          adjacentTo: [],
+          body: {}
+        });
+
+        yield* this.#analyseFile(
+          depFile,
+          depRelativeFile,
+          options
+        );
       }
+
+      this.dependencies.addEdge({
+        from: relativeFile, to: depRelativeFile
+      });
     }
   }
 
-  async #getInternalDepPath(name, basePath) {
-    const depPath = path.join(basePath, name);
-    const existingExt = path.extname(name);
+  async #getInternalDepPath(
+    filePath
+  ) {
+    const fileExtension = path.extname(filePath);
 
-    if (existingExt === "") {
+    if (fileExtension === "") {
       for (const ext of this.allowedExtensions) {
-        const depPathWithExt = `${depPath}.${ext}`;
+        const depPathWithExt = `${filePath}.${ext}`;
 
         const fileExist = await this.#fileExists(depPathWithExt);
         if (fileExist) {
@@ -82,22 +121,24 @@ export class EntryFilesAnalyser {
       }
     }
     else {
-      if (!this.allowedExtensions.has(existingExt.slice(1))) {
+      if (!this.allowedExtensions.has(fileExtension.slice(1))) {
         return null;
       }
 
-      const fileExist = await this.#fileExists(depPath);
+      const fileExist = await this.#fileExists(filePath);
       if (fileExist) {
-        return depPath;
+        return filePath;
       }
     }
 
     return null;
   }
 
-  async #fileExists(path) {
+  async #fileExists(
+    filePath
+  ) {
     try {
-      await fs.access(path, fs.constants.R_OK);
+      await fs.access(filePath, fs.constants.R_OK);
 
       return true;
     }
@@ -110,3 +151,11 @@ export class EntryFilesAnalyser {
     }
   }
 }
+
+function fileURLToPathExtended(
+  file
+) {
+  return file instanceof URL ?
+    fileURLToPath(file) :
+    file;
+}

package/src/probes/isLiteral.js

@@ -5,6 +5,7 @@ import { builtinModules } from "repl";
 import { Hex } from "@nodesecure/sec-literal";
 
 const kMapRegexIps = Object.freeze({
+  // eslint-disable-next-line @stylistic/max-len
   regexIPv4: /^(https?:\/\/)(?!127\.)(?!.*:(?:0{1,3}|25[6-9])\.)(?!.*:(?:25[6-9])\.(?:0{1,3}|25[6-9])\.)(?!.*:(?:25[6-9])\.(?:25[6-9])\.(?:0{1,3}|25[6-9])\.)(?!.*:(?:25[6-9])\.(?:25[6-9])\.(?:25[6-9])\.(?:0{1,3}|25[6-9]))((?:\d{1,2}|1\d{2}|2[0-4]\d|25[0-5])\.){3}(?:\d{1,2}|1\d{2}|2[0-4]\d|25[0-5])(?::\d{1,5})?(\/[^\s]*)?$/,
   regexIPv6: /^(https?:\/\/)(\[[0-9A-Fa-f:]+\])(?::\d{1,5})?(\/[^\s]*)?$/
 });

package/src/probes/isRequire/isRequire.js

@@ -17,7 +17,9 @@ function validateNodeRequire(node, { tracer }) {
     return [false];
   }
 
-  const data = tracer.getDataFromIdentifier(id);
+  const data = tracer.getDataFromIdentifier(id, {
+    removeGlobalIdentifier: true
+  });
 
   return [
     data !== null && data.name === "require",
@@ -135,8 +137,12 @@ function main(node, options) {
 
 export default {
   name: "isRequire",
-  validateNode: [validateNodeRequire, validateNodeEvalRequire],
+  validateNode: [
+    validateNodeRequire,
+    validateNodeEvalRequire
+  ],
   main,
+  teardown,
   breakOnMatch: true,
   breakGroup: "import"
 };

package/src/warnings.js

@@ -34,7 +34,7 @@ export const warnings = Object.freeze({
   "suspicious-file": {
     i18n: "sast_warnings.suspicious_file",
     severity: "Critical",
-    experimental: true
+    experimental: false
   },
   "obfuscated-code": {
     i18n: "sast_warnings.obfuscated_code",
@@ -44,12 +44,12 @@ export const warnings = Object.freeze({
   "weak-crypto": {
     i18n: "sast_warnings.weak_crypto",
     severity: "Information",
-    experimental: true
+    experimental: false
   },
   "shady-link": {
     i18n: "sast_warnings.shady_link",
     severity: "Warning",
-    experimental: true
+    experimental: false
   }
 });
 

package/types/api.d.ts

@@ -1,5 +1,12 @@
-import { Warning } from "./warnings.js";
-import { Statement } from "meriyah/dist/src/estree.js";
+// Third-party
+import type { DiGraph, VertexDefinition, VertexBody } from "digraph-js";
+import { Statement } from "meriyah";
+
+// Internal
+import {
+  Warning,
+  WarningName
+} from "./warnings.js";
 
 export {
   AstAnalyser,
@@ -10,8 +17,6 @@ export {
 
   JsSourceParser,
   SourceParser,
-  runASTAnalysis,
-  runASTAnalysisOnFile,
 
   RuntimeOptions,
   RuntimeFileOptions,
@@ -105,25 +110,59 @@ interface SourceParser {
 
 declare class AstAnalyser {
   constructor(options?: AstAnalyserOptions);
-  analyse: (str: string, options?: RuntimeOptions) => Report;
-  analyseFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
+  analyse: (
+    str: string,
+    options?: RuntimeOptions
+  ) => Report;
+  analyseFile(
+    pathToFile: string,
+    options?: RuntimeFileOptions
+  ): Promise<ReportOnFile>;
+  analyseFileSync(
+    pathToFile: string,
+    options?: RuntimeFileOptions
+  ): ReportOnFile;
+}
+
+declare class SourceFile {
+  constructor(source: string, options: any);
+  addDependency(
+    name: string,
+    location?: string | null,
+    unsafe?: boolean
+  ): void;
+  addWarning(
+    name: WarningName,
+    value: string,
+    location?: any
+  ): void;
+  analyzeLiteral(node: any, inArrayExpr?: boolean): void;
+  getResult(isMinified: boolean): any;
+  walk(node: any): "skip" | null;
 }
 
 interface EntryFilesAnalyserOptions {
   astAnalyzer?: AstAnalyser;
   loadExtensions?: (defaults: string[]) => string[];
+  rootPath?: string | URL;
 }
 
 declare class EntryFilesAnalyser {
+  public astAnalyzer: AstAnalyser;
+  public allowedExtensions: Set<string>;
+  public dependencies: DiGraph<VertexDefinition<VertexBody>>;
+
   constructor(options?: EntryFilesAnalyserOptions);
 
   /**
    * Asynchronously analyze a set of entry files yielding analysis reports.
    */
-  analyse(entryFiles: (string | URL)[]): AsyncGenerator<ReportOnFile & { url: string }>;
+  analyse(
+    entryFiles: Iterable<string | URL>,
+    options?: RuntimeFileOptions
+  ): AsyncGenerator<ReportOnFile & { file: string }>;
 }
 
-declare class JsSourceParser implements SourceParser {}
-
-declare function runASTAnalysis(str: string, options?: RuntimeOptions & AstAnalyserOptions): Report;
-declare function runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions & AstAnalyserOptions): Promise<ReportOnFile>;
+declare class JsSourceParser implements SourceParser {
+  parse(source: string, options: unknown): Statement[];
+}