/

Custom Action

Action Type: CUSTOM

Execute your own handler logic when security threats are detected. This is the most flexible action type, enabling advanced threat response scenarios.

Available for: All platforms (Mobile and Desktop)

How It Works

Custom actions provide complete control over threat response:

  1. Receive detailed threat information (type, confidence, metadata)
  2. Analyze threat properties
  3. Execute custom business logic
  4. Send notifications or alerts
  5. Track analytics and monitoring
  6. Continue, suspend, or terminate the application

When to Use

Recommended for:

  • Integration with analytics and monitoring systems
  • Sending notifications to security teams
  • Displaying user-friendly security alerts
  • Conditional responses based on threat severity
  • Implementing complex business-specific logic

Not recommended for:

  • Simple binary responses (use Log, Close, or Erase instead)
  • Performance-critical code paths (handlers should be lightweight)

Threat Information Available

When your custom handler is invoked, you receive a threat object with these properties:

Kotlin (property syntax):

  • threat.threatType: Classification of detected threat (String)
  • threat.description: Human-readable threat description (String)
  • threat.confidence: Confidence score 0.0-1.0 (Double)
  • threat.metadata: Additional context data (Map)
  • threat.isThreatDetected(): Boolean indicating if threat was confirmed

Java (getter syntax):

  • threat.getThreatType(): Classification of detected threat
  • threat.getDescription(): Human-readable threat description
  • threat.getConfidence(): Confidence score 0.0-1.0
  • threat.getMetadata(): Additional context data
  • threat.isThreatDetected(): Boolean indicating if threat was confirmed

Configuration

JSON Configuration

JSON
{
  "protections": [
    {
      "type": "DebuggerDetection",
      "action": "log_threat",
      "interval": 2000
    },
    {
      "type": "MemoryDumpDetection",
      "action": "email_alert",
      "interval": 1000
    },
    {
      "type": "TamperingDetection",
      "action": "track_analytics",
      "interval": 3000
    }
  ]
}

Code Examples

Basic Custom Action (Kotlin)

Register a simple custom action that logs threat information:

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

Monitor.configure { config ->
    config.registerCustomAction("log_threat") { threat ->
        println("Threat detected: ${threat.threatType}")
        println("Description: ${threat.description}")
        println("Confidence: ${(threat.confidence * 100).toInt()}%")
    }

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "log_threat",
        2000
    )
}

Basic Custom Action (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.registerCustomAction("log_threat", threat -> {
        System.out.println("Threat detected: " + threat.getThreatType());
        System.out.println("Description: " + threat.getDescription());
        System.out.println("Confidence: " + (int)(threat.getConfidence() * 100) + "%");
    });

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "log_threat",
        2000
    );
});

Custom Action with User Dialog (Kotlin)

Display an alert to the user with conditional actions:

Kotlin
import com.bytehide.monitor.Monitor
import com.bytehide.monitor.core.protection.ProtectionModuleType
import android.app.AlertDialog
import android.content.Context

Monitor.configure { config ->
    config.registerCustomAction("show_user_alert") { threat ->
        val dialogBuilder = AlertDialog.Builder(context)
        dialogBuilder.setTitle("Security Warning")
        dialogBuilder.setMessage(buildString {
            appendLine("A security issue was detected:")
            appendLine(threat.description)
            appendLine("\nConfidence: ${(threat.confidence * 100).toInt()}%")
            appendLine("\nPlease update your app or contact support.")
        })
        dialogBuilder.setPositiveButton("Restart App") { dialog, _ ->
            dialog.dismiss()
            System.exit(1)
        }
        dialogBuilder.setNegativeButton("Continue") { dialog, _ ->
            dialog.dismiss()
        }
        dialogBuilder.setCancelable(false)
        dialogBuilder.show()
    }

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "show_user_alert",
        2000
    )
}

Custom Action with User Dialog (Java)

Java
import com.bytehide.monitor.Monitor;
import com.bytehide.monitor.core.protection.ProtectionModuleType;
import android.app.AlertDialog;

Monitor.configure(config -> {
    config.registerCustomAction("show_user_alert", threat -> {
        new AlertDialog.Builder(context)
            .setTitle("Security Warning")
            .setMessage("A security issue was detected:\n" +
                threat.getDescription() + "\n\n" +
                "Confidence: " + (int)(threat.getConfidence() * 100) + "%\n\n" +
                "Please update your app or contact support.")
            .setPositiveButton("Restart App", (dialog, which) -> {
                dialog.dismiss();
                System.exit(1);
            })
            .setNegativeButton("Continue", (dialog, which) -> dialog.dismiss())
            .setCancelable(false)
            .show();
    });

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "show_user_alert",
        2000
    );
});

Custom Action with Analytics Tracking (Kotlin)

Track security threats in your analytics system:

Kotlin
import com.bytehide.monitor.Monitor
import com.bytehide.monitor.core.protection.ProtectionModuleType
import com.google.firebase.analytics.FirebaseAnalytics
import android.os.Bundle

Monitor.configure { config ->
    config.registerCustomAction("track_analytics") { threat ->
        val analytics = FirebaseAnalytics.getInstance(context)
        val bundle = Bundle()
        bundle.putString("threat_type", threat.threatType)
        bundle.putString("description", threat.description)
        bundle.putDouble("confidence", threat.confidence)
        bundle.putLong("timestamp", System.currentTimeMillis())

        // Add metadata if available
        threat.metadata?.forEach { (key, value) ->
            bundle.putString("metadata_$key", value.toString())
        }

        analytics.logEvent("security_threat", bundle)
    }

    config.addProtection(
        ProtectionModuleType.TAMPERING_DETECTION,
        "track_analytics",
        3000
    )
}

Custom Action with Analytics Tracking (Java)

Java
import com.bytehide.monitor.Monitor;
import com.bytehide.monitor.core.protection.ProtectionModuleType;
import com.google.firebase.analytics.FirebaseAnalytics;
import android.os.Bundle;

Monitor.configure(config -> {
    config.registerCustomAction("track_analytics", threat -> {
        FirebaseAnalytics analytics = FirebaseAnalytics.getInstance(context);
        Bundle bundle = new Bundle();
        bundle.putString("threat_type", threat.getThreatType());
        bundle.putString("description", threat.getDescription());
        bundle.putDouble("confidence", threat.getConfidence());
        bundle.putLong("timestamp", System.currentTimeMillis());

        // Add metadata if available
        if (threat.getMetadata() != null) {
            threat.getMetadata().forEach((key, value) ->
                bundle.putString("metadata_" + key, value.toString())
            );
        }

        analytics.logEvent("security_threat", bundle);
    });

    config.addProtection(
        ProtectionModuleType.TAMPERING_DETECTION,
        "track_analytics",
        3000
    );
});

Conditional Response Based on Threat Type (Kotlin)

Execute different logic for different threat types:

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

Monitor.configure { config ->
    config.registerCustomAction("conditional_response") { threat ->
        when (threat.threatType) {
            "DEBUGGER_ATTACHED" -> {
                // Debugger detected - immediate exit
                println("Debugger detected: ${threat.description}")
                System.exit(1)
            }
            "MEMORY_CORRUPTION" -> {
                // Memory issue - clear sensitive data first
                println("Memory corruption detected - erasing data")
                clearSensitiveData(context)
                System.exit(1)
            }
            "JAILBREAK_DETECTED" -> {
                // Jailbreak detected - send alert
                println("Jailbreak detected")
                sendSecurityAlert(threat)
            }
            "UNUSUAL_ACTIVITY" -> {
                // Low confidence threat - just log it
                if (threat.confidence < 0.70) {
                    println("Low confidence threat logged: ${threat.description}")
                }
            }
            else -> {
                // Default behavior - log unknown threat
                println("Unknown threat: ${threat.threatType}")
            }
        }
    }

    config.addProtection(
        ProtectionModuleType.MEMORY_DUMP_DETECTION,
        "conditional_response",
        2000
    )
}

Conditional Response Based on Threat Type (Java)

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

Monitor.configure(config -> {
    config.registerCustomAction("conditional_response", threat -> {
        String threatType = threat.getThreatType();

        switch (threatType) {
            case "DEBUGGER_ATTACHED":
                System.out.println("Debugger detected: " + threat.getDescription());
                System.exit(1);
                break;
            case "MEMORY_CORRUPTION":
                System.out.println("Memory corruption detected - erasing data");
                clearSensitiveData(context);
                System.exit(1);
                break;
            case "JAILBREAK_DETECTED":
                System.out.println("Jailbreak detected");
                sendSecurityAlert(threat);
                break;
            case "UNUSUAL_ACTIVITY":
                if (threat.getConfidence() < 0.70) {
                    System.out.println("Low confidence threat logged: " +
                        threat.getDescription());
                }
                break;
            default:
                System.out.println("Unknown threat: " + threatType);
        }
    });

    config.addProtection(
        ProtectionModuleType.MEMORY_DUMP_DETECTION,
        "conditional_response",
        2000
    );
});

Multiple Custom Actions (Kotlin)

Register different handlers for different modules with different behaviors:

Kotlin
Monitor.configure { config ->
    // Action 1: Simple logging
    config.registerCustomAction("log_all_threats") { threat ->
        println("Threat logged: ${threat.threatType} (${(threat.confidence * 100).toInt()}%)")
    }

    // Action 2: Alert on high confidence threats
    config.registerCustomAction("alert_high_confidence") { threat ->
        if (threat.confidence >= 0.85) {
            sendSecurityAlert(threat)
            System.exit(1)
        }
    }

    // Action 3: Track specific threat types
    config.registerCustomAction("track_debugger") { threat ->
        if (threat.threatType == "DEBUGGER_ATTACHED") {
            recordDebuggerEvent(threat)
        }
    }

    // Action 4: Conditional erase
    config.registerCustomAction("conditional_erase") { threat ->
        if (threat.confidence >= 0.95) {
            clearSensitiveData(context)
            System.exit(1)
        }
    }

    // Apply actions to different modules
    config.addProtection(
        ProtectionModuleType.MEMORY_DUMP_DETECTION,
        "log_all_threats",
        2000
    )

    config.addProtection(
        ProtectionModuleType.NETWORK_TAMPERING,
        "alert_high_confidence",
        2000
    )

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "track_debugger",
        1000
    )

    config.addProtection(
        ProtectionModuleType.PROCESS_INJECTION,
        "conditional_erase",
        2000
    )
}

Multiple Custom Actions (Java)

Java
Monitor.configure(config -> {
    // Action 1: Simple logging
    config.registerCustomAction("log_all_threats", threat ->
        System.out.println("Threat logged: " + threat.getThreatType() +
            " (" + (int)(threat.getConfidence() * 100) + "%)")
    );

    // Action 2: Alert on high confidence threats
    config.registerCustomAction("alert_high_confidence", threat -> {
        if (threat.getConfidence() >= 0.85) {
            sendSecurityAlert(threat);
            System.exit(1);
        }
    });

    // Action 3: Track specific threat types
    config.registerCustomAction("track_debugger", threat -> {
        if (threat.getThreatType().equals("DEBUGGER_ATTACHED")) {
            recordDebuggerEvent(threat);
        }
    });

    // Action 4: Conditional erase
    config.registerCustomAction("conditional_erase", threat -> {
        if (threat.getConfidence() >= 0.95) {
            clearSensitiveData(context);
            System.exit(1);
        }
    });

    // Apply actions to different modules
    config.addProtection(
        ProtectionModuleType.MEMORY_DUMP_DETECTION,
        "log_all_threats",
        2000
    );

    config.addProtection(
        ProtectionModuleType.NETWORK_TAMPERING,
        "alert_high_confidence",
        2000
    );

    config.addProtection(
        ProtectionModuleType.DEBUGGER_DETECTION,
        "track_debugger",
        1000
    );

    config.addProtection(
        ProtectionModuleType.PROCESS_INJECTION,
        "conditional_erase",
        2000
    );
});

Error Handling

Implement safe error handling in your custom actions to prevent handler failures from crashing the application:

Kotlin
config.registerCustomAction("safe_handler") { threat ->
    try {
        // Your custom logic here
        sendSecurityAlert(threat)
        trackAnalytics(threat)
    } catch (e: Exception) {
        // Fallback behavior - log and exit safely
        System.err.println("Handler error: ${e.message}")
        e.printStackTrace()

        // Attempt graceful fallback
        try {
            clearCriticalData(context)
        } catch (fallbackError: Exception) {
            fallbackError.printStackTrace()
        }

        System.exit(1)
    }
}

Best Practices

  • Keep Handlers Fast: Minimize processing in custom actions to avoid blocking threat detection
  • Avoid Sensitive Operations: Don't call risky APIs in threat handlers that might be intercepted
  • Log Everything: Record all threat occurrences for later analysis
  • Test Thoroughly: Test custom actions with realistic threat scenarios
  • Combine Actions: Use multiple custom actions for comprehensive threat response
  • Monitor Performance: Track performance impact of custom action execution
  • Implement Fallbacks: Provide default behavior if custom handlers fail
  • Use Confidence Levels: Implement different behaviors based on threat confidence scores
  • Metadata Analysis: Leverage metadata for context-aware responses
  • Timeout Protection: Keep handler execution time short to prevent timing issues

DetectionResult Properties

When accessing threat properties in custom handlers, use these available properties:

Kotlin (property accessors):

  • threat.threatType (String): Type of threat detected
  • threat.description (String): Detailed description
  • threat.confidence (Double): Confidence score (0.0-1.0)
  • threat.metadata (Map): Additional context
  • threat.isThreatDetected() (Boolean): Confirmed threat status

Java (getter methods):

  • threat.getThreatType(): Type of threat detected
  • threat.getDescription(): Detailed description
  • threat.getConfidence(): Confidence score (0.0-1.0)
  • threat.getMetadata(): Additional context
  • threat.isThreatDetected(): Confirmed threat status

Log Action

Record threats to internal logger

Close Action

Terminate application immediately

Erase Action

Wipe sensitive data before termination

Previous
Erase
Next
None