/

JSON Configuration

Configure Monitor using local JSON configuration files. Ideal for version-controlled setups, offline environments, and CI/CD pipelines.

Overview

JSON configuration lets you define protections, logging, and other Monitor settings in a file that lives alongside your application code. This is useful for:

  • Version control: Track configuration changes in git alongside your codebase
  • Environment-specific configs: Different files per environment (dev, staging, production)
  • Offline deployments: No dependency on the ByteHide Cloud API
  • CI/CD pipelines: Automate configuration as part of your build and deploy process

Configuration Priority

When multiple configuration sources are present, they are applied in this priority order: Cloud Dashboard (highest) > JSON File > Code (Configuration API) (lowest). Cloud configuration overrides JSON settings. See Cloud Configuration for details.

Export from Cloud Dashboard

If you already have rules configured in the Cloud Dashboard, click Export config in the Workflow tab to download them as a JSON file. This gives you a ready-to-use configuration file that matches your current cloud setup.

Configuration Files

Monitor searches for configuration files in your app bundle, in this order:

  1. monitor.config.json
  2. bytehide.monitor.json
  3. bytehide.monitor.config.json
  4. monitor-config.json
  5. bytehide-monitor-config.json

The first file found is used. Add one of these files to your Xcode project and ensure it is included in the app bundle (Target > Build Phases > Copy Bundle Resources).

Basic Configuration

JSON
{
  "apiToken": "${BYTEHIDE_TOKEN}",
  "logLevel": "info",
  "enableConsoleLogs": true,
  "enableFileLogs": false,
  "protections": [
    { "type": "DebuggerDetection", "action": "close", "intervalMs": 5000 },
    { "type": "JailbreakDetection", "action": "close", "intervalMs": 60000 },
    { "type": "TamperingDetection", "action": "close", "intervalMs": 60000 }
  ]
}

Complete Schema Reference

Root Configuration

FieldTypeDefaultDescription
apiTokenstring-ByteHide project token (can use env vars with ${VAR} syntax)
logLevelstring"info"Minimum log level: "debug", "info", "warning", "error"
enableConsoleLogsbooleantrueEnable console logging (NSLog / os_log)
enableFileLogsbooleanfalseEnable file logging to disk
protectionsarray[]Array of protection module configurations
customActionsobject{}Map of custom action names to handler class names

Protection Configuration

Protections are defined as an array of objects:

JSON
{
  "protections": [
    {
      "type": "DebuggerDetection",
      "action": "close",
      "intervalMs": 5000,
      "enabled": true,
      "parameters": {}
    }
  ]
}
FieldTypeDefaultDescription
typestring-Protection module type (PascalCase)
actionstring"log""none", "log", "close", "erase", "custom"
intervalMsnumber5000Check interval in milliseconds
enabledbooleantrueEnable this protection
parametersobject{}Module-specific configuration

No Block Action

The iOS SDK supports five action types: none, log, close, erase, and custom. The block action is not available on iOS.

Available Protection Types

JSON ValueDescription
DebuggerDetectionDetects attached debuggers (lldb, Xcode, ptrace)
JailbreakDetectionDetects jailbroken devices (Cydia, Sileo, checkra1n)
SimulatorDetectionDetects iOS Simulator environments
ClockTamperingDetects system time manipulation
MemoryDumpDetectionDetects memory dumping attempts (Frida, Cycript)
TamperingDetectionDetects app bundle tampering and code changes
ProcessInjectionDetects code injection and Frida gadgets
NetworkTamperingDetects proxies, MITM tools, and VPN connections
HardwareBindingDetects hardware fingerprint changes
ScreenRecordingDetectionDetects active screen recording
ScreenshotDetectionDetects screenshots
OverlayDetectionDetects UI overlays and tapjacking
LibraryInjectionDetectionDetects DYLD library injection and Substrate
KeychainIntegrityDetectionDetects Keychain integrity violations
ProtectionRecommended IntervalRationale
DebuggerDetection5,000ms (5s)Frequent checks for active debugging
JailbreakDetection60,000ms (1min)Device state changes infrequently
SimulatorDetection300,000ms (5min)Environment does not change at runtime
ClockTampering300,000ms (5min)Time drift accumulates slowly
MemoryDumpDetection3,000ms (3s)Memory attacks happen quickly
TamperingDetection60,000ms (1min)Bundle changes are persistent
ProcessInjection5,000ms (5s)Injection can occur at any time
NetworkTampering30,000ms (30s)Network state can change
HardwareBinding300,000ms (5min)Hardware does not change frequently
ScreenRecordingDetection2,000ms (2s)Recording can start/stop quickly
ScreenshotDetection1,000ms (1s)Screenshots are instantaneous events
OverlayDetection2,000ms (2s)Overlays can appear dynamically
LibraryInjectionDetection5,000ms (5s)Injection can occur at any time
KeychainIntegrityDetection60,000ms (1min)Keychain state changes infrequently

Environment Variables

You can reference environment variables in any string value using ${VARIABLE_NAME} syntax:

JSON
{
  "apiToken": "${BYTEHIDE_TOKEN}"
}

This avoids hardcoding sensitive values in configuration files.

Token Resolution Order

The project token is resolved in this order:

  1. BYTEHIDE_MONITOR_TOKEN environment variable
  2. BYTEHIDE_TOKEN environment variable
  3. apiToken value in the JSON file
  4. ByteHideMonitor > APIToken in Info.plist

Complete Production Example

JSON
{
  "apiToken": "${BYTEHIDE_TOKEN}",
  "logLevel": "warning",
  "enableConsoleLogs": false,
  "enableFileLogs": false,

  "protections": [
    { "type": "DebuggerDetection", "action": "close", "intervalMs": 5000 },
    { "type": "JailbreakDetection", "action": "close", "intervalMs": 60000 },
    { "type": "SimulatorDetection", "action": "close", "intervalMs": 300000 },
    { "type": "ClockTampering", "action": "log", "intervalMs": 300000 },
    { "type": "MemoryDumpDetection", "action": "erase", "intervalMs": 3000 },
    { "type": "TamperingDetection", "action": "close", "intervalMs": 60000 },
    { "type": "ProcessInjection", "action": "close", "intervalMs": 5000 },
    { "type": "NetworkTampering", "action": "log", "intervalMs": 30000 },
    { "type": "HardwareBinding", "action": "log", "intervalMs": 300000 },
    { "type": "ScreenRecordingDetection", "action": "log", "intervalMs": 2000 },
    { "type": "ScreenshotDetection", "action": "log", "intervalMs": 1000 },
    { "type": "OverlayDetection", "action": "log", "intervalMs": 2000 },
    { "type": "LibraryInjectionDetection", "action": "close", "intervalMs": 5000 },
    { "type": "KeychainIntegrityDetection", "action": "erase", "intervalMs": 60000 }
  ]
}

Development Configuration

JSON
{
  "apiToken": "${BYTEHIDE_TOKEN}",
  "logLevel": "debug",
  "enableConsoleLogs": true,
  "enableFileLogs": false,

  "protections": [
    { "type": "DebuggerDetection", "action": "none", "intervalMs": 5000 },
    { "type": "JailbreakDetection", "action": "log", "intervalMs": 60000 },
    { "type": "TamperingDetection", "action": "log", "intervalMs": 60000 },
    { "type": "ProcessInjection", "action": "log", "intervalMs": 5000 },
    { "type": "NetworkTampering", "action": "none", "intervalMs": 30000 }
  ]
}

Advanced Interval Configuration

For fine-tuned control over detection frequency:

JSON
{
  "protections": [
    {
      "type": "DebuggerDetection",
      "action": "close",
      "intervalMs": 3000
    },
    {
      "type": "JailbreakDetection",
      "action": "close",
      "intervalMs": 120000
    },
    {
      "type": "MemoryDumpDetection",
      "action": "erase",
      "intervalMs": 2000
    }
  ]
}

Performance Impact

Lower intervals mean more frequent checks but higher CPU and battery usage. Balance security needs with performance and battery requirements for mobile applications.

Next Steps

Cloud Configuration

Configure protections from the web dashboard with real-time sync

Configuration API

Code-based configuration for custom actions and programmatic control

Protection Modules

Complete reference of all available protection modules

Actions

All action types and when to use each one

Previous
Cloud Configuration
Next
Configuration API