feat: implement new default isMonkeyPatch probe with monkey-patch warning (#485)

Author: fraxken

.changeset/sparkly-pugs-doubt.md

@@ -0,0 +1,5 @@
+---
+"@nodesecure/js-x-ray": minor
+---
+
+Implement a new monkey-patch warning/probe

README.md

@@ -134,7 +134,8 @@ type WarningName = "parsing-error"
 | "shady-link"
 | "synchronous-io"
 | "log-usage"
-| "serialize-environment";
+| "serialize-environment"
+| "monkey-patch";
 
 declare const warnings: Record<WarningName, {
   i18n: string;
@@ -175,7 +176,7 @@ This section describes all the possible warnings returned by JSXRay. Click on th
 | [data-exfiltration](./docs/data-exfiltration.md) | ❌ | the code potentially attemps to transfer sensitive data wihtout authorization from a computer or network to an external location. |
 | [log-usage](./docs/log-usage.md) | ❌ | The code contains a log call. |
 | [sql-injection](./docs/sql-injection.md) | ❌ | The code contains a SQL injection vulnerability |
-
+| [monkey-patch](./docs/monkey-patch.md) | ❌ | The code alters built-in JavaScript prototype properties |
 
 ## Workspaces
 

docs/monkey-patch.md

@@ -0,0 +1,28 @@
+# Monkey patch
+
+| Code | Severity | i18n | Experimental |
+| --- | --- | --- | :-: |
+| monkey-patch | `Warning` | `sast_warnings.monkey_patch` | ❌ | 
+
+## Introduction
+
+Monkey-patching involves modifying native language objects (prototypes, global functions) at runtime to alter their behavior. While it can serve legitimate purposes like polyfills or extending APIs, it introduces significant security risks: breaking invariants, global side effects, flow hijacking (hooking), stealthy persistence, and concealing malicious activities.
+
+JS-X-Ray raises a `monkey-patch` warning when it detects writes to native prototypes. The signal is intentionally broad to facilitate review: while some legitimate uses exist, any invasive modification deserves inspection.
+
+## Examples
+
+```js
+Array.prototype.map = function() {
+  // alters global map() behavior
+};
+
+Object.defineProperty(String.prototype, "replace", {
+  configurable: true,
+  enumerable: false,
+  writable: true,
+  value: function replacer(search, replaceWith) {
+    // systematic interception of all replace() calls
+  }
+});
+```

workspaces/js-x-ray/src/ProbeRunner.ts

@@ -26,6 +26,7 @@ import isSyncIO from "./probes/isSyncIO.ts";
 import isUnsafeCallee from "./probes/isUnsafeCallee.ts";
 import isUnsafeCommand from "./probes/isUnsafeCommand.ts";
 import isWeakCrypto from "./probes/isWeakCrypto.ts";
+import isMonkeyPatch from "./probes/isMonkeyPatch.ts";
 
 import type { SourceFile } from "./SourceFile.ts";
 import type { OptionalWarningName } from "./warnings.ts";
@@ -100,7 +101,8 @@ export class ProbeRunner {
     isUnsafeCommand,
     isSerializeEnv,
     dataExfiltration,
-    sqlInjection
+    sqlInjection,
+    isMonkeyPatch
   ];
 
   static Optionals: Record<OptionalWarningName, Probe> = {

workspaces/js-x-ray/src/probes/isMonkeyPatch.ts

@@ -0,0 +1,139 @@
+// Import Third-party Dependencies
+import type { ESTree } from "meriyah";
+import {
+  getCallExpressionIdentifier,
+  getMemberExpressionIdentifier
+} from "@nodesecure/estree-ast-utils";
+
+// Import Internal Dependencies
+import type {
+  ProbeMainContext,
+  ProbeContext
+} from "../ProbeRunner.ts";
+import { generateWarning } from "../warnings.ts";
+
+// CONSTANTS
+export const JS_TYPES = new Set([
+  "AggregateError",
+  "Array",
+  "ArrayBuffer",
+  "BigInt",
+  "BigInt64Array",
+  "BigUint64Array",
+  "Boolean",
+  "DataView",
+  "Date",
+  "Error",
+  "EvalError",
+  "FinalizationRegistry",
+  "Float32Array",
+  "Float64Array",
+  "Function",
+  "Int16Array",
+  "Int32Array",
+  "Int8Array",
+  "Map",
+  "Number",
+  "Object",
+  "Promise",
+  "Proxy",
+  "RangeError",
+  "ReferenceError",
+  "Reflect",
+  "RegExp",
+  "Set",
+  "SharedArrayBuffer",
+  "String",
+  "Symbol",
+  "SyntaxError",
+  "TypeError",
+  "Uint16Array",
+  "Uint32Array",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "URIError",
+  "WeakMap",
+  "WeakRef",
+  "WeakSet"
+]);
+
+/**
+ * @description Search for monkey patching of built-in prototypes.
+ * @example
+ * Array.prototype.map = function() {};
+ */
+function validateNodeAssignment(
+  node: ESTree.Node,
+  ctx: ProbeContext
+): [boolean, any?] {
+  if (
+    node.type !== "AssignmentExpression" ||
+    node.left.type !== "MemberExpression"
+  ) {
+    return [false];
+  }
+
+  return validateMemberExpression(node.left, ctx);
+}
+
+function validateDefineProperty(
+  node: ESTree.Node,
+  ctx: ProbeContext
+): [boolean, any?] {
+  if (node.type !== "CallExpression") {
+    return [false];
+  }
+  const id = getCallExpressionIdentifier(node);
+
+  if (
+    (id !== "Object.defineProperty" && id !== "Reflect.defineProperty")
+  ) {
+    return [false];
+  }
+
+  const firstArg = node.arguments.at(0);
+  if (firstArg?.type !== "MemberExpression") {
+    return [false];
+  }
+
+  return validateMemberExpression(firstArg, ctx);
+}
+
+function validateMemberExpression(
+  node: ESTree.MemberExpression,
+  ctx: ProbeContext
+): [boolean, any?] {
+  const iter = getMemberExpressionIdentifier(node, {
+    externalIdentifierLookup: (name: string) => ctx.sourceFile.tracer.literalIdentifiers.get(name) ?? null
+  });
+
+  const jsTypeName = iter.next().value;
+  if (typeof jsTypeName !== "string" || !JS_TYPES.has(jsTypeName)) {
+    return [false];
+  }
+
+  return [
+    iter.next().value === "prototype",
+    `${jsTypeName}.prototype`
+  ];
+}
+
+function main(
+  node: ESTree.Node,
+  options: ProbeMainContext
+) {
+  const { sourceFile, data: prototypeName } = options;
+
+  sourceFile.warnings.push(
+    generateWarning("monkey-patch", { value: prototypeName, location: node.loc })
+  );
+}
+
+export default {
+  name: "isMonkeyPatch",
+  validateNode: [
+    validateNodeAssignment,
+    validateDefineProperty
+  ],
+  main
+};

workspaces/js-x-ray/src/warnings.ts

@@ -10,7 +10,8 @@ import {
 } from "./utils/toArrayLocation.ts";
 
 export type OptionalWarningName =
-  | "synchronous-io" | "log-usage";
+  | "synchronous-io"
+  | "log-usage";
 
 export type WarningName =
   | "parsing-error"
@@ -28,6 +29,7 @@ export type WarningName =
   | "serialize-environment"
   | "data-exfiltration"
   | "sql-injection"
+  | "monkey-patch"
   | OptionalWarningName;
 
 export interface Warning<T = WarningName> {
@@ -126,6 +128,11 @@ export const warnings = Object.freeze({
     i18n: "sast_warnings.sql_injection",
     severity: "Warning",
     experimental: false
+  },
+  "monkey-patch": {
+    i18n: "sast_warnings.monkey_patch",
+    severity: "Warning",
+    experimental: false
   }
 }) satisfies Record<WarningName, Pick<Warning, "experimental" | "i18n" | "severity">>;
 

workspaces/js-x-ray/test/probes/isLiteral.spec.ts

@@ -296,9 +296,9 @@ describe("email collection", () => {
 
     const emails = Array.from(emailSet);
     assert.strictEqual(emails.length, 3);
-    assert.ok(emails.some(e => e.value === "user@example.com"));
-    assert.ok(emails.some(e => e.value === "name.surname@domain.co.uk"));
-    assert.ok(emails.some(e => e.value === "test123@test-domain.org"));
+    assert.ok(emails.some((e) => e.value === "user@example.com"));
+    assert.ok(emails.some((e) => e.value === "name.surname@domain.co.uk"));
+    assert.ok(emails.some((e) => e.value === "test123@test-domain.org"));
   });
 
   test("should not collect invalid email formats", () => {
@@ -311,7 +311,7 @@ describe("email collection", () => {
     `;
     const ast = parseScript(str);
     const emailSet = new CollectableSet("email");
-    const sastAnalysis = getSastAnalysis(isLiteral, { collectables: [emailSet] })
+    getSastAnalysis(isLiteral, { collectables: [emailSet] })
       .execute(ast.body);
 
     const emails = Array.from(emailSet);
@@ -327,21 +327,21 @@ describe("email collection", () => {
     `;
     const ast = parseScript(str);
     const emailSet = new CollectableSet("email");
-    const sastAnalysis = getSastAnalysis(isLiteral, { collectables: [emailSet] })
+    getSastAnalysis(isLiteral, { collectables: [emailSet] })
       .execute(ast.body);
 
     const emails = Array.from(emailSet);
     assert.strictEqual(emails.length, 3);
-    assert.ok(emails.some(e => e.value === "admin@site.com"));
-    assert.ok(emails.some(e => e.value === "support@help.io"));
-    assert.ok(emails.some(e => e.value === "info@company.net"));
+    assert.ok(emails.some((e) => e.value === "admin@site.com"));
+    assert.ok(emails.some((e) => e.value === "support@help.io"));
+    assert.ok(emails.some((e) => e.value === "info@company.net"));
   });
 
   test("should track email locations correctly", () => {
     const str = `const email = "test@example.com";`;
     const ast = parseScript(str);
     const emailSet = new CollectableSet("email");
-    const sastAnalysis = getSastAnalysis(isLiteral, { collectables: [emailSet], location: "test.js" })
+    getSastAnalysis(isLiteral, { collectables: [emailSet], location: "test.js" })
       .execute(ast.body);
 
     const emails = Array.from(emailSet);

workspaces/js-x-ray/test/probes/isMonkeyPatch.spec.ts

@@ -0,0 +1,72 @@
+
+// Import Node.js Dependencies
+import { describe, test } from "node:test";
+
+// Import Internal Dependencies
+import isMonkeyPatch, { JS_TYPES } from "../../src/probes/isMonkeyPatch.ts";
+import { getSastAnalysis, parseScript } from "../utils/index.ts";
+
+describe("isMonkeyPatch", () => {
+  test("should detect monkey patching via direct prototype assignment", (t) => {
+    t.plan(JS_TYPES.size * 2);
+
+    for (const jsType of JS_TYPES) {
+      const computed = Math.random() > 0.5 ? `["prototype"]` : ".prototype";
+      const str = `${jsType}${computed}.any = function() {};`;
+
+      const ast = parseScript(str);
+      const sastAnalysis = getSastAnalysis(isMonkeyPatch);
+      sastAnalysis.execute(ast);
+
+      const outputWarnings = sastAnalysis.warnings();
+
+      t.assert.equal(outputWarnings.length, 1);
+      t.assert.partialDeepStrictEqual(outputWarnings[0], {
+        kind: "monkey-patch",
+        value: `${jsType}.prototype`
+      });
+    }
+  });
+
+  test("should detect monkey patching via Object.defineProperty", (t) => {
+    const str = `Object.defineProperty(Array.prototype, "map", {
+      configurable: true,
+      enumerable: false,
+      writable: true,
+      value: function mapper(fn, thisArg) {}
+    });`;
+
+    const ast = parseScript(str);
+    const sastAnalysis = getSastAnalysis(isMonkeyPatch);
+    sastAnalysis.execute(ast);
+
+    const outputWarnings = sastAnalysis.warnings();
+
+    t.assert.equal(outputWarnings.length, 1);
+    t.assert.partialDeepStrictEqual(outputWarnings[0], {
+      kind: "monkey-patch",
+      value: "Array.prototype"
+    });
+  });
+
+  test("should detect monkey patching via Reflect.defineProperty", (t) => {
+    const str = `Reflect.defineProperty(Array.prototype, "map", {
+      configurable: true,
+      enumerable: false,
+      writable: true,
+      value: function mapper(fn, thisArg) {}
+    });`;
+
+    const ast = parseScript(str);
+    const sastAnalysis = getSastAnalysis(isMonkeyPatch);
+    sastAnalysis.execute(ast);
+
+    const outputWarnings = sastAnalysis.warnings();
+
+    t.assert.equal(outputWarnings.length, 1);
+    t.assert.partialDeepStrictEqual(outputWarnings[0], {
+      kind: "monkey-patch",
+      value: "Array.prototype"
+    });
+  });
+});

workspaces/js-x-ray/test/probes/log-usage.spec.ts

@@ -10,7 +10,7 @@ import { AstAnalyser } from "../../src/index.ts";
 // CONSTANTS
 const kFixtureURL = new URL("fixtures/logUsage/", import.meta.url);
 
-test("it should detect log methods", async () => {
+test("it should detect log methods", async() => {
   const fixtureFiles = await fs.readdir(kFixtureURL);
   for (const fixtureFile of fixtureFiles) {
     const fixture = readFileSync(new URL(fixtureFile, kFixtureURL), "utf-8");