/

Simulator Detection

Protection Module: SimulatorDetection

Available For

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

How It Works

The Simulator Detection module identifies whether your application is running in an iOS simulator or on a physical device. It uses multiple reliable detection techniques that are difficult to bypass:

Detection Techniques

  • TARGET_OS_SIMULATOR Compile-Time Flag: Checks the compile-time flag that differentiates simulator builds from device builds at compilation.
  • Architecture Detection: Analyzes CPU architecture; simulator environments use x86_64 or i386 architectures, while devices use ARM64 or similar ARM architectures.
  • SIMULATOR_ROOT Environment Variable: Checks for the presence of the SIMULATOR_ROOT environment variable, which is set only in simulator contexts.
  • Device Model Name: Verifies the device model string; simulator returns "Simulator" in the model name.

Detection Confidence: 1.0 (100% - extremely reliable detection)

Default Interval: 60 seconds

Caching: Cached permanently (simulator status doesn't change at runtime)

JSON Configuration

JSON
{
  "protections": [
    {
      "type": "SimulatorDetection",
      "action": "close",
      "intervalMs": 60000
    }
  ]
}

Code-Based Configuration

Swift

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    config.enableProtection(.simulatorDetection, action: .close, intervalMs: 60000)
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

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

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 Releases: Prevent distribution and testing on simulators
  • Testing Environments: Identify when running in development vs. production
  • License Enforcement: Allow only physical device usage for paid apps
  • Sensitive Data Apps: Restrict simulator access to protect real user data
  • Beta Testing: Control which devices can run beta versions
  • Development: Use Log action during development to track simulator usage
  • Analytics: Monitor simulator vs. device distribution

Code Examples

Swift Basic Configuration

Swift
import ByteHideMonitor

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

Swift with Custom Action

Swift
import ByteHideMonitor

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

        // Log simulator usage
        Analytics.log(event: "simulator_detected", parameters: [
            "threat_type": threatType,
            "description": description,
            "timestamp": ISO8601DateFormatter().string(from: Date())
        ])

        // Optionally enable development-only features
        DevelopmentMode.enable()

        // Notify backend of development environment usage
        APIClient.reportEnvironmentUsage(
            environment: "simulator",
            appVersion: Bundle.main.appVersion
        )
    }

    config.enableProtection(.simulatorDetection, customAction: "simulator-handler", intervalMs: 60000)
}

Objective-C Basic Configuration

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

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

Objective-C with Custom Action

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

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

        // Log simulator usage
        [Analytics logEvent:@"simulator_detected"
                parameters:@{
                    @"threat_type": threatType,
                    @"description": description,
                    @"timestamp": [NSDate date]
                }];

        // Enable development features
        [DevelopmentMode enable];

        // Report to backend
        [[APIClient sharedClient] reportEnvironmentUsage:@"simulator"
                                             appVersion:[NSBundle mainBundle].appVersion];
    }];

    [config enableProtection:BHMProtectionModuleTypeSimulatorDetection
                customAction:@"simulator-handler"
                  intervalMs:60000];
}];

Platform Compatibility

FeatureiOS 12-13iOS 14-15iOS 16+
Compile-Time Flag Check✓✓✓
Architecture Detection✓✓✓
Environment Variable Check✓✓✓
Device Model Detection✓✓✓
Permanent Caching✓✓✓
Reliable on All Simulators✓✓✓

Performance Impact

  • CPU Usage: <0.1% (single check at startup, then cached)
  • Memory Overhead: <100 KB (cached result)
  • Battery Impact: Negligible (permanent cache)
  • First Detection: <10ms
  • Runtime Overhead: Minimal (cached permanently)

Threat Detection Details

JSON
{
  "threat": {
    "moduleType": "SimulatorDetection",
    "threatType": "SimulatorDetected",
    "threatDescription": "Application running in iOS simulator, not on physical device",
    "detectionResult": {
      "isThreat": true,
      "category": "Environment",
      "threatDescription": "Simulator environment detected",
      "confidence": 1.0,
      "evidence": {
        "target_os_simulator": true,
        "architecture": "x86_64",
        "device_model": "iPhone 14 Pro Simulator",
        "simulator_root": "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Simulator/RuntimeRoot",
        "environment_variable": "SIMULATOR_ROOT"
      },
      "timestamp": "2026-03-03T10:30:45.123Z"
    },
    "metadata": {
      "cache_status": "permanent",
      "check_duration_ms": 3,
      "interval_ms": 60000,
      "cached_at_startup": true
    }
  }
}

Next Steps

Previous
Jailbreak Detection
Next
Clock Tampering