/

Overlay Detection

Protection Module: OverlayDetection

Available For

This protection module is available for iOS 12 and later. It provides detection of suspicious window hierarchies and overlay-based attacks.

PlatformSupportNote
iOS✓iOS 12+ required
Framework✓UIKit required
Architecture✓All architectures

How It Works

Overlay Detection analyzes the UIWindow hierarchy to identify unauthorized windows that could be used for overlay attacks, tapjacking, or credential harvesting. It monitors window levels, transparency, and positioning to detect suspicious patterns.

Detection Techniques

The module employs the following detection strategies:

  • Window Hierarchy Analysis: Examines all active UIWindow instances in the application
  • Window Level Inspection: Detects windows positioned above normal level (.normal)
  • Hidden Window Detection: Identifies windows with zero opacity or hidden attributes
  • Positioning Analysis: Evaluates window frame and layering patterns
  • Tapjacking Prevention: Detects overlays that intercept touches without legitimate purpose
  • Level Validation: Verifies window level consistency with expected UI hierarchy

Confidence Metrics:

  • Suspicious window levels: 0.8
  • Hidden overlay detection: 0.85-0.90
  • Transparency-based detection: 0.75-0.80

Default Interval: Variable (typically 5-10 seconds)

JSON Configuration

JSON
{
  "protections": [
    {
      "type": "OverlayDetection",
      "action": "log",
      "intervalMs": 10000
    }
  ]
}

Code-Based Configuration

Swift

Swift
import ByteHideMonitor

BHMMonitor.configure { config in
    config.enableProtection(.overlayDetection, action: .log, intervalMs: 10000)
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

[BHMMonitor configure:^(BHMMonitorConfiguration *config) {
    [config enableProtection:BHMProtectionModuleTypeOverlayDetection
                      action:BHMActionTypeLog
                  intervalMs:10000];
}];

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

Enable Overlay Detection if:

  • Your app handles sensitive user input (passwords, PINs, credit cards)
  • You need to protect against tapjacking and overlay-based credential theft
  • You're implementing banking or payment applications
  • You want to prevent credential harvesting attacks
  • You need to detect unauthorized UI injection attempts
  • You're concerned about malware or compromised devices
  • You need to comply with banking security standards

Consider using custom actions to implement warning mechanisms or disable sensitive input operations.

Code Examples

Swift - Basic Configuration

Swift
import ByteHideMonitor

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        BHMMonitor.configure { config in
            config.enableProtection(
                .overlayDetection,
                action: .log,
                intervalMs: 10000
            )
        }
        return true
    }
}

Swift - Custom Action with Input Blocking

Swift
BHMMonitor.configure { config in
    config.registerCustomAction("overlay-handler") { context in
        let threatType = context.threatType
        let description = context.threatDescription
        let metadata = context.metadata

        // Log the overlay detection
        print("Overlay Detected: \(description)")
        print("Threat Type: \(threatType)")

        // Extract detection details
        if let windowInfo = metadata?["windowInfo"] as? [String: Any] {
            print("Suspicious Window Level: \(windowInfo["windowLevel"] ?? "unknown")")
            print("Window Count: \(windowInfo["windowCount"] ?? 0)")
        }

        // Block sensitive input operations
        DispatchQueue.main.async {
            self.disableSensitiveInput()

            // Show warning to user
            let alert = UIAlertController(
                title: "Security Warning",
                message: "Overlay detected. Sensitive operations are disabled.",
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.window?.rootViewController?.present(alert, animated: true)
        }

        // Log to security event tracker
        SecurityEvents.logOverlayDetection(
            description: description,
            windowCount: metadata?["windowCount"] as? Int ?? 0
        )
    }

    config.enableProtection(
        .overlayDetection,
        customAction: "overlay-handler",
        intervalMs: 10000
    )
}

private func disableSensitiveInput() {
    // Disable sensitive text fields and input operations
    // This prevents credential harvesting via overlays
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

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

        NSLog(@"Overlay Detected: %@", description);
        NSLog(@"Threat Type: %@", threatType);

        NSDictionary *windowInfo = metadata[@"windowInfo"];
        if (windowInfo) {
            NSLog(@"Suspicious Window Level: %@", windowInfo[@"windowLevel"]);
            NSLog(@"Window Count: %@", windowInfo[@"windowCount"]);
        }

        dispatch_async(dispatch_get_main_queue(), ^{
            [self disableSensitiveInput];

            UIAlertController *alert = [UIAlertController
                alertControllerWithTitle:@"Security Warning"
                message:@"Overlay detected. Sensitive operations are disabled."
                preferredStyle:UIAlertControllerStyleAlert];

            UIAlertAction *okAction = [UIAlertAction actionWithTitle:@"OK"
                style:UIAlertActionStyleDefault
                handler:nil];
            [alert addAction:okAction];

            [self.window.rootViewController presentViewController:alert animated:YES completion:nil];
        });
    }];

    [config enableProtection:BHMProtectionModuleTypeOverlayDetection
                customAction:@"overlay-handler"
                  intervalMs:10000];
}];

- (void)disableSensitiveInput {
    // Implement input disabling logic
}

Platform Compatibility

ComponentiOS 12iOS 13+iOS 16+Notes
Window Hierarchy Analysis✓✓✓Full support across all versions
Window Level Detection✓✓✓Detects suspicious window levels
Hidden Window Detection✓✓✓Identifies transparent overlays
Positioning Analysis✓✓✓Frame and layer analysis

Performance Impact

Overlay Detection has low to moderate performance impact:

  • CPU Usage: 0.3-0.8% per check cycle
  • Memory Overhead: ~2-4 MB for window hierarchy analysis
  • Check Latency: 50-150ms per detection cycle
  • Background Impact: Continues monitoring when applicable

To optimize performance:

  • Increase intervalMs to 20000 (20 seconds) for less frequent checks
  • Use .none action during development for detection-only mode
  • Consider disabling in non-sensitive screens if performance is critical

Threat Detection Details

When an overlay is detected, the threat context includes:

JSON
{
  "moduleType": "OverlayDetection",
  "threatType": "SuspiciousOverlay",
  "threatDescription": "Unauthorized overlay window detected above normal level",
  "detectionResult": {
    "windowLevel": 2147483647,
    "windowCount": 5,
    "suspiciousLevelDetected": true,
    "confidence": 0.8
  },
  "metadata": {
    "confidence": 0.8,
    "windowInfo": {
      "windowLevel": 2147483647,
      "windowCount": 5,
      "normalWindowCount": 2,
      "overlayCount": 3
    },
    "timestamp": "2024-03-15T10:30:45Z"
  }
}

Next Steps

Previous
Screenshot Detection
Next
Anomaly Detection