@nodesecure/js-x-ray 4.4.0 → 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,25 +71,27 @@ 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:
-```
+```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 {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
   });
@@ -97,33 +99,31 @@ export const warnings = Object.freeze({
 
 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));
-
 ```
 
-## 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
 
@@ -151,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)):
@@ -168,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

@@ -1,124 +1,140 @@
-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;
+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"
+    | "weak-crypto";
+
+  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",
+      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 {
+    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

@@ -86,39 +86,55 @@ export async function runASTAnalysisOnFile(pathToFile, options = {}) {
 export const warnings = Object.freeze({
   parsingError: {
     code: "ast-error",
-    i18n: "sast_warnings.ast_error"
+    i18n: "sast_warnings.ast_error",
+    severity: "Information"
   },
   unsafeImport: {
     code: "unsafe-import",
-    i18n: "sast_warnings.unsafe_import"
+    i18n: "sast_warnings.unsafe_import",
+    severity: "Warning"
   },
   unsafeRegex: {
     code: "unsafe-regex",
-    i18n: "sast_warnings.unsafe_regex"
+    i18n: "sast_warnings.unsafe_regex",
+    severity: "Warning"
   },
   unsafeStmt: {
     code: "unsafe-stmt",
-    i18n: "sast_warnings.unsafe_stmt"
+    i18n: "sast_warnings.unsafe_stmt",
+    severity: "Warning"
   },
   unsafeAssign: {
     code: "unsafe-assign",
-    i18n: "sast_warnings.unsafe_assign"
+    i18n: "sast_warnings.unsafe_assign",
+    severity: "Warning"
   },
   encodedLiteral: {
     code: "encoded-literal",
-    i18n: "sast_warnings.encoded_literal"
+    i18n: "sast_warnings.encoded_literal",
+    severity: "Information"
   },
   shortIdentifiers: {
     code: "short-identifiers",
-    i18n: "sast_warnings.short_identifiers"
+    i18n: "sast_warnings.short_identifiers",
+    severity: "Warning"
   },
   suspiciousLiteral: {
     code: "suspicious-literal",
-    i18n: "sast_warnings.suspicious_literal"
+    i18n: "sast_warnings.suspicious_literal",
+    severity: "Warning"
   },
   obfuscatedCode: {
     code: "obfuscated-code",
-    i18n: "sast_warnings.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.4.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.3.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",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.15.0",
-    "pkg-ok": "^3.0.0",
-    "tape": "^5.5.3"
-  }
-}
+{
+  "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"
+  }
+}