docs(helpers): clarify fake() does not execute javascript (#3945)

Author: Shinigami92

src/modules/helpers/eval.ts

@@ -46,7 +46,8 @@ const REGEX_DOT_OR_BRACKET = /\.|\(/;
  * const airlineMethodName = fakeEval('airline.airline.name', faker); // 'bound airline'
  * ```
  *
- * It is NOT possible to access any values not passed as entrypoints.
+ * It is not possible to execute arbitrary JavaScript through this method;
+ * expressions can only resolve properties and methods reachable from the given entrypoints.
  *
  * This method will never return arrays, as it will pick a random element from them instead.
  *

src/modules/helpers/module.ts

@@ -1177,7 +1177,7 @@ export class HelpersModule extends SimpleHelpersModule {
    * e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
    *
    * This method is useful if you have to build a random string from a static, non-executable source
-   * (e.g. string coming from a user, stored in a database or a file).
+   * that you control (e.g. a template authored by a developer or stored in a database or file).
    *
    * It checks the given string for placeholders and replaces them by calling faker methods:
    *
@@ -1200,7 +1200,11 @@ export class HelpersModule extends SimpleHelpersModule {
    * const message = faker.helpers.fake('Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.');
    * ```
    *
-   * It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
+   * The pattern is not evaluated as JavaScript: only faker methods can be called, and any
+   * parameters are parsed as JSON or plain strings. Nevertheless, it is possible for certain
+   * maliciously crafted patterns to use large amounts of memory or CPU time, so the pattern
+   * itself must always be from trusted input. Do not evaluate patterns provided by untrusted
+   * user input or external sources.
    *
    * @param pattern The pattern string that will get interpolated.
    *
@@ -1226,7 +1230,7 @@ export class HelpersModule extends SimpleHelpersModule {
    * e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
    *
    * This method is useful if you have to build a random string from a static, non-executable source
-   * (e.g. string coming from a user, stored in a database or a file).
+   * that you control (e.g. a template authored by a developer or stored in a database or file).
    *
    * It checks the given string for placeholders and replaces them by calling faker methods:
    *
@@ -1252,7 +1256,11 @@ export class HelpersModule extends SimpleHelpersModule {
    * const message = faker.helpers.fake(['Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.']);
    * ```
    *
-   * It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
+   * The pattern is not evaluated as JavaScript: only faker methods can be called, and any
+   * parameters are parsed as JSON or plain strings. Nevertheless, it is possible for certain
+   * maliciously crafted patterns to use large amounts of memory or CPU time, so the pattern
+   * itself must always be from trusted input. Do not evaluate patterns provided by untrusted
+   * user input or external sources.
    *
    * @param patterns The array to select a pattern from, that will then get interpolated. Must not be empty.
    *
@@ -1272,7 +1280,7 @@ export class HelpersModule extends SimpleHelpersModule {
    * e.g. ``const address = `${faker.location.zipCode()} ${faker.location.city()}`;``
    *
    * This method is useful if you have to build a random string from a static, non-executable source
-   * (e.g. string coming from a user, stored in a database or a file).
+   * that you control (e.g. a template authored by a developer or stored in a database or file).
    *
    * It checks the given string for placeholders and replaces them by calling faker methods:
    *
@@ -1295,7 +1303,11 @@ export class HelpersModule extends SimpleHelpersModule {
    * const message = faker.helpers.fake('Your pin is {{string.numeric(4, {"allowLeadingZeros": true})}}.');
    * ```
    *
-   * It is also NOT possible to use any non-faker methods or plain javascript in such patterns.
+   * The pattern is not evaluated as JavaScript: only faker methods can be called, and any
+   * parameters are parsed as JSON or plain strings. Nevertheless, it is possible for certain
+   * maliciously crafted patterns to use large amounts of memory or CPU time, so the pattern
+   * itself must always be from trusted input. Do not evaluate patterns provided by untrusted
+   * user input or external sources.
    *
    * @param pattern The pattern string that will get interpolated. If an array is passed, a random element will be picked and interpolated.
    *

test/modules/helpers-eval.spec.ts

@@ -1,7 +1,12 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { FakerError, faker } from '../../src';
 import { fakeEval } from '../../src/modules/helpers/eval';
 
+// A hostile definition resolving to a function returning a function, mirroring the original GHSA-qxc2-j82w-r537 proof-of-concept.
+const noop = () => {};
+
+const hostileDefinition = { evil: () => noop };
+
 describe('fakeEval()', () => {
   it('does not allow empty string input', () => {
     expect(() => fakeEval('', faker)).toThrow(
@@ -167,4 +172,42 @@ describe('fakeEval()', () => {
       new FakerError("Missing closing parenthesis in '(.iataCode'")
     );
   });
+
+  // Regression test for GHSA-qxc2-j82w-r537: fake()/fakeEval() must never evaluate the expression as JavaScript.
+  // In particular, a (hostile) definition that resolves to a function must not expose the `Function` constructor via a `.constructor` chain, which would allow arbitrary code execution.
+  // Functions are always invoked (never property-accessed), so the constructor chain can never reach `Function`.
+  describe('does not allow arbitrary code execution (GHSA-qxc2-j82w-r537)', () => {
+    const globalWithFlag = globalThis as Record<string, unknown>;
+
+    // Every payload is an observable side effect (setting the global flag), so we
+    // notice if it ever executes instead of a silent expression like `return 1`.
+    const attacks = [
+      'do.evil.constructor(globalThis.__fakerPwned = true)()',
+      'do.evil().constructor(globalThis.__fakerPwned = true)()',
+      'do.evil.constructor.constructor(globalThis.__fakerPwned = true)',
+      'do.evil.constructor.constructor(globalThis.__fakerPwned = true)()',
+      'string.constructor.constructor(globalThis.__fakerPwned = true)()',
+    ];
+
+    beforeEach(() => {
+      globalWithFlag.__fakerPwned = false;
+      faker.definitions.raw.do = hostileDefinition;
+    });
+
+    afterEach(() => {
+      delete faker.definitions.raw.do;
+      delete globalWithFlag.__fakerPwned;
+    });
+
+    it.each(attacks)('rejects %s via fakeEval()', (attack) => {
+      // The expression must always be rejected with the library's own error type, never evaluated as JavaScript.
+      expect(() => fakeEval(attack, faker)).toThrow(FakerError);
+      expect(globalWithFlag.__fakerPwned, attack).toBe(false);
+    });
+
+    it.each(attacks)('rejects %s via helpers.fake()', (attack) => {
+      expect(() => faker.helpers.fake(`{{${attack}}}`)).toThrow(FakerError);
+      expect(globalWithFlag.__fakerPwned, attack).toBe(false);
+    });
+  });
 });