User Manual_Virbox Protector Command Line

User Manual:

Virbox Protector Command Line Tool

Virbox Protector supports developer to protect applications in both GUI tool and CLI tool.

Here we introduce how to use "Command Line Interface of Virbox Protector to protect applications.

Prerequisites

Sign-up Virbox Protector, get the trial license and install the Virbox Protector in your machine;

Go to the \bin sub directory of installation directory of Virbox Protector, besides of the GUI tool of Virbox Protector, you will find 2 command line interface tools in the same of installation directory:

Virbox Protector CLI tool:

virboxprotector_con.exe

DS Protector CLI tool (DS Protector is the tool for software developer to protect their data resource, more details information, pls refer the relevant document):

dsprotector_con.exe

(Above prerequisites is for test/evaluation Virbox Protector only.

To protect formal release software, pls purchase and get the related Virbox Protector license)

1. Start to use Virbox Protector CLI tool

The on default path forVirbox Protector CLI tools: virboxprotector_con.exe are:

Windows:
C:\Program Files\senseshield\Virbox Protector 3\bin

Linux:
/usr/share/virboxprotector/bin

macOS:
/Applications/Virbox Protector 3.app/Contents/MacOS/bin

When you call Virbox Protector Command line tool and execute the Virbox protector,

You may:

Either to specify the full absolutely path, for example:

"C:\Program Files\senseshield\Virbox Protector 3\bin\virboxprotector_con.exe" <file_path>      <options ..> -o <output_path>

Or,

in windows system , you may add the environmental variable and directly input:

virboxprotector_con

and no need to specify the full path to execute the Virbox Protector.

For non windows system: you may set the Symbolic Link, like this sample below:

sudo ln -s /usr/share/virboxprotector/bin/virboxprotector_con /usr/local/bin/virboxprotector_con

Then you can directly input: virboxprotector_con to protect your applications.

2. The main protection function/feature of Virbox Protector CLI tool:

To protect desktop or mobile application, you can call Virbox Protector CLI tool and specify the application path and out path to protect your applications. Virbox Protector will automatically to recognize the application types;

Like with Virbox Protector tool, Developer may use "option" to set and specify the "Protection option" to the application protected, includes “Function Option”, "Protection Option", "Data & Resource Protection" etc.

On default, if developer doesn't specify output folder, after protection succeed, a new \protected folder will be generated, the protected application with same file name located in the new directory. 

virboxprotector_con <file_path> <options ...> -o <output_path>

To get help information, use following command:

virboxprotector_con

or

virboxprotector_con --help=?

to view help information to each type of application in details:

For dsprotector_con

dsprotector_con <filename|directory> <-c ssp>

To get help information, execute

dsprotector_con

or

dsprotector -?

Specify application type to view help information in detail:

native|dotnet|apk|aab|aar|app|u3d|java-bce|java-vme|h5|strip|u3dres|mulpkg|ilmerge

For example, get help information to protect Android AAB package:

virboxprotector_con --help=aab

For some special application type, it is required to specify the argument accordingly.

Application type and protection optionArgument

Protect the Java apps with BCE protection mode

-java

Protect the Java apps with VME protection mode

N/A, on default to use VME

Protection Unity3D app and resource encryption (Windows/Linux hot update)

-u3dres

Protection the HTML 5 (.js file)

-h5

To remove the debugging information from ELF file (strip)

-strip

Protect and archive with multiple package

-mulpkg

Protect and merge assemblies

-ilmerge

Example:

virboxprotector_con -java <java_dir> <other_options ...>

The Syntax of Virbox Protector CLI with long options

For most of command line options, the syntax is:

--{opt}=value

1 means enable/switch on

0 means disable/switch off

Sample

--mem-check=1, --jit-enc=0

How to get the CLI's Help

For more detail instruction/help to use VBP CLI's options/arguments,

use: --help={type} to view the CLI helps:

virboxprotector_con --help=apk

The application supports to get "help" includes:

--help={native|dotnet|apk|aab|aar|app|u3d|java-bce|java-vme|h5|strip|u3dres|mulpkg|ilmerge}

native application means the native types of application to the operation system, and it doesn't need the Virtual machine environment or interpreter when executed. usually, these native application compiled by C/C++/Delphi/VB6 program language, which includes:

​ The PE program in the Windows system(with the suffix of .exe/.dll/.sys );

​ The Elf programs in the Linux/Android system (with the suffix of .so or main program);

​ The MachO application (.dylib or main program) in the macOS/iOS system.

3. The way using Virbox Protector CLI to protect applications

Unlike with by using the Virbox Protector GUI tool, developer to set protection option by "select and click", when Developer use the CLI tool to set the protection setting, there are 2 ways for Software developer to set the protection option by use of Virbox Protector CLI tool to protect their project.

Option 1: With protection configuration file

Configuration file (suffix .ssp) is the file which generated by Virbox Protector GUI tool which save the protection option setting. Developer use Virbox Protector GUI tool to generate the protection configuration file (the configuration file suffix is .ssp file, which store the protection setting to functions protection setting, general protection setting etc..) and then save the configuration file together with the project which to be protected in the same folder, then use Virbox Protector CLI (no need to specify argument, option, since all of protection setting has been saved in the configuration file) to protect the project accordingly.

Option 2: Without Protection Configuration file

Use CLI tool to protect the software project directly, with specified the argument, option which to define the functions protection option and general protection options.

Developer may use VBP CLI tool to protect different kind of application with multiple arguments and options.

if no specified argument/option has been used in Virbox CLI tool, the protection setting will be used on default.

Option 1 example

Here we use a native executive file to be a example to show how to use Virbox Protector GUI tool to generate a protection configuration file (.ssp file) and then use the CLI tool and the configuration file to protect the original native executive file.

Step1, Generate the "Protection Configuration File"

Open the Virbox Protector GUI tool, drag the native file into Virbox Protector GUI tools, set the protection option in the Function Option tab and Protection Option tab;

Click the button (menu): Save Selected Configuration which save the configuration file generated (suffix name is .ssp in the output folder

Go to output folder

Go to the output folder, find the .ssp file and save the configuration file in the same folder together with native file which to be protected.

Step 2

Use Virbox Protector CLI tool to protect the native project file

Virbox Protector standard command to protect applications:

virboxprotector_con <file_path> <options ...> -o <output_path>

C:\the absolutely path of virbox protector\virboxprotector_con the absolutely path of protected file\protected filename -o absolutedly path of output file\output file name

sample:

if no configuration file generated or not be found the configuration file in same folder

Virbox Protector CLI tool will use protection option setting on default to protect the project:

The on default protection option setting for:

Native Project:

Compression and Memory Check

.NET Project:

Compression and JIT Encryption;

if you want to specify to protect the concrete function with Code encryption or Code Obfuscation, you need to generate the protection configuration file first. and follow the protect step above.

ELF Project:

Compression and Memory Check;

MachO Project:

Memory Check

Android APK:

On default protection setting:

On default anti debug

4. The Protected Application Type & Protection Options setting

From the section below, we will introduce how to use Virbox CLI tools (or Combine with GUI tools) to protect different kind of project, or different language.

CLI command to protect application:

virboxprotector_con <apk_path> filename <options ...> [-o <output_path>]

Protect Android APK/AAB

Virbox Protector CLI command to use to protect Android AAB or Apk.

virboxprotector_con <apk_path> <options ...> [-o <output_path>]

View help info

Protection OptionsCLI argumentsOn default value:

Dex Encryption

--dex-enc=

APK:1, AAB:0

File Verification

--file-check=

1

Signature Verification

--sign-check=

0

Anti-Injection

--anti-inject=

1

Detect the debug tool

--detect-dbg=

0

Detect the simulator

--detect-emu=

0

Root Detection

--detect-root=

0

Multi parallel Detection

--detect-multi=

0

Output apks (Valid when enable the AAB signature)

--apks=<apks_path>

N/A

1 means enable/switch on

0 means disable/switch off

Resource Encryption

Virbox Protector (include GUI tool and CLI tool) support developer to protect the data, image resource attached together with the Android application.

Use the argument: --res-enc=1 to enable the Resource encryption options,

Use the ; to separate the resource file list, support the wild card *

OptionCLI argumentOn default Argument value

Enable

--res-enc=

0

Resource list

-res <resource_list>

On default to protect all resource file

Sample:

--res-enc=1 -res "file1;file2;assets/file1;assets2/*"

Function Protection Option

Besides of General protection option setting to applications, Virbox Protector supports developer to protect the specified function/methods, for APK and AAB's Functions Protection, Virbox Protector provides the feature: "Code of Virtualization" to protect the functions/method. which is most secured Protection options to specified functions to Android APK/AAB applications.

On default setting to "Code of Virtuallization" is to protect the methods of entry class of Application and Main Activity's class.

If you want to protect the specific functions/methods, pls refer:

Function Option

Archive application to multiple packages

To archive the application to multiple package template, pls refer:

Archive with multiple package

Signature

Virbox Protector support developer to use signature, for Signature Options setting, pls refer:

Signature option

Sample

virboxprotector_con app-release.apk 
	--dex-enc=1 --file-check=1 --detect-dbg=0 --sign-check=1
	--res-enc=1 -res "assets/*;res/*"
	--hide-symtab=0 -lib "lib/armeabi-v7a/libhello.so;/lib/arm64-v8a/*"
	--sign=1 --ks="test/android.ks" --ks-pass=mypass --ks-key-alias=CERT --key-pass=mykeypass
	-o app-release-protected.apk

Protect AAR package

Virbox Protector support to protect Android AAR pacakge with Code of Virtualization, and to protect the .so libs of AAR package:

Virbox Protector CLI toolCommand used:

virboxprotector_con <aar_path> <options ...> [-o <output_dir>]

Sample (Sample shows to protect the all of the class method of “test.aar” package and protect all of .so libs, "v" means "virtualization")

virboxprotector_con test.aar -v "com.example.*" -lib "jni/*" -o protected/test.aar

Protect the Android .SO lib **

Virbox Protector CLI command to protect Android .so libs

virboxprotector_con <Android.so lib_path> <options ...> [-o <output_path>]

OptionCLI argumentOn default Argument value

Hide the symbol table

--hide-symtab=

0

Resource list

-lib <nativelib_list>

N/A

--hide-symtab=0 -lib "lib/armeabi-v7a/libhello.so;/lib/arm64-v8a/*"

Protect the PE and native application

virboxprotector_con <native_path> <options ...> [-o <output_dir>]

Protection OptionCLI argumentsOn default argument value

Compression

--pack=

1

Memory Check

--mem-check=

1

Import table protection

--imp-protect=

1

Resource section protection

--res-sect-enc=

1

Protect/encrypt PE overlay

--overlay-enc=

1

Detect the debug tool

--detect-dbg=

0

VM detection

--detect-vm=

0

here value setting:

1 means enable/switch on

0 means disable/switch off

Protect the ELF

OptionCLI argumentsOn default argument value

Compression

--pack=

1

Memory Check

--mem-check=

1

Detect the debug tool

--detect-dbg=

0

Strip the symbol table of ELF file

--strip-dbginfo=

1

here value setting:

1 means enable/switch on

0 means disable/switch off

Protect the MachO

Protection OptionCLI argumentOn default Argument value

Memory Check

--mem-check=

1

Detect debug tool

--detect-dbg=

0

For how to sign and use signature, pls refer:

Signature Options

Here value setting:

1 means enable/switch on

0 means disable/switch off

Protect iOS App

Virbox Protector CLI command to protect iOS App

virboxprotector_con <input_path> <options ...> [-o <output_path>]

Protection OptionCLI ArgumentOn default Argument value

Memory Check

--mem-check=

1

Detect Debug tool

--detect-dbg=

0

Objective-C: Name of Obfuscation to Objective C

--objc-rename=

0

Output path

-o

protected/<file_name>

IPA path (enable signature required)

--ipa=<ipa_path>

None

Here value setting:

1 means enable/switch on

0 means disable/switch off

Signature Option

Pls refer the signature of iOS/macOS in the "Signature Option".

Protect .NET project

Virbox Protector CLI command to protect dotNET project

virboxprotector_con <input_path> <options ...> [-o <output_path>]

Protection OptionCLI ArgumentOn default Argument Value

Compression

--pack=

0

JIT Encryption

--jit-enc=

1

String Encryption

--str-enc=

1

Overlay encryption

--overlay-enc=

1

Detect the debug tool

--detect-dbg=

0

Name of Obfuscation

--rename=

0

Keep the rules of Name of obfuscation

--keep-rules=

""

here value setting:

1 means enable/switch on

0 means disable/switch off

If No overlay data attachment, then ignore the argument: --overlay-enc 。

Name of Obfuscation Options:

--rename=0 Off, disable the feature of Name of obfuscation;

--rename=1 Set the name of Obfuscation to private member

--rename=2 Reserve/keep the name of self-defined and not obfuscated.

Keep the Rule of Name of Obfuscation

Use the semicolon: ;to separate the functions/methods, support to use wild card *

Sample

virboxprotector_con test.dll --pack=0 --jit-enc=1 --str-enc=1 --rename=2 --keep-rules="MyNamespace.MyInterface.*;MyNamespace.ExportForInvoke.*"

Function Protection Option Setting

Virbox Protector support developer to set the protection option to "fucntions/methods level (with fine grained level protection), To those critical methods/functions, Developer may select and set the protection mode to specified functions, with "Encryption", "Obfuscation", and "Virtualization".

Pls refer the "Function Protection Option", on default to encrypt the code of entry functions.

SDK label

For some special methods and code, Developer may use the "SDK label to label in project code process. when Developer use the Virbox protector to protect the .net project. Virbox Protector will capapible and recognized these code label and protected.

For .NET project, Virbox Protector support developer to label the critical functions/methods with 2 protection options: Code Encryption and Code Obfuscation.

set the label to the functions code (start and ending), then project compiled and developer use Virbox protector to protect the project. GUI tools will show these functions with protection mode accordingly.

See SDK label section for detail.

SDK sample for .NET project:

//Name

namespace Virbox{

//Code obfuscation

class Mutate : System.Attribute

{

}

//Code encryption

class Encrypt: System.Attribute

{

}

}

public class main

{

[Virbox.Mutate]//code obfuscation

public static void test1(string[] args)

{

System.Console.WriteLine("hello Virbox.Mutate!");

}

[Virbox.Encrypt]//Code Encryption

public static void test2(string[] args)

{

System.Console.WriteLine("hello Virbox.Encrypt!");

}

public static void Main(string[] args)

{

test1(args);

test2(args);

}

}

Protect Unity3D project

Virbox Protector CLI tool command to protect Unity3D project

virboxprotector_con <input_path> <options ...> [-o <output_path>]

Protection OptionCLI ArgumentOn default Argument value

Memory Check (Valid for il2cpp)

--mem-check=

1

File Check （Valid for Android)

--file-check=

1

Signature check (Valid for Android)

--sign-check=

0

Anti Injection（Valid for Android）

--anti-inject=

1

Protect Unity Engine （Valid for Android il2cpp project only）

--unity-engine-protect=

1

MetaData, name of Obfuscation（Valid for il2cpp）

--metadata-rename=

0

Detect debug tool

--detect-dbg=

1

Detect simulator (Valid for Android Only)

--detect-emu=

0

Root Detection (Valid for Android only)

--detect-root=

0

Parallel detection

--detect-multi=

0

Encrypt the assembly

Use -asm to specify assembly list and use semicolon: ; to separate each assembly, support wild card *，On default to encrypt the .dll which prefix by Assembly-CSharp and Assembly-UnityStrcip and not necessary to specify these assembly accordingly.

Sample:

-asm "Data/Managed/Assembly-CSharp.dll;Data/Managed/Assembly-CSharp-first.dll"

Resource Encryption

Use the option: --res-enc=1 to enable "Resource encryption" to protect resources, ，use the semicolon ; to be separator between the resource list , wild card * supported.

Protection OptionCLI ArgumentOn default argument Value

Enable

--res-enc=

1

Protection Priority by resources size (valid for android and iOS only)

--res-favor-size=

0

Set the Password to Resource encryption (Valid for Windows/Linux only)

--res-pass=

N/A

Resource list

-res <resource_list>

On default to protect all resource.

Sample:

--res-enc=1 -res "file1;file2;assets/file1;assets2/*"

Protect Java Project

Virbox Protector support developer to protect Java Project with different kind of protection mode:

Java BCE mode

and

Java VME mode

For the difference between these 2 protection mode, pls refer the related section in the Virbox Protector User Manual.

Note: 2 different license required to use these 2 protection mode.

Protect Java project with Java-BCE Protection mode

Virbxo Protector CLI command to protect Java project (with BCE protection mode)

virboxprotector_con -java <project_directory> [--java-pass=<password>] [-o <output_directory>]
Protection OptionCLI ArgumentOn default Argument value/setting

Set the password

--java-pass=

Random password

Encrypt the JAR embedded

--include-embedded=

0

Specify the Output path

-o <path>

xxxx_protected

Sample:

virboxprotector_con -java my_java_dir --java-pass=12345 --include-embedded=1 -o my_java_dir_protected

After protection successed, you will find 3 new file has been generated in the specified output folder:

  1. the new protected jar file

  2. ReadMe.txt (which describe how to deploy when execute the protected jar file;

  3. sjt_agent.jar

How to deploy when execute the protected JAR file (ReadMe.text)

There are 2 ways to deployed Jar file when executed

Option 1:

Use command line to specify and add sjt_agent to JAR, see sample:

java -javaagent:"D:\test\sjt\sjt_agent.jar" -jar test.jar

Option 2:

For "Tomcat" framework or other special framework which profile can be used to setup option, for example, setenv.sh, developer may edit the profile and add -javaagent option, for how to edit the profile, pls refer relevant document.

JAR deployment

WAR deployment

pls refer related sections in Protect Java Project with GUI tool.

Protect Java project with Java-VME mode

Java-VME support to protect the Java method with "code of Virtualization" only, which is most of secure way to protect the Java method.

There are 3 ways to protect Java project with VME protection mode:

  1. Use Virbox Protector GUI to generate the configuration file, and then use Virbox Protector CLI to protect java project;

  2. Use Virbox Protector CLI tools to protect Java project directly (go through this way in below section;

  3. SDK lable to those critical method, Virbox Protector support developer to set a SDK label to those critical method, then use CLI tool to protect Java Project.

Virbox Protector CLI command to protect Java Project with VME protection mode

virboxprotector_con <jar_path> <options ...> [-o <output_dir>]

Sample 1 ( Protect all of methods of "test1" and "test2" with "Virtualization" ):

virboxprotector_con my_jar.jar -v "com.example.test1.*;com.example.test2.*" -o protected/my_jar.jar

Sample 2(Protect all of methods in the JAR archive)：

virboxprotector_con my_jar.jar -v "*" -o protected/my_jar.jar

SDK label

For some critical functions/methods, Virbox Protector also support developer to set SDK label to those functions/methods in project coding process. for more detail how to use/set SDK label to these functions/method in coding process, pls refer next chapter.

pls refer SDK label section

Protect HTML 5 Project

virboxprotector_con -h5 <dir_or_file> -o <output_path>

Protect Python Project (Scripting language project)

To protect Python project, or other similar Scripting language project, the protection process consists 2 parts:

  1. Protect “python.exe", in this part, Developer may use Virbox protector GUI tool to generate configuration file or use CLI tools to protect the "Python.exe" directly.

  2. Protect "py" or "pyc" file, in this section developer use dsprotector_con to protect py or pyc file.

Here we introduce how to protect the Python project steps by steps

Step 1: Protect "python.exe"

Option 1: Use Virbox Protector CLI to protect python.exe, The protection process pls refer related native protection section above.

Option 2: Use Virbox Protector GUI tool to generate the configuration file which save the "Protection option" setting.

Pls following below 2 steps to generate the configuration file to python.exe. kindly remind, to switch on "DS" button and input the password.

save the the configuration file (.ssp file) with the same folder of "py" or "pyc" file.

the configuration file to python.exe is: python.exe.ssp

Step 2: Use DS Protector CLI to protect py or pyc file/pyc file folder.

dsprotector_con <filename|directory> -c ssp -o <filename|directory>

sample:

dsprotector_con.exe C:\Users\test\Desktop\cmd\python\py.py -c C:\Users\test\Desktop\cmd\python\python.exe.ssp -o C:\Users\test\Desktop\cmd\python\protected\py.py

Option Description to DSProtector CLI

Option settingDescription

filename

to protect the specific file

directory

to protect the whole directory

-c ssp

use the configuration file which generated by Virbox Protector GUI tool

-o output

output directory for the protected file

Protect pyc file directory, DSProtector supports to protect multiple py/pyc files in same directory. so, specify the directory, all of py/pyc file in the directory will be protected.

Protect PHP Project

Protect PHP, Lua, or other scripting language project. the protection process is similar to the protection process to Python.

in General, there are 2 steps to protect PHP project:

Step 1 Use Virbox Protector CLI tool to protect PHP executive file

Step 2 Use DSProtector CLI tool tool to protect PHP file.

For the detail info, Pls refer the Python Protection process section above.

5. Signature Option

APK/AAB Signature

OptionCLI ArgumentOn default argument value/setting

Enable the sign

--sign=

0

Set Key Store Path

--ks=

Valid for Global Configuration

Set Key Store Password

--ks-pass=

Valid for Global Configuration

Set the Key alias

--ks-key-alias=

Valid for Global Configuration

Set the Password of Key

--key-pass=

Valid for Global Configuration

Sample

virboxprotector_con <file_path> <other_options ...> 
	--sign=1 --ks="test/android.ks" --ks-pass=mypass --ks-key-alias=CERT --key-pass=mykeypass 
	-o <output_path>

iOS/macOS Signature

OptionCLI ArgumentOn default argument value/setting

enable signature

--sign=

0

Certificate

--identity=

N/A

6. Function Protection Option

Virbox Protector supports developer to protect the functions/method level (fine grained protection) and specify the "rule" to protect the critical functions/methods with different kind of protection options: Code of Encryption, Code of obfuscation (Mutation) and Code of Virtualization.

, use the semicolon: ; to separate functions, support to use wild card: *

OptionCLI ArgumentWild card

Ignore/skip the function/method not support to protect

--ignore-unsupported=<value>

N/A

Code of Encryption

-e

support to use: *

Code of Obfuscation (Code of mutation)

-m

Support to use: *

Code of Virtualization

-v

Support to use: *

Sample

-m "function1;function2" -v "function3;function4" -e "test*" --ignore-unsupported=1

--ignore-unsupported=

This option used to skip/ignore those functions which developer select the protection option doesn't support to protect; This option is enable on default when developer protect the following type of applications: Jar/aar/war/apk/aab

SDK label to some critical functions/methods

Virbox Protector also support to set SDK label in project coding process. for more detail how to use SDK label to label to functions/methods in coding process, pls refer next chapter.

7. Other Options

Archive with multiple package

Protect and use multiple package template to archive package

virboxprotector_con <apk_path> <other_options ...> 
	--mulpkg-template=<template_path> --mulpkg-outdir=<multi_package_outdir>
	[-o <output_main_apk_file>]

Archive with multiple package only (no protect)

virboxprotector_con -mulpkg <apk_path> --mulpkg-template=<template_path> -o <output_directory>

To specify the signature (optional)

For all above CLI command options, developer may specify to enable signature, pls refer the related "Signature Options" respectively.

Merge the assemblies

Use: -ilmerge option to merge the assemblies:

virboxprotector_con -ilmerge <main_assembly> <other_assemblies ...> -o <output_path>

Sample

virboxprotector_con -ilmerge Project.exe MyLibrary1.dll MyLibrary2.dll -o Merged/Project.exe

Remove "Symbol table"

Use -strip option to remove the debugging information (Static symbol table & static string table) from ELF application

virboxprotector_con -strip <file_path> -o <output_path>

Sample

virboxprotector_con -strip libhello.so -o striped/libhello.so

8. Error code for Virbox Protector CLI tool

Error CodeDescription

Error（0x00000000)

Success

Error（0x00000002）

Memory in sufficient

Error（0x00000003）

Configuration file error

Error（0x00000011）

Project has been encrypted

Error（0x00000012）

Failed to read file, file or file folder not found

Error（0x00000013）

Failed to write file, file has been occupied or no access right to write file

Error（0x00000021）

not found .ssp file (configuration file not found)

Error（0x00000022）

Configuration file error

Error（0x00000023）

missing the configuration file to ds plugin in the .ssp file (configuration file) or ds node in the .ssp file has been deleted.

Error（0x00000024）

ds plug in the .ssp file not activate (which means ds button not been switch on

Error（0x00000025）

password node for the ds plug in in the .ssp file missing. which means no password input or password node has been deleted.

Error（0x00000031）

file size too small (less 4 bytes)

PreviousCLI Tool: User ManualNextSet the SDK label to protect the specified functions/code/String

Last updated