/

Debugger Detection

Protection Module: DebuggerDetection

Available For

Android API 21+ (Mobile) Desktop Java Runtime (JVM)

How It Works

The Debugger Detection module monitors and identifies various debugging interfaces and tools that could be used to inspect or manipulate your application at runtime. It detects active debugging sessions through platform-specific mechanisms and prevents execution when debugging tools are attached.

Detection Techniques

Android Platform:

  • isDebuggerConnected(): Uses android.os.Debug.isDebuggerConnected() via reflection to detect active debugger connections
  • Build Type Detection: Checks Build.TYPE for engineering builds ("eng") or debug builds ("userdebug") that indicate development environments
  • Confidence: 1.0 (maximum certainty on Android)

Desktop Java Platform:

  • JDWP Argument Inspection: Analyzes ManagementFactory.getRuntimeMXBean().getInputArguments() for JDWP flags including -agentlib:jdwp, -Xrunjdwp, and -Xdebug
  • Debug Session Detection: Identifies active Java Debug Wire Protocol sessions
  • Confidence: 0.9

Default detection interval: 60 seconds

JSON Configuration

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

Code-Based Configuration

Kotlin

Kotlin
import com.bytehide.monitor.Monitor
import com.bytehide.monitor.core.action.ActionType
import com.bytehide.monitor.core.protection.ProtectionModuleType

Monitor.configure { config ->
    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        ActionType.CLOSE,
        60000
    )
}

Java

Java
import com.bytehide.monitor.Monitor;
import com.bytehide.monitor.core.action.ActionType;
import com.bytehide.monitor.core.protection.ProtectionModuleType;

Monitor.configure(config -> {
    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        ActionType.CLOSE,
        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

Enable Debugger Detection when:

  • Building financial or banking applications
  • Protecting sensitive user data or credentials
  • Developing premium apps vulnerable to feature unlocking
  • Requiring compliance with security standards (PCI DSS, HIPAA)
  • Preventing reverse engineering and code inspection
  • Protecting intellectual property in mobile apps

Code Examples

Kotlin - Basic Integration

Kotlin
import com.bytehide.monitor.Monitor
import com.bytehide.monitor.core.action.ActionType
import com.bytehide.monitor.core.protection.ProtectionModuleType

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Monitor.configure { config ->
            config.addProtection(
                ProtectionModuleType.DEBUGGER_DETECTION,
                ActionType.CLOSE,
                60000
            )
        }

        setContentView(R.layout.activity_main)
    }
}

Kotlin - Custom Action Handler

Kotlin
Monitor.configure { config ->
    config.registerCustomAction("debugger-handler") { threat ->
        val threatType = threat.getThreatType()
        val confidence = threat.getConfidence()
        val metadata = threat.getMetadata()

        Log.e("Security", "Debugger detected: $threatType (confidence: $confidence)")

        // Send to security backend
        reportSecurityEvent(
            threatType = threatType,
            confidence = confidence,
            timestamp = System.currentTimeMillis(),
            metadata = metadata
        )

        // Graceful shutdown
        gracefulShutdown()
    }

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "debugger-handler",
        60000
    )
}

Java - Custom Action with Log Fallback

Java
Monitor.configure(config -> {
    config.registerCustomAction("debugger-handler", threat -> {
        String threatType = threat.getThreatType();
        double confidence = threat.getConfidence();
        Map<String, Object> metadata = threat.getMetadata();

        if (confidence > 0.95) {
            Log.e("Security", "High-confidence debugger: " + threatType);
            System.exit(1);
        } else {
            Log.w("Security", "Potential debugger: " + threatType);
            // Log only, allow execution
        }
    });

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "debugger-handler",
        60000
    );
});

Java - Different Actions for Different Scenarios

Java
Monitor.configure(config -> {
    // Development build: log only
    if (BuildConfig.DEBUG) {
        config.addProtection(
            ProtectionModuleType.DEBUGGER_DETECTION,
            ActionType.LOG,
            60000
        );
    }

    // Production build: close immediately
    if (BuildConfig.RELEASE) {
        config.addProtection(
            ProtectionModuleType.DEBUGGER_DETECTION,
            ActionType.CLOSE,
            60000
        );
    }
});

Platform Compatibility

PlatformStatusNotes
Android 5.0+✓ Fully SupportedAPI Level 21+ with reflection-based detection
Android 11+✓ OptimizedEnhanced build property inspection
Desktop Java✓ SupportedJDWP detection via ManagementFactory
Windows JVM✓ SupportedStandard JDWP argument parsing
macOS JVM✓ SupportedStandard JDWP argument parsing
Linux JVM✓ SupportedStandard JDWP argument parsing

Performance Impact

  • CPU Impact: < 0.5% increase during detection cycles
  • Memory Overhead: ~50 KB for reflection cache
  • Detection Latency: 10-20 ms per cycle
  • Battery Impact: Minimal (background monitoring only)

Threat Detection Details

When a debugger is detected, the module generates a detection result with the following structure:

JSON
{
  "threatType": "isDebuggerConnected",
  "description": "Active debugger detected via android.os.Debug.isDebuggerConnected()",
  "confidence": 1.0,
  "timestamp": "2026-03-02T14:32:17.842Z",
  "metadata": {
    "detectionMethod": "reflection_check",
    "buildType": "eng",
    "isDebuggerConnected": true,
    "platformVersion": "Android 12"
  }
}
JSON
{
  "threatType": "jdwp_flag_detected",
  "description": "JDWP flag found in runtime arguments",
  "confidence": 0.9,
  "timestamp": "2026-03-02T14:32:17.842Z",
  "metadata": {
    "detectionMethod": "jdwp_flag_inspection",
    "runtimeArguments": ["-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"],
    "platformVersion": "Java 11",
    "jvmVersion": "OpenJDK 11.0.11"
  }
}

Next Steps

Previous
Overview
Next
Virtual Machine Detection