js-confuser 1.7.1 → 1.7.3

package/docs/Integrity.md

@@ -1,15 +1,21 @@
 ## `Integrity`
 
-JSConfuser can detect changes to the source and prevent execution.
+JS-Confuser can detect changes to the source code and terminate execution. 
 
-If the code is determined modified, the tampered code will not run.
+- **⚠️ This can break your code!**
 
-## Usage
+Option name: `lock.integrity`
+
+Option values: `true/false`
+
+### Usage
 
 ```js
 var JsConfuser = require("js-confuser");
 
-JsConfuser.obfuscate("console.log(1)", {
+var sourceCode = "console.log(1)"
+
+JsConfuser.obfuscate(sourceCode, {
   target: "browser",
   lock: {
     integrity: true,
@@ -19,35 +25,22 @@ JsConfuser.obfuscate("console.log(1)", {
 });
 ```
 
-## CLI Usage
-
-```shell
-<coming soon>
-```
-
-## Example
+### Example
 
 Consider the following code:
 
 ```js
 console.log(1)
-```
-
-The output:
 
-```
-> 1
+// 1
 ```
 
 The obfuscated code (from Usage):
 
 ```js
 (function(){var jXwFUz=Math.imul||function(jXwFUz,m9pBnlk){m9pBnlk|=0;var n1mfO$O=(jXwFUz&4194303)*m9pBnlk;if(jXwFUz&4290772992)n1mfO$O+=(jXwFUz&4290772992)*m9pBnlk|0;return n1mfO$O|0};function m9pBnlk(n1mfO$O,humOEA){var DGCgjl=3735928559^humOEA;var S$63Fy1=1103547991^humOEA;for(var Lop2FFS=0,GC2VbAQ;Lop2FFS<n1mfO$O.length;Lop2FFS++){GC2VbAQ=n1mfO$O.charCodeAt(Lop2FFS);DGCgjl=jXwFUz(DGCgjl^GC2VbAQ,2654435761);S$63Fy1=jXwFUz(S$63Fy1^GC2VbAQ,1597334677)}DGCgjl=jXwFUz(DGCgjl^DGCgjl>>>16,2246822507)^jXwFUz(S$63Fy1^S$63Fy1>>>13,3266489909);S$63Fy1=jXwFUz(S$63Fy1^S$63Fy1>>>16,2246822507)^jXwFUz(DGCgjl^DGCgjl>>>13,3266489909);return 4294967296*(2097151&S$63Fy1)+(DGCgjl>>>0)}function n1mfO$O(jXwFUz){return jXwFUz.toString().replace(/ |\n|;|,|\{|\}|\(|\)/g,'')}function y3EzuX9(){console['log'](1)}var yzLesc=m9pBnlk(n1mfO$O(y3EzuX9),957);if(yzLesc==0x7a77799eaf937){return y3EzuX9.apply(this,arguments)}}())
-```
 
-The output:
-```
-> 1
+// 1
 ```
 
 Since only Integrity is enabled, it's pretty easy to find the original code: `console['log'](1)`.
@@ -58,18 +51,32 @@ Let's try to change the `console['log'](1)` to `console['log'](2)`:
 (function(){var jXwFUz=Math.imul||function(jXwFUz,m9pBnlk){m9pBnlk|=0;var n1mfO$O=(jXwFUz&4194303)*m9pBnlk;if(jXwFUz&4290772992)n1mfO$O+=(jXwFUz&4290772992)*m9pBnlk|0;return n1mfO$O|0};function m9pBnlk(n1mfO$O,humOEA){var DGCgjl=3735928559^humOEA;var S$63Fy1=1103547991^humOEA;for(var Lop2FFS=0,GC2VbAQ;Lop2FFS<n1mfO$O.length;Lop2FFS++){GC2VbAQ=n1mfO$O.charCodeAt(Lop2FFS);DGCgjl=jXwFUz(DGCgjl^GC2VbAQ,2654435761);S$63Fy1=jXwFUz(S$63Fy1^GC2VbAQ,1597334677)}DGCgjl=jXwFUz(DGCgjl^DGCgjl>>>16,2246822507)^jXwFUz(S$63Fy1^S$63Fy1>>>13,3266489909);S$63Fy1=jXwFUz(S$63Fy1^S$63Fy1>>>16,2246822507)^jXwFUz(DGCgjl^DGCgjl>>>13,3266489909);return 4294967296*(2097151&S$63Fy1)+(DGCgjl>>>0)}function n1mfO$O(jXwFUz){return jXwFUz.toString().replace(/ |\n|;|,|\{|\}|\(|\)/g,'')}function y3EzuX9(){console['log'](2)}var yzLesc=m9pBnlk(n1mfO$O(y3EzuX9),957);if(yzLesc==0x7a77799eaf937){return y3EzuX9.apply(this,arguments)}}())
 ```
 
-The program no longer outputs anything. Integrity detected the change and stopped execution.
+The program no longer outputs anything. Integrity has detected the change and stopped execution.
+
+### How is this possible?
+
+JavaScript has a sneaky method to view the source code any function. Calling `Function.toString()` on any function reveals the raw source code.
+
+Integrity uses a hashing algorithm on the obfuscated code during the obfuscation-phase. The obfuscator then places checksum functions throughout the output code to verify it's unchanged at runtime.
+
+An additional RegEx is utilized to remove spaces, newlines, braces, and commas. This ensures the hash isn't too sensitive.
 
-## How is this possible?
+### Tamper Detection
 
-JavaScript has a sneaky method to view the source code any function. Calling `.toString()` on any function reveals the raw source code.
-Integrity hashes the code during obfuscation phase and embeds an IF-statement within the code. We used an additional regex to remove spaces, newlines, braces,
-and commas to ensure the hash isn't too sensitive.
+If tampering is detected, the `lock.countermeasures` function will be invoked. If you don't provide a `lock.countermeasures` function, the default behavior is to crash the program.
 
-## Potential Issues
+[Learn more about the countermeasures function](Countermeasures.md).
+
+### Potential Issues
 
 If you decide to use Integrity, consider the following:
 
-1. Any build-tools must not modify the locked code. The code can't be changed after JsConfuser runs.
-2. `.toString()` functionality may not be enabled in your environment (bytenode)
+1. Any build-tools must not modify the locked code. The code can't be changed after JS-Confuser is applied.
+2. `Function.toString()` functionality may not be enabled in your environment (bytenode)
+
+### See also
+
+- [Countermeasures](Countermeasures.md)
+- [Tamper Protection](TamperProtection.md)
+
 

package/docs/RGF.md

@@ -416,4 +416,9 @@ RGF only applies to:
 - Function Declarations or Expressions
 - Cannot be async / generator function
 - Cannot rely on outside-scoped variables
-- Cannot use `this`, `arguments`, or `eval`
+- Cannot use `this`, `arguments`, or `eval`
+
+### See also
+
+- [Control Flow Flattening](./ControlFlowFlattening.md)
+- [Tamper Protection](./TamperProtection.md)

package/docs/RenameVariables.md

@@ -0,0 +1,116 @@
+## `Rename Variables`
+
+Determines if variables should be renamed. (`true/false`)
+
+Option name: `controlFlowFlattening`
+
+Option values: `true/false`
+
+```js
+// Input
+var twoSum = function (nums, target) {
+  var hash = {};
+  var len = nums.length;
+  for (var i = 0; i < len; i++) {
+    if (nums[i] in hash) return [hash[nums[i]], i];
+    hash[target - nums[i]] = i;
+  }
+  return [-1, -1];
+};
+
+var test = function () {
+  var inputNums = [2, 7, 11, 15];
+  var inputTarget = 9;
+  var expectedResult = [0, 1];
+
+  var actualResult = twoSum(inputNums, inputTarget);
+  ok(actualResult[0] === expectedResult[0]);
+  ok(actualResult[1] === expectedResult[1]);
+};
+
+test();
+
+// Output
+var _O2mOcF = function (kB4uXM, w_07HXS) {
+  var ZLTJcx = {};
+  var sXQOaUx = kB4uXM["length"];
+  for (var JYYxEk = 0; JYYxEk < sXQOaUx; JYYxEk++) {
+    if (kB4uXM[JYYxEk] in ZLTJcx) {
+      return [ZLTJcx[kB4uXM[JYYxEk]], JYYxEk];
+    }
+    ZLTJcx[w_07HXS - kB4uXM[JYYxEk]] = JYYxEk;
+  }
+  return [-1, -1];
+};
+var qFaI6S = function () {
+  var fZpeOw = [2, 7, 11, 15];
+  var UJ62R2c = 9;
+  var dG6R0cV = [0, 1];
+  var WgYXwn = _O2mOcF(fZpeOw, UJ62R2c);
+  void (ok(WgYXwn[0] === dG6R0cV[0]), ok(WgYXwn[1] === dG6R0cV[1]));
+};
+qFaI6S();
+```
+
+### Custom Implementation
+
+A custom function can provided as the `renameVariables` option, determining if a variable should be renamed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The variable proposed to be renamed |
+| `isGlobal` | `boolean` | Is the variable defined at the global level? |
+
+```js
+{
+  target: "node",
+  
+  // Avoid renaming a certain variable
+  renameVariables: name=>name != "jQuery",
+}
+```
+
+### Access the renamed variable
+
+The `__JS_CONFUSER_VAR__` function provides a method to access variable mappings. This is especially useful for `eval()` scenarios where you want preserve the mapping.
+
+
+```js
+// Input
+var message = "Hello world!";
+eval(`console.log(${ __JS_CONFUSER_VAR__(message)  })`);
+
+console.log("message was renamed to", __JS_CONFUSER_VAR__(message));
+
+// Output
+var nSgZyJf = "Hello world!";
+eval(`console.log(${"nSgZyJf"})`) // "Hello world!"
+console["log"]("message was renamed to", "nSgZyJf") // message was renamed to nSgZyJf
+```
+
+Even if `Rename Variables` is disabled, the `__JS_CONFUSER_VAR__` will still be removed. (The original name will be returned as a string)
+
+### Never rename a variable
+
+The `__NO_JS_CONFUSER_RENAME__` prefix disables renaming a certain variable. This can be useful for debugging the obfuscator.
+
+```js
+// Input
+var __NO_JS_CONFUSER_RENAME__message1 = "My first message"
+var message2 = "My other message"
+
+console.log(__NO_JS_CONFUSER_RENAME__message1)
+console.log(message2)
+
+// Output
+var __NO_JS_CONFUSER_RENAME__message1 = "My first message";
+var jRLf713 = "My other message";
+
+console.log(__NO_JS_CONFUSER_RENAME__message1),
+console.log(jRLf713)
+```
+
+
+
+
+

package/docs/TamperProtection.md

@@ -0,0 +1,100 @@
+## `Tamper Protection`
+
+Tamper Protection safeguards the runtime behavior from being altered by JavaScript pitfalls. 
+
+**⚠️ Tamper Protection requires eval and ran in a non-strict mode environment!**
+
+- **This can break your code.**
+- **Due to the security concerns of arbitrary code execution, you must enable this yourself.**
+
+Option name: `lock.tamperProtection`
+
+Option values: `true/false/Function`
+
+### 1. Improves `Global Concealing`
+
+Tamper Protection with `Global Concealing` can detect at runtime if certain global functions have been monkey-patched. The following code exemplifies this:
+
+#### (a) Native function check
+
+```js
+var _fetch = fetch;
+fetch = (...args)=>{
+  console.log("Fetch request intercepted!", ...args)
+  return _fetch(...args)
+}
+```
+
+This monkey-patch can be detected by inspecting the `fetch.toString()` value:
+
+```js
+// Untampered
+fetch.toString() // "function fetch() { [native code] }"
+
+
+// Tampered
+fetch.toString()  // "(...args)=>{\n  console.log("Fetch request intercepted!", ...args)\n  return _fetch(...args)\n}"
+```
+
+Certain global functions are checked before each invocation to ensure that (1) the arguments cannot be intercepted and (2) their behavior cannot be altered.
+
+#### (b) Stealthy global
+
+A direct `eval` invocation can access the local scope, only if it has not been redefined.
+
+```js
+let root = {};
+eval("root=this"); // Window {window: ...}
+```
+
+This method securely obtains the real global object for both the browser and NodeJS. Properties on the global object can still be changed however.
+
+### 2. Improves `RGF`
+
+RGF (Runtime-Generated-Functions) behavior's can be altered by overriding the default `Function` constructor. 
+This allows a reverse engineer to inspect the concealed code and alter the behavior of the application.
+
+When `lock.tamperProtection` is enabled, `RGF` will no longer use the `Function` constructor.
+Instead, `eval` will be used with a strict integrity check.
+
+```js
+let check = false;
+eval("check = true")
+if (!check) {
+    throw new Error("Eval was redefined")
+}
+
+const myFunction = eval("function abc(){}; abc");
+```
+
+Eval loses it's local scope access when redefined by a monkey-patched function. This example ensures the concealed code cannot be inspected or behavior be changed.
+
+[Learn more about RGF](RGF.md).
+
+### Custom Implementation
+
+You can provide a custom implementation for `lock.tamperProtection` to control which functions get the native function check.
+
+```js
+{
+  target: "node",
+  lock: {
+    tamperProtection: (fnName) => fnName === "console.log"
+  }
+}
+```
+
+### Disallows Strict Mode
+
+Tamper Protection requires the script to run in non-strict mode. Detection of the script in Strict Mode will be considered tampering. You can control the tampering response using the `lock.countermeasures` option, as detailed in the next section.
+
+### Tamper Detection
+
+If tampering is detected, the `lock.countermeasures` function will be invoked. If you don't provide a `lock.countermeasures` function, the default behavior is to crash the program.
+
+[Learn more about the countermeasures function](Countermeasures.md).
+
+### See also
+
+- [Countermeasures](Countermeasures.md)
+- [RGF](RGF.md)

package/docs/Template.md

@@ -0,0 +1,117 @@
+## `Template`
+
+The Template API provides an easy way to parse code snippets into AST subtrees.
+These AST subtrees can added to the obfuscated code, tailored with custom variable names and logic.
+
+
+### 1. Basic string interpolation
+
+Interpolated strings can use the `{name}` syntax to be replaced. This allows you to create custom-named functions exemplified in the following example:
+
+```js
+import JsConfuser from "js-confuser"
+
+var Base64Template = new JsConfuser.Template(`
+function {name}(str){
+  return btoa(str)
+}
+`);
+
+var functionDeclaration = Base64Template.single({ 
+  name: "atob" 
+});
+
+console.log(functionDeclaration);
+// Node {
+//  type: 'FunctionDeclaration',
+//  start: 3,
+//  end: 47,
+//  id: Node { type: 'Identifier', start: 12, end: 16, name: 'atob' },
+//  expression: false,
+//  generator: false,
+//  async: false,
+//  params: [ Node { type: 'Identifier', start: 17, end: 20, name: 'str' } ],
+//  body: Node { type: 'BlockStatement', start: 21, end: 47, body: [ [Node] ] }
+// }
+```
+
+This simply preprocesses the `{name}` to `"atob"` before parsing. This behavior can let additional code to be inserted and does not properly escape strings. To avoid these pitfalls, use AST subtree insertion.
+
+### 2. AST subtree insertion
+
+```js
+var Base64Template = new JsConfuser.Template(`
+function {name}(str){
+  {getWindow}
+  return {getWindowName}btoa(str)
+}`)
+
+var functionDeclaration = Base64Template.single({
+  name: "atob",
+  getWindowName: "newWindow",
+  getWindow: () => {
+    var code = "var newWindow = {}";
+    return acorn.parse(code).body[0];
+  }
+});
+```
+
+Here, the `getWindow` variable is passed as function that returns an AST subtree. This must be a `Node` object, `Node[]` array, or another Template.
+Optionally, the function can be replaced with the return value if it's already computed.
+
+When utilizing AST-interpolated variables, an additional traversal will need to be ran to replace the plain Identifier nodes.
+
+Regular string interpolation does not require an additional traversal.
+
+### 3. Template subtree insertion
+
+```js
+var NewWindowTemplate = new JsConfuser.Template(`
+  var {NewWindowName} = {};
+`);
+
+var Base64Template = new JsConfuser.Template(`
+function {name}(str){
+  {NewWindowTemplate}
+  return {NewWindowName}.btoa(str)
+}`)
+
+var functionDeclaration = Base64Template.single({
+  name: "atob",
+  NewWindowName: "newWindow",
+  NewWindowTemplate: NewWindowTemplate
+});
+```
+
+The variables are passed into the child templates. This allows you to not have to repeat the `NewWindowName` variable.
+
+### `new Template(template)`
+
+Creates a new Template instance. You can pass multiple templates and a random one will be chosen each interpolation.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `template` | `string` | The source code for the Template |
+
+### `template.compile(variables)`
+
+Compiles the template and returns a Node array (`Node[]`)
+
+Returns the equivalent of a [ESTree `Program.body`](https://github.com/estree/estree/blob/master/es5.md#programs)
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `variables` | `object` | An object of variables |
+
+### `template.single(variables)`
+
+Compiles the template and returns the first Node. (`Node`)
+
+An error will thrown if multiple nodes were parsed. Use this function for singular expressions/declarations.
+
+
+Returns the equivalent of a [ESTree `Program.body[0]`](https://github.com/estree/estree/blob/master/es5.md#programs)
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `variables` | `object` | An object of variables |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-confuser",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "JavaScript Obfuscation Tool.",
   "main": "dist/index.js",
   "types": "index.d.ts",
@@ -22,8 +22,8 @@
   "author": "MichaelXF",
   "license": "MIT",
   "dependencies": {
-    "acorn": "^8.10.0",
-    "escodegen": "^2.0.0"
+    "acorn": "^8.12.1",
+    "escodegen": "^2.1.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.17.6",

package/src/constants.ts

@@ -82,3 +82,20 @@ export const reservedIdentifiers = new Set([
 
 export const noRenameVariablePrefix = "__NO_JS_CONFUSER_RENAME__";
 export const placeholderVariablePrefix = "__p_";
+
+/**
+ * Tells the obfuscator this function is predictable:
+ * -  Never called with extraneous parameters
+ */
+export const predictableFunctionTag = "__JS_PREDICT__";
+
+/**
+ * Tells the obfuscator this function is critical for the Obfuscated code.
+ * -  Example: string decryption function
+ */
+export const criticalFunctionTag = "__JS_CRITICAL__";
+
+/**
+ * Allows the user to grab the variable name of a renamed variable.
+ */
+export const variableFunctionName = "__JS_CONFUSER_VAR__";

package/src/index.ts

@@ -2,6 +2,7 @@ import compileJs, { compileJsSync } from "./compiler";
 import parseJS, { parseSync } from "./parser";
 import Obfuscator from "./obfuscator";
 import Transform from "./transforms/transform";
+import Template from "./templates/template";
 import { remove$Properties } from "./util/object";
 import presets from "./presets";
 
@@ -39,7 +40,7 @@ export async function obfuscateAST(AST, options: ObfuscateOptions) {
 
   options = await correctOptions(options);
 
-  var obfuscator = new Obfuscator(options);
+  var obfuscator = new Obfuscator(options as any);
 
   await obfuscator.apply(AST);
 
@@ -70,7 +71,7 @@ var JsConfuser: IJsConfuser = async function (
 
   options.verbose && console.log("* Obfuscating...");
 
-  var obfuscator = new Obfuscator(options);
+  var obfuscator = new Obfuscator(options as any);
 
   await obfuscator.apply(tree);
 
@@ -96,7 +97,7 @@ export const debugTransformations: IJsConfuserDebugTransformations =
     var frames = [];
 
     var tree = parseSync(code);
-    var obfuscator = new Obfuscator(options);
+    var obfuscator = new Obfuscator(options as any);
 
     var time = Date.now();
 
@@ -141,7 +142,7 @@ export const debugObfuscation: IJsConfuserDebugObfuscation = async function (
 
   const parseTime = performance.now() - beforeParseTime;
 
-  var obfuscator = new Obfuscator(options);
+  var obfuscator = new Obfuscator(options as any);
   var totalTransforms = obfuscator.array.length;
 
   var transformationTimes = Object.create(null);
@@ -183,6 +184,7 @@ JsConfuser.debugTransformations = debugTransformations;
 JsConfuser.debugObfuscation = debugObfuscation;
 JsConfuser.Obfuscator = Obfuscator;
 JsConfuser.Transform = Transform;
+JsConfuser.Template = Template;
 
 if (typeof window !== "undefined") {
   window["JsConfuser"] = JsConfuser;
@@ -193,4 +195,4 @@ if (typeof global !== "undefined") {
 
 export default JsConfuser;
 
-export { presets, Obfuscator, Transform };
+export { presets, Obfuscator, Transform, Template };