Product: Code Integrity

Last updated on May 28th 2024.

Welcome back to Jscrambler 101! A collection of tutorials on how to use Jscrambler to protect your JavaScript. These tutorials cover Jscrambler version 8.3.

Introduction

Last time, on Jscrambler 101 — First Use, we talked about using our web app, applying transformations, creating templates, and learning how to export transformations as a JSON file, among other tips.

This time, we’re going to talk about Code Annotations.

What are Code Annotations?

Code Annotations are JavaScript comments you can add to your code. They are used to change Jscrambler’s behavior when protecting your app.

Sometimes, the transformations that you apply to protect your code can cause performance issues or obfuscate your code in an undesired way. Code Annotations can be used to counteract these situations.

Streamline This Process with Jscrambler Profiling

Using the Profiling feature, you can let Jscrambler do most of the heavy lifting towards minimizing eventual performance impact. Then, you can still tweak the final result using code annotations.

The existing Code Annotations directives are:

• enable — enables transformations and transformation aliases
• define — defines a transformation alias with custom options
• disable — disables transformations, transformation targets, and transformation aliases
• order — enables transformations and transformation aliases in a specific order (allows repetition)
• target — enables all transformations available for a transformation target

To show you how Code Annotations work, we’re going to use several code snippets. Each snippet will focus on a certain directive.

Enable

Starting with the getSecret function, let’s assume we have a string with sensitive information such as a secret:

function getSecret() {
    return 'This is the secret.';
}

We want to specifically encode this string which has sensitive information, so we add the enable directive locally.

// @jscrambler enable stringEncoding
function getSecret() {
    return 'This is the secret.';
}

This will enable the String Encoding transformation on our string.

function getSecret() {
    return 'u0054u0068u0069u0073u0020u0069u0073u0020u0074u0068u0065u0020u0073u0065u0063u0072u0065u0074u002e';
}

It still looks a bit too easy to decode, so we’re going to add String Concealing as well:

// @jscrambler enable stringEncoding, stringConcealing
function getSecret() {
    return 'This is the secret.';
}

This will become:

var uPIi = {
//string concealing and encoding
};
//...
function getSecret() {
    return uPIi.o(0);
}

Let’s say you’ve added other strings with sensitive information and found it best to simply encode and conceal every string in the file.

function getSecret() {
    return 'This is the secret.';
}
//…

function getAnotherSecret() {
    return 'This is another secret.';
}

We can use global enable to affect the whole file, like this:

// @jscrambler global enable stringEncoding, stringConcealing
function getSecret() {
    return 'This is the secret.';
}
//…

function getAnotherSecret() {
    return 'This is another secret.';
}

This will be transformed into:

var pLZi = {
//string concealing and encoding
};
//...
function getSecret() {
    return pLZi.n(1);
}
function getAnotherSecret() {
    return pLZi.n(0);
}

Now, both displayed secrets have been transformed by String Concealing and String Encoding.

Disable

Imagine you’re using a file that has a global String Encoding, and you have a code block that does operations on a string.

// @jscrambler global enable stringEncoding, numberToString
var a = 'some string';
var b = 1;

//...
for (i = 0; i < 1000; i++) {
    //something happens with strings
    var s = 'disable string encoding here';
    //...
}
var t = 'should be transformed';

Say you don’t want String Encoding to transform the strings inside the loop — as it would affect code performance — but you want all the other strings outside of this loop to be transformed. You can use the disable annotation.

// @jscrambler global enable stringEncoding, numberToString
var a = 'some string';
var b = 1;
//...
// @jscrambler disable stringEncoding
for (i = 0; i < 1000; i++) {
    //something happens with strings
    var s = 'disable string transformations here';
    //...
}
var t = 'should be transformed';

Now Jscrambler will act so that the strings inside the loop won’t be affected by the transformations, but everything else will be affected.

As we only have the String Encoding disabled, you’ll notice that Number to String still works on the for loop.

var a = 'u0073u006fu006du0065u0020u0073u0074u0072u0069u006eu0067';
var b = "1" + 0;
//...
for (i = "0" * 1; i < "1000" - 0; i++) {
    var s = 'disable string transformations here';
}
var t = 'x73x68x6fx75x6cx64x20x62x65x20x74x72x61x6ex73x66x6fx72x6dx65x64';

If you don’t want transformations to occur at all in a code block, use //@jscrambler disable *

// @jscrambler global enable stringEncoding, numberToString
//...
// @jscrambler disable *
function foo() {
    var a = 'I won't be affected';
    function bar() {
        var b = 'I won't be affected either';
    }
    // @jscrambler global enable stringEncoding, numberToString
    var c = 'But I wan't to be affected';
    var d = 2;
}

You will notice that the strings in var a and var b aren’t affected by any transformation. We wanted var c to be affected by these transformations though, so we had to insert a new Jscrambler to enable annotation.

function foo() {
    var a = 'I won't be affected';
    function bar() {
        var b = 'I won't be affected either';
    }
  var c = 'x42x75x74x20x49x20x77x61x6ex27x74x20x74x6fx20x62x65x20x61x66x66x65x63x74x65x64';
  var d = 2;
}

If we want var d=2; to be affected by Number to String though, we’ll have to add another code annotation directly above it, as so:

// @jscrambler enable stringEncoding, numberToString
var c = 'But I wan't to be affected';
// @jscrambler enable stringEncoding, numberToString
var d = 2;

This would become:

var c = 'x42x75x74x20x49x20x77x61x6ex27x74x20x74x6fx20x62x65x20x61x66x66x65x63x74x65x64';
var d = "2" * 1;

Define

Define can be used for transformations that include options, such as Self-Defending, CharToTernaryOperator, and ControlFlowFlattening.

Define works by using both define and enable.

//@jscrambler define charToTernaryOperator {tern: [0,1]} as iR1
//@jscrambler enable iR1
var a = 'o';
var b = 'o';

Here, we’re using the Char to Ternary Operator transformation and setting its option tern, which is the minimum number of ternary operators between 0 and 1. This includes 0 and 1 as the minimum number of ternary operators and generates a random output.

var a = (730.08, 860.34) < 4.43 ? 0x13c4 : 'o';
var b='o';

We could use other numbers such as 2 and 3, so that:

//@jscrambler define charToTernaryOperator {tern: [2,3]} as iR1
//@jscrambler enable iR1
var a = 'o';
var b = 'o';

Would become:

var a = (5523, 8821) < (634, 4753) ? 108.94 < (230.23, 2050) ? 2880 <= 9190 ? 610.76 : (4.35e+2, 521.21) : (false, 6.46e+2) : 'o';
var b='o';

Define is local and will only affect the code block below it — so remember to use global when you want to affect more than one location. For example:

//@jscrambler define charToTernaryOperator {tern: [0,1]} as iR1
//@jscrambler enable iR1
var a= 'o';
//@jscrambler enable iR1
var b= 'o';

Won’t affect var b. But, if we use global, iR1 can be reused in var b.

//@jscrambler global define charToTernaryOperator {tern: [0,1]} as iR1
//@jscrambler enable iR1
var a= 'o';
//@jscrambler enable iR1
var b= 'o';

The transformed code will look like this:

var a = (730.08, 860.34) < 4.43 ? 0x13c4 : 'o';
var b = (273.32, 907.6) === (1500, 5782) ? (9.92e+2, false) : 'o';

Aliases — as all other code annotations — are inherited from upper blocks. So, if you define an alias for a block, you can enable it not only in that block but also in any of the inner statements and blocks without using global.

// @jscrambler define charToTernaryOperator {tern: [0,1]} as iR1
function foo() {
 function bar() {
   // @jscrambler enable iR1
   function baz() {}
 }
}

In this case, only baz() will be affected by the charToTernaryOperator.

Order

Order allows transformations to be executed in a set order. As an example:

// @jscrambler order numberToString, stringEncoding
var strNum= 123;
// @jscrambler order stringEncoding, numberToString
var numStr= 456;

The strNum variable will first be affected by numberToString, followed by stringEncoding, while numStr will first be affected by stringEncoding, then numberToString.

You’ll notice that numStr was only affected by numberToString since at the time stringEncoding was performed, there wasn’t any string to act on.

var strNum = +'x31x32x33';
var numStr = "456" | 0;

Order is best used to handle situations such as these — where the order in which the transformations are applied severely affects the outcome.

Imagine you want to set a specific order for the whole JavaScript source code. To do this, you can use the global modifier.

// @jscrambler global order numberToString, stringEncoding
var strNum = 123;
var numStr = 456;

Will become:

    var strNum = +'u0031u0032u0033';
    var numStr = 'u0034u0035u0036' - 0;

You can also repeat transformations, but the same transformation can only be repeated up to 3 times. Something like:

// @jscrambler order dotToBracketNotation, numberToString, stringEncoding, numberToString, stringEncoding
map.moveTo(0, 0);

It is transformed to:

map['u006du006fu0076u0065u0054u006f'](+'u0030', 'u0030' - +'u0030');

By repeating numberToString and stringEncoding, the numeric arguments produced by the first stringEncoding were transformed and all strings were encoded twice.

Some transformations can only be used once per node. These are:

• charToTernaryOperator
• selfDefending

The order can also be inherited — so if you define a specific order for a block, any inner statement and block will inherit it and combine it with any directive defined at that point. This means that:

// @jscrambler order A, B, C
function foo() {
 // @jscrambler order D, E
 function bar() {}
}

Will be applied in the following order:

// [A, B, C]
function foo() {
 // [D, E, A, B, C]
 function bar() {}
}

Code annotations prioritize local order, so D and E will always be performed before A, B, and C.

Transformations are also merged if they are repeated such as:

// @jscrambler order A, B, C
function foo() {
 // @jscrambler order A, A
 function baz() {}
 // @jscrambler order B
 function qux() {}
}

This will be merged to act in the following manner:

// [A, B, C]
function foo() {
 // [A, A, B, C]
 function baz() {}
 // [B, A, C]
 function qux() {}
}

For the baz function, transformation A is executed twice, as it was defined locally that way.

For the qux function, B is executed before A and C, because the local code annotation has priority over the global annotations and the global B ends up being merged with the local B.

Target

Now, say you have the following function.

function foo() {
    var reallySuperMegaHugeBigLongVar = 'target me!!';
}

You want to target the strings and identifiers in the function but aren’t sure what transformations you should apply. If you were to add a target strings, and identifiers as we do below:

//@jscrambler target strings, identifiers
function foo() {
    var reallySuperMegaHugeBigLongVar = 'target me!!';
}

Then run a protection, you’ll notice that both the string and identifiers are affected. This happens because Jscrambler will target strings and identifiers, applying transformations accordingly.

var aWua = {
//string transformations
};
//...
function foo() {
    var i = aWua["f"](0);
}

The available targets are:

• booleans
• controlFlow
• functions
• identifiers
• numbers
• objects
• predicates
• regularExpressions
• statements
• strings
• variables

Target is equivalent to a global enable of a set of transformations, so it will affect all functions in a file. It’s easy to use — especially if you don’t know what transformations are available but know what you want to protect.

You can test all these Code Annotations on your Dashboard. Simply create a new app, insert the code snippets, and run protection without selecting any transformations.

You’ll see that the resulting code has the protections applied according to the used code annotations. Since we didn’t apply powerful sets of transformations, you can easily see how each code annotation affected each snippet.

Conclusion

You should now be able to use Code Annotations to change Jscrambler’s behavior when protecting specific code blocks.

Don’t forget to use the global modifier when you want to affect the whole source file. Feel free to proceed to one of our other 101 Tutorials:

Enjoy your testing and start protecting your Applications ASAP! If you have any additional questions, feel free to contact us.

Last updated on September 3rd, 2024

Welcome to Jscrambler 101! A collection of tutorials on how to use Jscrambler to protect your JavaScript. These tutorials cover Jscrambler version 8.1.

Introduction

In this tutorial — First Use — you will be introduced to our interface, and we will guide you through the process of making your first protection request. You will learn how to navigate the Web App, make different protections, and protect your own apps. In the final section, we’ll also explain the first steps to using our command-line interface (CLI).

How to Access Your Dashboard

To start using Jscrambler, sign in with the credentials you used to create your account. If you don’t have a Jscrambler account, now is the time to create one by clicking Try Jscrambler for Free or going to the login page.

The first time you open Jscrambler’s web app, you will see a callout message to click the Playground app. After clicking it, you will see a demo screen as shown below:

In this demo, sample code appears on the left side of the text editor. Follow the message bubble and click the Protect App button. Jscrambler will apply code lock protection with real-time notifications, preventing the app from running on any browser except the allow-listed one.

You’ll now be prompted to run your newly protected app. When you run it, our HTML5 racing game will try to run in your current browser, which triggers the code lock.

Because the code lock has the real-time notifications feature enabled, you can now click “See Notifications”. This will lead you to your Live Feed, where you’ll see an alert that someone tried to run the code outside of the lock.

Now, you can proceed to your own dashboard simply by following the message bubble and clicking Dashboard on the top-left menu.

Navigating the Playground App

To use your Dashboard, you must verify your email address.

In the Dashboard, click Playground. This is a sample HTML5 racing game that will enable you to test our transformations. After opening the Playground, you will see a set of pre-configured sample files in the File Tree on the left.

Click the JavaScript file common.js to see its content in the left side of the Text Editor and file information at the bottom-left of the page (as shown in the screenshot).

Now, let’s move on to the right side of the text editor. Here is where you will find the protected code after you apply for protection. You can also find two available tabs:

• Templates — where you can select one of our default templates (or use a template you created) in order to apply a saved set of transformations to the sample code.
• Fine-Tuning — where you can select which individual transformations you want to apply to the source code.

We’ll now go over each of these tabs separately.

Fine-Tuning

On this tab, you can specify the code transformations you want to apply to the source code one by one.

At the top, you’ll see Targets and Advanced tabs. You can select targets and choose the transformations you want to apply easily. If you want to take it one step further, you can select the Advanced tab, where you’ll get an additional set of options for your transformations.

If you hover over each transformation in the Advanced tab, a brief explanation will appear. Take this as an example:

Templates

Templates are saved sets of code protections. As such, they enable you to apply multiple pre-defined transformations without needing to choose them one by one every time.

On this tab, you will find Default Templates and Custom Templates. Default Templates are provided directly by us and contain sets of protections with self-explanatory purposes. As an example, the Advanced Obfuscation template will apply a set of protections that give your code the highest level of obfuscation.

Custom Templates consist of templates you created. Creating a template is simple: head over to the Fine-Tuning tab and select some protections. From there, just click the Create Template button below the transformations. Give your template a name and a description, click Save Template and you’re done!

If you go into the Templates tab you should now see your new Template.

Protecting, Testing, and Downloading the Code

It’s time to start protecting our HTML5 racing game. As you may remember, we can do this two different ways: either by picking protections one by one on the Fine-Tuning tab or by selecting a pre-defined template on the Templates tab.

Let’s test the Advanced Obfuscation template. Select it on the Templates tab. If you’re curious to see which transformations this template includes, simply go to the Fine-Tuning tab and check for yourself.

We’re ready to apply these protections. To do that, press Protect App at the bottom. After the app is protected, you will see the result on the right side of the text editor. If nothing shows up, just click on the common.js file. The result will be similar to this:

All protections you apply in the Playground won’t affect your account balance in any way — you can try everything without any worries.

Now, you can test the newly protected file. To do that, simply click “Run Protected” at the bottom of the screen. You will notice that the app will run normally, even though it’s using obfuscated code.

Downloading your newly protected code is also straightforward: simply press Download App (bottom left) and that’s it.

The transformations we applied during this simple process already go a long way toward protecting your code. They are suitable for obfuscating your functions and objects and concealing their logic.

How to Protect Your Own App

So far, we have covered the basics of Jscrambler by using the Playground app. Now, we will guide you through the process of protecting your own app. To return to the dashboard, click the Dashboard link on the menu.

Once there, you should click the Add App button, enter a name in the input field, like Hello World, select the Protection Type as “Code Integrity”, and click Create to create your own Jscrambler project.
This will redirect you to the Live Feed for your newly created app. To enter the Code Integrity protection builder, click the Protect App option on the left sidebar.

How to Add Your Own File to Be Protected

On the left side of the screen, you’ll see the file tree, where you can check which files have been uploaded to the app. You can add your JavaScript and HTML files or add a single ZIP archive containing your project to the app.

If you click the “Add” button on the left, you can see that a file can be created directly from the interface, uploaded from your device, or obtained through a URL. Choose the most suitable option to add your app.

After you have some files in your file tree, you can apply transformations to your own code.

For tutorial purposes, let’s choose Identifiers Renaming and Whitespace Removal as our transformations (find them after toggling Advanced Options, in the Fine-Tuning tab).

You may notice that some of the transformations are greyed out. This happens because you’re currently using a free trial account. If you want to unlock all Jscrambler features, please upgrade your plan.

With your trial account, you can still try the greyed-out transformations, but only by selecting a predefined template.

You can now protect your app with these transformations and check out what your protected code looks like. After that, it’s ready to be downloaded and used. Remember, you can always create new templates to apply these transformations later.

Jscrambler CLI First Steps

With the Jscrambler CLI, you can easily integrate Jscrambler into your build process.

To get your Jscrambler configuration settings quickly, select the transformations you want (or a template) directly from the dashboard, and then download a JSON file by clicking the cogwheel above the Fine Tuning tab, and then clicking “Download Settings in JSON”.

You can choose whether to download the entire file or the file without your Jscrambler secrets. For the sake of this tutorial, download the entire file by selecting “All Parameters”.

You should have downloaded a file similar to the one below:

{
  "keys": {
    "accessKey": "myAccessKey",
    "secretKey": "mySecretKey"
  },
  "applicationId": "myApplicationID",
  "params": [
        {
      "name": "identifiersRenaming"
    },
    {
      "name": "whitespaceRemoval"
    }
  ],
  "areSubscribersOrdered": false,
  "applicationTypes": {
    "webBrowserApp": false,
    "desktopApp": false,
    "serverApp": false,
    "hybridMobileApp": false,
    "javascriptNativeApp": false,
    "html5GameApp": false
  },
  "languageSpecifications": {
    "es5": true,
    "es6": false,
    "es7": false
  },
  "useRecommendedOrder": true,
  "jscramblerVersion": "8.1",
  "tolerateMinification": true
}

The AccessKey and SecretKey vary by user, while applicationId changes based on the application you are protecting. You can check your application inside the app, above the text editor:
As for your AccessKey and SecretKey, you can check them on the My Profile page, under the “API Credentials” section:
For further directions on using the Jscrambler CLI, check our following 101 article.

Conclusion

This concludes our first tutorial on how to use Jscrambler.

You should now be able to navigate the available apps, create new projects, apply transformations to your code, save them as templates, and download them as a JSON file to use with the API. Enjoy your testing and start protecting your Applications ASAP! If you have any additional questions, feel free to contact us.