/

Debugger Detection

Protection Module: DebuggerDetection

Available For

PlatformVersionStatus
iOS12.0+✓ Full Support
iPadOS12.0+✓ Full Support
tvOS12.0+✓ Supported

How It Works

The Debugger Detection module continuously monitors your application for signs of attached debuggers. It works across multiple detection techniques to ensure comprehensive coverage:

Detection Techniques

  • sysctl P_TRACED Flag Detection: Checks the P_TRACED flag via sysctl syscall to determine if the process is being traced by a debugger (LLDB, Xcode).
  • Exception Port Checking: Analyzes exception ports using task_get_exception_ports() to detect debugger exception handlers registered with the Mach kernel.
  • Timing Anomaly Detection: Measures execution timing to detect breakpoint-induced delays that indicate debugger stepping.

Detection Confidence: 1.0 (100% - guaranteed detection for attached debuggers)

Default Interval: 10 seconds

JSON Configuration

JSON
{
  "protections": [
    {
      "type": "DebuggerDetection"
      "action": "close"
    }
  ]
}

Code-Based Configuration

Swift

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    config.enableProtection(.debuggerDetection, action: .close)
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config enableProtection:BHMProtectionModuleTypeDebuggerDetection
                      action:BHMActionTypeClose];
}];

Available Actions

ActionBehaviorRecommended For
CloseTerminate application immediatelyProduction apps with critical IP
LogRecord incident and continueDevelopment, analytics
EraseSecurely delete data then terminateFinancial, healthcare apps
CustomExecute custom handlerEnterprise integrations
NoneDetect only, no actionTesting configurations

See Actions for detailed action documentation.

When to Use

  • Production Apps: Always enable to prevent reverse engineering and IP theft
  • Enterprise Software: Protect sensitive business logic from debugging
  • Financial Apps: Prevent transaction manipulation through debugging
  • Gaming Apps: Protect anti-cheat systems and game logic
  • Development: Use None or Log action during development to track debugger attachments

Code Examples

Swift Basic Configuration

Swift
import ByteHideMonitor

// In your AppDelegate or app initialization
BHMMonitor.configure { config in
    config.enableProtection(.debuggerDetection, action: .close)
}

Swift with Custom Action

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    // Register custom handler
    config.registerCustomAction("debugger-handler") { context in
        let threatType = context.threatType
        let description = context.threatDescription
        let metadata = context.metadata

        // Log to analytics
        Analytics.log(event: "debugger_detected", parameters: [
            "threat_type": threatType
            "description": description
            "timestamp": ISO8601DateFormatter().string(from: Date())
        ])

        // Optionally clean up resources before app termination
        UserDefaults.standard.synchronize()
    }

    // Enable with custom action
    config.enableProtection(.debuggerDetection, customAction: "debugger-handler")
}

Objective-C Basic Configuration

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

// In your AppDelegate application:didFinishLaunchingWithOptions:
[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config enableProtection:BHMProtectionModuleTypeDebuggerDetection
                      action:BHMActionTypeClose];
}];

Objective-C with Custom Action

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config registerCustomAction:@"debugger-handler" handler:^(BHMThreatContext *context) {
        NSString *threatType = context.threatType;
        NSString *description = context.threatDescription;
        NSDictionary *metadata = context.metadata;

        // Log threat to analytics
        [Analytics logEvent:@"debugger_detected"
                parameters:@{
                    @"threat_type": threatType
                    @"description": description
                    @"timestamp": [NSDate date]
                }];

        // Custom cleanup logic
        [[NSUserDefaults standardUserDefaults] synchronize];
    }];

    [config enableProtection:BHMProtectionModuleTypeDebuggerDetection
                customAction:@"debugger-handler"];
}];

Platform Compatibility

FeatureiOS 12-13iOS 14-15iOS 16+
sysctl Detection✓✓✓
Exception Port Checking✓✓✓
Timing Anomaly Detection✓✓✓
Background Monitoring✓✓✓
Continuous Intervals✓✓✓

Performance Impact

  • CPU Usage: Minimal, ~0.1-0.3% per check cycle
  • Memory Overhead: <500 KB
  • Battery Impact: Negligible with 10-second intervals
  • First Detection: <50ms after debugger attachment

Threat Detection Details

JSON
{
  "threat": {
    "moduleType": "DebuggerDetection"
    "threatType": "DebuggerAttached"
    "threatDescription": "LLDB debugger detected via P_TRACED flag"
    "detectionResult": {
      "isThreat": true
      "category": "Debugger"
      "threatDescription": "Process traced by debugger"
      "confidence": 1.0
      "evidence": {
        "detector": "sysctl_p_traced"
        "ppid": 1
        "p_traced_flag": true
      }
      "timestamp": "2026-03-03T10:30:45.123Z"
    }
    "metadata": {
      "detection_method": "sysctl"
      "check_duration_ms": 2
      "interval_ms": 10000
    }
  }
}

Next Steps

Previous
Overview
Next
Jailbreak Detection