@nodesecure/js-x-ray 4.2.1 → 4.5.0

package/README.md

@@ -10,7 +10,7 @@ JavaScript AST analysis. This package has been created to export the [Node-Secur
 
 The goal is to quickly identify dangerous code and patterns for developers and Security researchers. Interpreting the results of this tool will still require you to have a set of security notions.
 
-> 💖 I have no particular background in security. I'm simply becoming more and more interested and passionate about static code analysis. But I would be more than happy to learn that my work can help prevent potential future attacks (or leaks).
+> **Note** I have no particular background in security. I'm simply becoming more and more interested and passionate about static code analysis. But I would be more than happy to learn that my work can help prevent potential future attacks (or leaks).
 
 ## Goals
 The objective of the project is to successfully detect all potentially suspicious JavaScript codes.. The target is obviously codes that are added or injected for malicious purposes..
@@ -71,27 +71,59 @@ console.log(warnings);
 
 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.
+> **Warning** There is also a lot of suspicious code example in the `./examples` cases directory. Feel free to try the tool on these files.
 
-## Warnings Legends (v2.0+)
+## Warnings
 
-> Node-secure versions equal or lower than 0.7.0 are no longer compatible with the warnings table below.
+This section describes how use `warnings` export.
 
-This section describe all the possible warnings returned by JSXRay.
+The structure of the `warnings` is as follows:
+```js
+/**
+ * @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.
+ * @property {string}  warnings[name].severity - Warning severity.
+ */
+ 
+export const warnings = Object.freeze({
+    parsingError: {
+      i18n: "sast_warnings.ast_error"
+      code: "ast-error",
+      severity: "Information"
+    },
+    ...otherWarnings
+  });
+```
+
+We make a call to `i18n` through the package `NodeSecure/i18n` to get the translation.
+
+```js
+import * as jsxray from "@nodesecure/js-x-ray";
+import * as i18n from "@nodesecure/i18n";
+
+console.log(i18n.getToken(jsxray.warnings.parsingError.i18n));
+```
 
-| name | description |
-| --- | --- |
-| parsing-error | An error occured when parsing the JavaScript code with meriyah. It mean that the conversion from string to AST as failed. If you encounter such an error, **please open an issue here**. |
-| unsafe-import | Unable to follow an import (require, require.resolve) statement/expr. |
-| unsafe-regex | A RegEx as been detected as unsafe and may be used for a ReDoS Attack. |
-| unsafe-stmt | Usage of dangerous statement like `eval()` or `Function("")`. |
-| unsafe-assign | Assignment of a protected global like `process` or `require`. |
-| encoded-literal | An encoded literal has been detected (it can be an hexa value, unicode sequence, base64 string etc) |
-| short-identifiers | This mean that all identifiers has an average length below 1.5. Only possible if the file contains more than 5 identifiers. |
-| suspicious-literal | This mean that the sum of suspicious score of all Literals is bigger than 3. |
-| obfuscated-code (**experimental**) | There's a very high probability that the code is obfuscated... |
+## Warnings Legends
 
-> 👀 More details on warnings and their implementations [here](./WARNINGS.md)
+> **Warning** versions of NodeSecure greather than v0.7.0 are no longer compatible with the warnings table below.
+
+This section describe all the possible warnings returned by JSXRay. Click on the warning **name** for additional information and examples.
+
+| name | experimental | description |
+| --- | :-: | --- |
+| [parsing-error](./docs/parsing-error.md) | ❌ | The AST parser throw an error |
+| [unsafe-import](./docs/unsafe-import.md) | ❌ | Unable to follow an import (require, require.resolve) statement/expr. |
+| [unsafe-regex](./docs/unsafe-regex.md) | ❌ | A RegEx as been detected as unsafe and may be used for a ReDoS Attack. |
+| [unsafe-stmt](./docs//unsafe-stmt.md) | ❌ | Usage of dangerous statement like `eval()` or `Function("")`. |
+| [unsafe-assign](./docs/unsafe-assign.md) | ❌ | Assignment of a protected global like `process` or `require`. |
+| [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. |
+| [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...) |
 
 ## API
 
@@ -119,11 +151,37 @@ interface Report {
 
 </details>
 
+<details>
+<summary>runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions): Promise< ReportOnFile ></summary>
+
+```ts
+interface RuntimeOptions {
+    module?: boolean;
+    isMinified?: boolean;
+}
+```
+
+Run the SAST scanner on a given JavaScript file.
+
+```ts
+export type ReportOnFile = {
+  ok: true,
+  warnings: Warning<BaseWarning>[];
+  dependencies: ASTDeps;
+  isMinified: boolean;
+} | {
+  ok: false,
+  warnings: Warning<BaseWarning>[];
+}
+```
+
+</details>
+
 
 ## Contributors ✨
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -136,6 +194,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://www.linkedin.com/in/thomas-gentilhomme/"><img src="https://avatars.githubusercontent.com/u/4438263?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Gentilhomme</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=fraxken" title="Code">💻</a> <a href="https://github.com/NodeSecure/js-x-ray/commits?author=fraxken" title="Documentation">📖</a> <a href="https://github.com/NodeSecure/js-x-ray/pulls?q=is%3Apr+reviewed-by%3Afraxken" title="Reviewed Pull Requests">👀</a> <a href="#security-fraxken" title="Security">🛡️</a> <a href="https://github.com/NodeSecure/js-x-ray/issues?q=author%3Afraxken" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://github.com/Rossb0b"><img src="https://avatars.githubusercontent.com/u/39910164?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nicolas Hallaert</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=Rossb0b" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/antoine-coulon"><img src="https://avatars.githubusercontent.com/u/43391199?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Antoine</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=antoine-coulon" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/Mathieuka"><img src="https://avatars.githubusercontent.com/u/34446722?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mathieu</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=Mathieuka" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/Kawacrepe"><img src="https://avatars.githubusercontent.com/u/40260517?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Vincent Dhennin</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=Kawacrepe" title="Code">💻</a> <a href="https://github.com/NodeSecure/js-x-ray/commits?author=Kawacrepe" title="Tests">⚠️</a></td>
+    <td align="center"><a href="http://tonygo.dev"><img src="https://avatars.githubusercontent.com/u/22824417?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tony Gorez</b></sub></a><br /><a href="https://github.com/NodeSecure/js-x-ray/commits?author=tony-go" title="Code">💻</a> <a href="https://github.com/NodeSecure/js-x-ray/commits?author=tony-go" title="Documentation">📖</a> <a href="https://github.com/NodeSecure/js-x-ray/commits?author=tony-go" title="Tests">⚠️</a></td>
   </tr>
 </table>
 

package/index.d.ts

@@ -17,7 +17,8 @@ declare namespace JSXRay {
     | "unsafe-assign"
     | "short-identifiers"
     | "suspicious-literal"
-    | "obfuscated-code";
+    | "obfuscated-code"
+    | "weak-crypto";
 
   type WarningLocation = [[number, number], [number, number]];
   interface BaseWarning {
@@ -55,15 +56,57 @@ declare namespace JSXRay {
   }
 
   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"
+    parsingError: {
+      code: "ast-error",
+      i18n: "sast_warnings.ast_error",
+      severity: "Information"
+    },
+    unsafeImport: {
+      code: "unsafe-import",
+      i18n: "sast_warnings.unsafe_import",
+      severity: "Warning"
+    },
+    unsafeRegex: {
+      code: "unsafe-regex",
+      i18n: "sast_warnings.unsafe_regex",
+      severity: "Warning"
+    },
+    unsafeStmt: {
+      code: "unsafe-stmt",
+      i18n: "sast_warnings.unsafe_stmt",
+      severity: "Warning"
+    },
+    unsafeAssign: {
+      code: "unsafe-assign",
+      i18n: "sast_warnings.unsafe_assign",
+      severity: "Warning"
+    },
+    encodedLiteral: {
+      code: "encoded-literal",
+      i18n: "sast_warnings.encoded_literal",
+      severity: "Information"
+    },
+    shortIdentifiers: {
+      code: "short-identifiers",
+      i18n: "sast_warnings.short_identifiers",
+      severity: "Warning"
+    },
+    suspiciousLiteral: {
+      code: "suspicious-literal",
+      i18n: "sast_warnings.suspicious_literal",
+      severity: "Warning"
+    },
+    obfuscatedCode: {
+      code: "obfuscated-code",
+      i18n: "sast_warnings.obfuscated_code",
+      severity: "Critical"
+    },
+    weakCrypto: {
+      code: "weak-crypto",
+      i18n: "sast_warnings.weak_crypto",
+      severity: "Information",
+      experimental: true
+   }
   }
 
   interface RuntimeOptions {
@@ -90,9 +133,7 @@ declare namespace JSXRay {
 
   export function runASTAnalysisOnFile(pathToFile: string, options?: RuntimeFileOptions): Promise<ReportOnFile>;
 
-  export namespace CONSTANTS {
-    export const Warnings: WarningsNames;
-  }
+  export const warnings: WarningsNames;
 }
 
 export = JSXRay;

package/index.js

@@ -16,8 +16,13 @@ export function runASTAnalysis(str, options = Object.create(null)) {
   // 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: Boolean(module)
+    next: true,
+    loc: true,
+    raw: true,
+    module: isEcmaScriptModule,
+    globalReturn: !isEcmaScriptModule
   });
 
   const sastAnalysis = new Analysis();
@@ -78,16 +83,59 @@ export async function runASTAnalysisOnFile(pathToFile, options = {}) {
   }
 }
 
-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"
-  })
-};
+export const warnings = Object.freeze({
+  parsingError: {
+    code: "ast-error",
+    i18n: "sast_warnings.ast_error",
+    severity: "Information"
+  },
+  unsafeImport: {
+    code: "unsafe-import",
+    i18n: "sast_warnings.unsafe_import",
+    severity: "Warning"
+  },
+  unsafeRegex: {
+    code: "unsafe-regex",
+    i18n: "sast_warnings.unsafe_regex",
+    severity: "Warning"
+  },
+  unsafeStmt: {
+    code: "unsafe-stmt",
+    i18n: "sast_warnings.unsafe_stmt",
+    severity: "Warning"
+  },
+  unsafeAssign: {
+    code: "unsafe-assign",
+    i18n: "sast_warnings.unsafe_assign",
+    severity: "Warning"
+  },
+  encodedLiteral: {
+    code: "encoded-literal",
+    i18n: "sast_warnings.encoded_literal",
+    severity: "Information"
+  },
+  shortIdentifiers: {
+    code: "short-identifiers",
+    i18n: "sast_warnings.short_identifiers",
+    severity: "Warning"
+  },
+  suspiciousLiteral: {
+    code: "suspicious-literal",
+    i18n: "sast_warnings.suspicious_literal",
+    severity: "Warning"
+  },
+  obfuscatedCode: {
+    code: "obfuscated-code",
+    i18n: "sast_warnings.obfuscated_code",
+    severity: "Critical",
+    experimental: true
+  },
+  weakCrypto: {
+    code: "weak-crypto",
+    i18n: "sast_warnings.weak_crypto",
+    severity: "Information",
+    experimental: true
+  }
+});
+
+

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "@nodesecure/js-x-ray",
-  "version": "4.2.1",
-  "description": "JavaScript AST XRay analysis",
-  "type": "module",
-  "exports": "./index.js",
-  "engines": {
-    "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
-  },
-  "scripts": {
-    "lint": "eslint src test",
-    "prepublishOnly": "pkg-ok",
-    "test": "cross-env esm-tape-runner 'test/*.spec.js' | tap-monkey",
-    "check": "cross-env npm run lint && npm run test"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/NodeSecure/js-x-ray.git"
-  },
-  "keywords": [
-    "ast",
-    "nsecure",
-    "nodesecure",
-    "analysis",
-    "dependencies",
-    "security"
-  ],
-  "files": [
-    "src",
-    "index.js",
-    "index.d.ts"
-  ],
-  "author": "GENTILHOMME Thomas <gentilhomme.thomas@gmail.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/NodeSecure/js-x-ray/issues"
-  },
-  "homepage": "https://github.com/NodeSecure/js-x-ray#readme",
-  "dependencies": {
-    "@nodesecure/sec-literal": "^1.0.1",
-    "estree-walker": "^3.0.1",
-    "is-minified-code": "^2.0.0",
-    "meriyah": "^4.2.0",
-    "safe-regex": "^2.1.1"
-  },
-  "devDependencies": {
-    "@nodesecure/eslint-config": "^1.3.1",
-    "@slimio/is": "^1.5.1",
-    "@small-tech/esm-tape-runner": "^1.0.3",
-    "@small-tech/tap-monkey": "^1.3.0",
-    "@types/node": "^17.0.15",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.8.0",
-    "pkg-ok": "^2.3.1",
-    "tape": "^5.5.0"
-  }
-}
+{
+  "name": "@nodesecure/js-x-ray",
+  "version": "4.5.0",
+  "description": "JavaScript AST XRay analysis",
+  "type": "module",
+  "exports": "./index.js",
+  "engines": {
+    "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+  },
+  "scripts": {
+    "lint": "eslint src test",
+    "prepublishOnly": "pkg-ok",
+    "test": "cross-env esm-tape-runner 'test/**/*.spec.js' | tap-monkey",
+    "check": "cross-env npm run lint && npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NodeSecure/js-x-ray.git"
+  },
+  "keywords": [
+    "ast",
+    "nsecure",
+    "nodesecure",
+    "analysis",
+    "dependencies",
+    "security"
+  ],
+  "files": [
+    "src",
+    "index.js",
+    "index.d.ts"
+  ],
+  "author": "GENTILHOMME Thomas <gentilhomme.thomas@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/NodeSecure/js-x-ray/issues"
+  },
+  "homepage": "https://github.com/NodeSecure/js-x-ray#readme",
+  "dependencies": {
+    "@nodesecure/sec-literal": "^1.1.0",
+    "estree-walker": "^3.0.1",
+    "is-minified-code": "^2.0.0",
+    "meriyah": "^4.2.1",
+    "safe-regex": "^2.1.1"
+  },
+  "devDependencies": {
+    "@nodesecure/eslint-config": "^1.4.1",
+    "@slimio/is": "^1.5.1",
+    "@small-tech/esm-tape-runner": "^2.0.0",
+    "@small-tech/tap-monkey": "^1.4.0",
+    "@types/node": "^17.0.42",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.17.0",
+    "pkg-ok": "^3.0.0",
+    "tape": "^5.5.3"
+  }
+}

package/src/ASTDeps.js

@@ -1,55 +1,63 @@
-
-export default class ASTDeps {
-  #inTry = false;
-  dependencies = Object.create(null);
-
-  get isInTryStmt() {
-    return this.#inTry;
-  }
-
-  set isInTryStmt(value) {
-    if (typeof value !== "boolean") {
-      throw new TypeError("value must be a boolean!");
-    }
-
-    this.#inTry = value;
-  }
-
-  removeByName(name) {
-    if (Reflect.has(this.dependencies, name)) {
-      delete this.dependencies[name];
-    }
-  }
-
-  add(depName, location = null, unsafe = false) {
-    if (depName.trim() === "") {
-      return;
-    }
-
-    const cleanDepName = depName.charAt(depName.length - 1) === "/" ? depName.slice(0, -1) : depName;
-    const dep = {
-      unsafe,
-      inTry: this.isInTryStmt
-    };
-    if (location !== null) {
-      dep.location = location;
-    }
-    this.dependencies[cleanDepName] = dep;
-  }
-
-  get size() {
-    return Object.keys(this.dependencies).length;
-  }
-
-  * getDependenciesInTryStatement() {
-    for (const [depName, props] of Object.entries(this.dependencies)) {
-      if (props.inTry === true && props.unsafe === false) {
-        yield depName;
-      }
-    }
-  }
-
-  * [Symbol.iterator]() {
-    yield* Object.keys(this.dependencies);
-  }
-}
+
+export default class ASTDeps {
+  #inTry = false;
+  dependencies = Object.create(null);
+
+  get isInTryStmt() {
+    return this.#inTry;
+  }
+
+  set isInTryStmt(value) {
+    if (typeof value !== "boolean") {
+      throw new TypeError("value must be a boolean!");
+    }
+
+    this.#inTry = value;
+  }
+
+  removeByName(name) {
+    if (Reflect.has(this.dependencies, name)) {
+      delete this.dependencies[name];
+    }
+  }
+
+  add(depName, location = null, unsafe = false) {
+    if (depName.trim() === "") {
+      return;
+    }
+
+    const cleanDepName = depName.charAt(depName.length - 1) === "/" ? depName.slice(0, -1) : depName;
+    const dep = {
+      unsafe,
+      inTry: this.isInTryStmt
+    };
+    if (location !== null) {
+      dep.location = location;
+    }
+    this.dependencies[cleanDepName] = dep;
+  }
+
+  has(depName) {
+    if (depName.trim() === "") {
+      return false;
+    }
+
+    return Reflect.has(this.dependencies, depName);
+  }
+
+  get size() {
+    return Object.keys(this.dependencies).length;
+  }
+
+  * getDependenciesInTryStatement() {
+    for (const [depName, props] of Object.entries(this.dependencies)) {
+      if (props.inTry === true && props.unsafe === false) {
+        yield depName;
+      }
+    }
+  }
+
+  * [Symbol.iterator]() {
+    yield* Object.keys(this.dependencies);
+  }
+}

package/src/Analysis.js

@@ -24,7 +24,8 @@ const kWarningsNameStr = Object.freeze({
   [_warnings.encodedLiteral]: "encoded-literal",
   [_warnings.shortIdentifiers]: "short-identifiers",
   [_warnings.suspiciousLiteral]: "suspicious-literal",
-  [_warnings.obfuscatedCode]: "obfuscated-code"
+  [_warnings.obfuscatedCode]: "obfuscated-code",
+  [_warnings.weakCrypto]: "weak-crypto"
 });
 
 export default class Analysis {

package/src/constants.js

@@ -43,5 +43,6 @@ export const warnings = Object.freeze({
   encodedLiteral: Symbol("EncodedLiteral"),
   shortIdentifiers: Symbol("ShortIdentifiers"),
   suspiciousLiteral: Symbol("SuspiciousLiteral"),
-  obfuscatedCode: Symbol("ObfuscatedCode")
+  obfuscatedCode: Symbol("ObfuscatedCode"),
+  weakCrypto: Symbol("WeakCrypto")
 });