Protecting projects with Stunnix C/C++ Obfuscator using command line

Key facts you need to know

  • Please read C/C++ Obfuscator: Introduction and Key Concepts first.
  • In order to call command line interface of C/C++ 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 cxx-obfus in Terminal.
  • It's VERY VERY bad idea to call cxx-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 C/C++ Obfuscator directly from command line, you can use this approach only if you have to support already existing project that uses C/C++ 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 cxx-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. Create a directory where files protected version of your code will be placed.
  2. Create some script or Makefile that invokes cxx-obfus, that handles all your files; make sure that it allows you to edit command line options applied to all invocations of cxx-obfus in a single place, as you will have to run cxx-obfus on your entire project several times, with different command line options
  3. 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 cxx-obfus to read exceptions from all files in that directory, append -x exceptions to cxx-obfus command line.
  4. Read introduction on what exceptions are.
  5. 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.
  6. 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).
  7. 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).
  8. Build your project with lite level of protection. To achieve this, append
    -x exceptions -i prefix -n none -s none -jam 0
    to command line of cxx-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.

  9. Try to compile your code in output directory. If compiler complains that symbol named ReplacementFor_FunctionName can't be found, it means that FunctionName is a symbol from 3rd-party library, and that symbols from that library were not added to the list of exceptions extacting list of symbols . Add them to the list of exceptions - to file manual.txt in exceptions directory.
  10. Erase all output files and repeat 2 last steps until you get no errors compiling your protected code.
  11. Erase all output files.
  12. Build your project with production level of protection. To achieve this, append
    -x exceptions
    to command line of cxx-obfus generated by command line builder.
  13. Perform very minor checks that protected code works fine.
  14. 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 cxx-obfus manual.