Before you start protection, be sure that your app meets the requirements.

Command Line Options

$ iosdefender --help

usage: iosdefender.py [-h] [-v] [--verbose] [-o OUTPUT_DIRECTORY] [-a ARTEFACTS] [-p INJECTION_CONFIG] -g CONFIG [-w OVERRIDE_CONFIG] [-l LICENSE_FILE] [-m MODE] [-b BUILD_MODE] [--generate-report] [input_package]

positional arguments:
input_package         Input XCArchive/XCFramework

options:
-h, --help            show this help message and exit
-v, --version         show program's version number and exit
--verbose             Enable verbose output
-o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        Output folder
-a ARTEFACTS, --artefacts ARTEFACTS
                        A folder where build artefacts are stored
-w OVERRIDE_CONFIG, --override-config OVERRIDE_CONFIG
                        Optional configuration file for overriding existing config options.
-l LICENSE_FILE, --license-file LICENSE_FILE
                        Path to the license file. Defaults to /Users/jbikulcius/Library/iosdefender/verimatrix.license
-m MODE, --mode MODE  Override a tool mode defined in config file. Available commands: online, offline.
-b BUILD_MODE, --build-mode BUILD_MODE
                        Available commands: protect, new-config, checkinstall. Default command is protect.
--generate-report     When enabled, the tool produces an efficacy report in the output directory.

required named arguments:
-g CONFIG, --config CONFIG
                        Project configuration file.

Project Setup

The XTD Protect for iOS requires a project configuration file to be passed to the tool as a command line argument. The file contains the list of features which can be modified by the user. Generate a project config file with a default feature set by calling IOSdefender with the new-config command. The project config file’s location and name must be provided to the tool via --config command line option. If the path is not provided, then the config file will be created in the folder where the tool was called from.

In the example below, the config file is project.config.

$ iosdefender -b new-config -g project.config
or $ iosdefender --build-mode new-config --config project.config

If the project config file exists, then it needs to be deleted first in order to create a new one. The tool will notify the user if the file cannot be created for any reason and display an appropriate error message.

You must ensure that the correct values are set in the project config file before using the tool for a commercial release.

Below is an example of the project config file.

{
   "title": "Auto-generated config file",
   "pipeline": "binary",
   "revision": 1,
   "config": "project",
   "mode": "offline",
   "user features": {
      "protection profile": "regular",
      "enable app properties protection": "True",
      "enable app resource deletion check": "True",
      "enable app resources protection": "True",
      "check network coverage": "std",
      "anti debug rate": "0.1",
      "constant obfuscation rate": "0.0",
      "disassembly barrier rate": "0.1",
      "exclude binaries": "",
      "enable frida hooking prevention": "False",
      "jailbreak": "hard",
      "monitoring api key": "",
      "monitoring api key id": "",
      "monitoring api key owner email": "",
      "enable override xcode toolchain": "True",
      "protect frameworks": "",
      "framework check network coverage": "off",
      "framework anti debug rate": "0.0",
      "framework constant obfuscation rate": "0.0",
      "framework disassembly barrier rate": "0.0",
      "protect plugins": "",
      "plugin check network coverage": "off",
      "plugin anti debug rate": "0.0",
      "plugin constant obfuscation rate": "0.0",
      "plugin disassembly barrier rate": "0.0",
      "secrets filename": "",
      "secrets strings": "",
      "enable string obfuscation": "True",
      "string obfuscation string exclude filename": "",
      "enable symbol stripping": "True",
      "enable url detection": "False",
      "enable javascript encryption": "False"
   }
}

Tool invocation

XTD Protect for iOS tool runs from a command line prompt with mandatory and optional arguments. The command line in the example below includes two arguments:

• --build-mode protect
• --config project.config
• --output-directory

If using a license file from other than the default location, you may also want to supply the --license-file argument:

$ iosdefender --build-mode protect --license-file ~/Downloads/verimatrix.license --config project.config --output-directory /tmp Molecules.xcarchive

Otherwise:

$ iosdefender --build-mode protect --config project.config --output-directory /tmp Molecules.xcarchive

Expected output is similar to the following:

IOSdefender: version 6.10 revision c385d28f782, BPT: version 1.53, built on 18 Jun 2024

* Check if the application can be protected
* Detected 1 Mach-O file eligible for protection
* Inspect \<Molecules> binary
* Apply protection to binary
* Write protected binary to the archive
* Verify archive
* Collect build artefacts
  
The following 1 binary was fully protected:
  App: Molecules
    Original size: 1.24MB      Protected size: 1.31MB        Time taken: 43.10s

Protected 1 Mach-O file out of 1
    Full protection: 1
    Partial protection: 0
    No protection: 0
         Total time taken: 43.10s

Two optional arguments --build-mode protect and --output-directory can be omitted. The default output folder is the current working directory (cwd).

$ iosdefender ios-archives/Molecules.xcarchive --config project.config

Tool modes

• Online mode: The injected protection code communicates with a back-end server managed by Verimatrix. Security information such as check values and root status are sent to the server allowing in-depth analysis and risk assessment to be performed by intelligent algorithms on the server. The response decision for features like root detect is managed by the server (based on instructions or rules from the software developer), however tamper response is always managed directly by the security code in the application.
• Offline mode: There is no back-end server connection, and all security management and decisions are taken directly by the security code injected into the application.

The mode is defined in the main config file.

...

"mode": "offline",

...

It can be overridden from the command line with –mode (-m) argument.

$ iosdefender --build-mode protect test.xcarchive --output-directory /tmp --config project.config --mode=online

$ iosdefender --build-mode protect test.xcarchive --output-directory /tmp --config project.config --mode=offline

When the tool runs in online mode, additional configuration is required for communications with the ARC (Analytics and Remote Control) server - the monitoring service.

Monitoring Service

The ARC server configuration can be retrieved from XTD Protect using an API key. For this feature to work your account plan must allow for generation of API keys. The system that the tool is installed on must also have internet access. Then you can use XTD to generate an API key and API key id pair. The API key must include the “Monitoring for On-prem“ scope, this allows the key to be used for obtaining configuration data. This key and its id should be entered into your IOSdefender project config under the monitoring api key and monitoring api key id user features. Additionally, you will need to provide the key owner email in the monitoring api key owner email field.

{
   ...
   "user features": {
      "monitoring api key": "/dGVzd31HqRlc3Rc026c3R0qZXN5s90dG2Vz4dHRzdA=",
      "monitoring api key id": "f8rca71g-kl8e-09lk-1234-aa2b1cd3ee4f",
      "monitoring api key owner email": "[email protected]",
      ...
   }
}

The values shown above are examples only - the correct values should be retrieved from the Verimatrix Platform.

Xcode compatibility check override

XTD Protect for IOS command line tool uses a single Xcode toolchain for protection which needs to match the version of Xcode used to build the main application (.app) in the archive. You can use the xcode-select -s command to choose a matching version of Xcode. All compatible binaries in the archive will be processed using this toolchain.

If you need to select a different Xcode version for compatibility reasons (for example, if one of the frameworks is built with a newer Xcode than the main app), you can select a different version of Xcode as long as it’s equal or newer than the toolchain used to build the main app. In this case you will also need to enable the Xcode toolchain override setting in the project configuration file:

{
   "enable override xcode toolchain": "True",
}

Customised config file

The list of features is available in the project config file and can be edited by the user. An alternative location for the config file can be added to the config file path –config (-c). It’s recommended to use the default configuration file.

$ iosdefender --build-mode protect test.xcarchive --output-directory /tmp --config=/alternative-location/project-modified.config

Build artifacts

The tool collects build artefacts in a temporary folder by default. Artifacts can be also stored in an alternative location. That may be useful for an investigation of any app protection issues. To change location, the –artefacts (-a) option needs to be added to the command line.

$ iosdefender --build-mode protect test.xcarchive --output-directory /tmp --config project.config --artefacts=/tmp/artefacts

Caching

The tool employs a caching mechanism for parsing binaries. During the initial protection, cache files are created in ~/Libraries/Cache/com.verimatrix.iosdefender and are used in subsequent runs, significantly speeding up the process. The cache items are invalidated and recreated if any of the following occur:

• XTD Protect for iOS is updated to a new version
• The checksum of a binary changes. For example, if a framework within the archive gets updated, only the cache for that framework will be cleared.
• The location of the archive or the dSYM changes, or the dSYM file is missing