/

Configuration Reference

Shield for iOS uses a JSON configuration file to control all aspects of the protection process. This page documents every available option.

Configuration File

Shield reads its configuration from a shield-ios.json file. Generate a default configuration with:

Bash
shield-ios init

Complete Structure

JSON
{
  "projectToken": "bh_YOUR_TOKEN",

  "protections": {
    "symbol_renaming": true,
    "string_encryption": true,
    "swift_stripping": true,
    "control_flow": "medium",
    "dead_code_injection": "medium",
    "opaque_predicates": "medium",
    "arithmetic_obfuscation": "medium",
    "instruction_substitution": "medium",
    "register_shuffling": "medium",
    "api_hiding": "medium",
    "class_encryption": true,
    "resource_encryption": true,
    "anti_debug": true,
    "anti_jailbreak": true,
    "rasp": true,
    "polymorphic": true
  },

  "code_signing": {
    "identity": "iPhone Distribution: Your Team",
    "provisioning_profile": "path/to/profile.mobileprovision",
    "skip_if_not_macos": true
  },

  "build_integration": {
    "skip_debug": true,
    "skip_simulator": true,
    "verbose": false
  },

  "output": {
    "suffix": "_protected"
  },

  "mapping": {
    "output_file": "mapping.txt",
    "format": "proguard"
  },

  "logging": {
    "level": "info",
    "file": "shield.log",
    "console": true
  }
}

Project Token

PropertyTypeDescription
projectTokenstringYour ByteHide project token (starts with bh_). Required for license validation and cloud features. Can also be set via the SHIELD_PROJECT_TOKEN environment variable (takes priority over the config file value).

Protections

Each protection can be enabled with true (default settings) or configured with a specific level or options object. See Protections Overview for details on each protection.

Boolean Protections

These protections accept true or false:

ProtectionDescription
symbol_renamingRename classes, methods, and properties
string_encryptionEncrypt string literals in the binary
swift_strippingRemove Swift metadata and debug symbols
class_encryptionEncrypt Objective-C class metadata
resource_encryptionEncrypt bundled resources and assets (AES-256)
anti_debugDetect and block debugger attachment
anti_jailbreakDetect jailbroken devices
raspRuntime Application Self-Protection (hook, trace, and tamper detection)
polymorphicGenerate unique binary on each build

Level-Based Protections

These protections accept an intensity level as a string:

ProtectionLevelsDescription
control_flow"light", "medium", "aggressive"Control flow obfuscation
dead_code_injection"light", "medium", "heavy"Insert unreachable code paths
opaque_predicates"simple", "medium", "complex"Add always-true/false conditions
arithmetic_obfuscation"simple", "medium", "complex"Transform arithmetic operations
instruction_substitution"simple", "medium", "complex"Replace instructions with equivalents
register_shuffling"simple", "medium", "complex"Randomize register allocation
api_hiding"simple", "medium", "complex"Hide system API calls

Set to false to disable any level-based protection.

Protection-Specific Options

Some protections accept an options object for fine-grained control instead of a simple true or level string.

Symbol Renaming Options

JSON
{
  "symbol_renaming": {
    "enabled": true,
    "prefix": "a",
    "rename_classes": true,
    "rename_methods": true,
    "rename_properties": true,
    "rename_protocols": false,
    "exclude": ["AppDelegate", "SceneDelegate", "*Delegate"]
  }
}

String Encryption Options

JSON
{
  "string_encryption": {
    "enabled": true,
    "algorithm": "xor",
    "exclude": ["http://*", "https://*"]
  }
}

Anti-Debug Options

JSON
{
  "anti_debug": {
    "enabled": true,
    "ptrace": true,
    "sysctl": true
  }
}

Anti-Jailbreak Options

JSON
{
  "anti_jailbreak": {
    "enabled": true,
    "sensitivity": 1,
    "exit_on_detect": true
  }
}
OptionTypeDescription
sensitivityinteger0 (Basic), 1 (Standard), 2 (Paranoid)
exit_on_detectbooleanExit the app when jailbreak is detected

RASP Options

JSON
{
  "rasp": {
    "enabled": true,
    "hook_detection": true,
    "trace_detection": true,
    "tamper_detection": true,
    "action": "exit"
  }
}
OptionTypeDescription
hook_detectionbooleanDetect Frida, Cycript, Substrate hooks
trace_detectionbooleanDetect dynamic tracing
tamper_detectionbooleanDetect binary modification
actionstring"exit", "alert", "log"

Code Signing

PropertyTypeDescription
code_signing.identitystringCode signing identity name (e.g., "Apple Development", "iPhone Distribution")
code_signing.provisioning_profilestringPath to .mobileprovision file (optional)
code_signing.skip_if_not_macosbooleanSkip signing if not on macOS — useful for CI/CD on Linux runners

When to use --no-sign

When using the Xcode post-archive integration, use --no-sign on the command line and let Xcode handle signing during distribution. The code_signing config section is for standalone CLI usage where you want Shield to re-sign the IPA.

Build Integration

PropertyTypeDefaultDescription
build_integration.skip_debugbooleantrueSkip protection for Debug builds
build_integration.skip_simulatorbooleantrueSkip protection for Simulator targets
build_integration.verbosebooleanfalseShow detailed output during protection

Output

PropertyTypeDescription
output.pathstringFull path for the protected output file
output.suffixstringSuffix added to the input filename (default: _protected)

Mapping

PropertyTypeDescription
mapping.output_filestringMapping file output path (default: mapping.txt)
mapping.formatstringMapping file format: "proguard"

Logging

PropertyTypeDefaultDescription
logging.levelstring"info"Log level: "debug", "info", "warning", "error"
logging.filestring"shield.log"Log file path
logging.consolebooleantrueEnable console output

Configuration Examples

Development (minimal)

JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "string_encryption": true
  }
}
JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "anti_jailbreak": true,
    "string_encryption": true,
    "symbol_renaming": true,
    "control_flow": "medium",
    "opaque_predicates": "medium"
  }
}

High-Security (maximum)

JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "anti_jailbreak": {
      "enabled": true,
      "sensitivity": 2,
      "exit_on_detect": true
    },
    "string_encryption": true,
    "symbol_renaming": true,
    "swift_stripping": true,
    "control_flow": "aggressive",
    "dead_code_injection": "heavy",
    "opaque_predicates": "complex",
    "class_encryption": true,
    "resource_encryption": true,
    "rasp": {
      "enabled": true,
      "hook_detection": true,
      "trace_detection": true,
      "tamper_detection": true,
      "action": "exit"
    }
  }
}
Previous
CI/CD Integration
Next
Build Profiles