@nodesecure/js-x-ray 4.4.0 → 5.0.1

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,59 +71,58 @@ 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
 
 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
-  });
+```ts
+type WarningName = "parsing-error"
+| "encoded-literal"
+| "unsafe-regex"
+| "unsafe-stmt"
+| "unsafe-assign"
+| "short-identifiers"
+| "suspicious-literal"
+| "obfuscated-code"
+| "weak-crypto"
+| "unsafe-import";
+
+declare const warnings: Record<WarningName, {
+  i18n: string;
+  severity: "Information" | "Warning" | "Critical";
+  experimental?: boolean;
+}>;
 ```
 
 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));
-
+console.log(i18n.getToken(jsxray.warnings["parsing-error"].i18n));
 ```
 
-## Warnings Legends (v2.0+)
-
-> Node-secure versions equal or lower than 0.7.0 are no longer compatible with the warnings table below.
+## Warnings Legends
 
-This section describe all the possible warnings returned by JSXRay.
+> **Warning** versions of NodeSecure greather than v0.7.0 are no longer compatible with the warnings table below.
 
-| 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... |
+This section describe all the possible warnings returned by JSXRay. Click on the warning **name** for additional information and examples.
 
-> 👀 More details on warnings and their implementations [here](./WARNINGS.md)
+| 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
 
@@ -142,7 +141,7 @@ The method take a first argument which is the code you want to analyse. It will
 ```ts
 interface Report {
     dependencies: ASTDeps;
-    warnings: Warning<BaseWarning>[];
+    warnings: Warning[];
     idsLengthAvg: number;
     stringScore: number;
     isOneLineRequire: boolean;
@@ -151,11 +150,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[];
+  dependencies: ASTDeps;
+  isMinified: boolean;
+} | {
+  ok: false,
+  warnings: Warning[];
+}
+```
+
+</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)):
@@ -168,6 +193,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

@@ -1,124 +1,34 @@
-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;
+import {
+  runASTAnalysis,
+  runASTAnalysisOnFile,
+  Report,
+  ReportOnFile,
+  RuntimeFileOptions,
+  RuntimeOptions
+} from "./types/api";
+import {
+  Warning,
+  WarningDefault,
+  WarningLocation,
+  WarningName,
+  WarningNameWithValue
+} from "./types/warnings";
+import { ASTDeps } from "./types/astdeps";
+
+declare const warnings: Record<WarningName, Pick<WarningDefault, "experimental" | "i18n" | "severity">>;
+
+export {
+  warnings,
+  runASTAnalysis,
+  runASTAnalysisOnFile,
+  Report,
+  ReportOnFile,
+  RuntimeFileOptions,
+  RuntimeOptions,
+  ASTDeps,
+  Warning,
+  WarningDefault,
+  WarningLocation,
+  WarningName,
+  WarningNameWithValue
 }
-
-export = JSXRay;
-export as namespace JSXRay;

package/index.js

@@ -9,6 +9,7 @@ import isMinified from "is-minified-code";
 
 // Import Internal Dependencies
 import Analysis from "./src/Analysis.js";
+import { warnings } from "./src/warnings.js";
 
 export function runASTAnalysis(str, options = Object.create(null)) {
   const { module = true, isMinified = false } = options;
@@ -83,43 +84,4 @@ export async function runASTAnalysisOnFile(pathToFile, options = {}) {
   }
 }
 
-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"
-  }
-});
-
-
+export { warnings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodesecure/js-x-ray",
-  "version": "4.4.0",
+  "version": "5.0.1",
   "description": "JavaScript AST XRay analysis",
   "type": "module",
   "exports": "./index.js",
@@ -10,7 +10,7 @@
   "scripts": {
     "lint": "eslint src test",
     "prepublishOnly": "pkg-ok",
-    "test": "cross-env esm-tape-runner 'test/*.spec.js' | tap-monkey",
+    "test": "cross-env esm-tape-runner 'test/**/*.spec.js' | tap-monkey",
     "check": "cross-env npm run lint && npm run test"
   },
   "repository": {
@@ -27,6 +27,7 @@
   ],
   "files": [
     "src",
+    "types",
     "index.js",
     "index.d.ts"
   ],
@@ -44,13 +45,13 @@
     "safe-regex": "^2.1.1"
   },
   "devDependencies": {
-    "@nodesecure/eslint-config": "^1.3.1",
+    "@nodesecure/eslint-config": "^1.4.1",
     "@slimio/is": "^1.5.1",
     "@small-tech/esm-tape-runner": "^2.0.0",
-    "@small-tech/tap-monkey": "^1.3.0",
-    "@types/node": "^17.0.31",
+    "@small-tech/tap-monkey": "^1.4.0",
+    "@types/node": "^17.0.42",
     "cross-env": "^7.0.3",
-    "eslint": "^8.15.0",
+    "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);
+  }
+}