Protecting projects with Stunnix JavaScript Obfuscator using command line

Key facts you need to know

  • Please read JavaScript Obfuscator: Introduction and Key Concepts first.
  • In order to call command line interface of JavaScript Obfuscator and other utilities shipped with it without mentioning path to those utilities, start Project Manager, go to Tools ⇒ Configure command line tools.., and specify any directory listed in your PATH environment variable there. Aliases will be installed to that directory, so you will be able to simply type js-obfus in Terminal.
  • It's VERY VERY bad idea to call js-obfus directly! It's much more recommended to create and operate a project in Project Manager. You can build a project from command line easily: for each project, it's possible to generate a commandline script (or .bat file for Windows) that will perform all operations available via the Build menu of Project Manager (i.e. building, rebuilding and cleaning of the project) by going to Project ⇒ Generate buildscript or Project ⇒ Generate buildscript as .bat file.

    The documentation on using generated buildscripts is available here - it lists all command line flags it supports. So please go to step-by-step guide using GUI (Project Manager), and stop reading this document - as it describes inferior and old approach of using JavaScript Obfuscator directly from command line, you can use this approach only if you have to support already existing project that uses JavaScript Obfuscator directly via command line.

  • There is nice GUI tool to generate command line using GUI, available at Tools ⇒ Command line builder. So you don't need to read documentation on command line options of js-obfus, just use Command line builder to generate command line options.

    Also there is an online version of Command line builder here, so you can avoid starting GUI.

Step-by-step guide using command line

  1. Update use of symbol names in your code mentioned in eval(), by wrapping names of symbols, into calls of OBJNAME(). See more details here.
  2. Test your code, ensuring that it works fine after these changes.
  3. Create a directory where files protected version of your code will be placed.
  4. Create some script or Makefile that invokes js-obfus, that handles all your files; make sure that it allows you to edit command line options applied to all invocations of js-obfus in a single place, as you will have to run js-obfus on your entire project several times, with different command line options
  5. Create a directory named exceptions in the same directory where your code resides. You will be adding exceptions to it - a list of symbol names that should not be changed, one per line. You will store each group of exceptions to separate file, e.g. exceptions extracted automatically should go to exceptions/auto.txt, exceptions composed manually should go to exceptions/manual.txt. In order to tell js-obfus to read exceptions from all files in that directory, append -x exceptions to js-obfus command line.
  6. Add as many libraries that your code uses into directory with your code (e.g. JQuery, Underscore) and modify your Makefile or script so those libraries are also processed. Doing this will reduce the number of libraries that you will be generating exceptions for in the next steps. Do not worry if those libraries are already minified!
  7. Read introduction on what exceptions are.
  8. Generate names of symbols that you are using from a libraries that you are not obfuscating along your project extacting list of symbols and store it to file named auto.txt in exceptions directory.
  9. Put all exceptions that were not extracted by other tools (i.e. exceptions that you've collected manually), to file named manual.txt in exceptions directory (one symbol per line).
  10. Generate names of symbols that you export to other developers extacting list of symbols , store them to file named exported.txt in exceptions directory (one symbol per line).
  11. Build your project with lite level of protection. To achieve this, append
    -x exceptions -i prefix -n none -s none -jam 0 -e 0
    to command line of js-obfus generated by command line builder.

    It will produce code that is rather easy to read. All symbols that are subject to mangling will get ReplacementFor_ string prepended to them.

  12. Now try to run your protected code from the output directory, testing all paths of control if possible. If you get interpreter errors like "ReplacementFor_FunctionName can't be found", most probably it means that FunctionName is a symbol from 3rd-party library. Either try to add that library to your project (so its code also gets obfuscated), or add its symbols to the list of exceptions adding symbols to exceptions by extracting its symbols extacting list of symbols . If you've already done extraction of its symbols, it probably means that extraction did not find some symbols, so you have to add them manually to file manual.txt in exceptions directory.
  13. Erase all output files and repeat 2 last steps until you get no errors running your protected code.
  14. Erase all output files.
  15. Build your project with production level of protection. To achieve this, append
    -x exceptions
    to command line of js-obfus generated by command line builder.
  16. Perform very minor checks that protected code works fine.
  17. Your product will then be ready for shipping.
If something still doesn't work, make sure you've read the recommendations in the NOTES section of the js-obfus manual.