React Native Security Checker

A comprehensive React Native security checker that detects jailbreak, root, emulators, hooks, tampering, and other security threats on both iOS and Android platforms.

Features

Android Security Checks

• Root Detection: Enhanced root detection using RootBeer library with multiple fallback methods
• Emulator Detection: Identifies if running on Android emulator
• Work Profile Detection: Checks if app is running in a work profile
• App Cloning Detection: Detects if app is running in cloned environment
• Secondary User Detection: Identifies if running as secondary user
• Debug Detection: Checks if app is debuggable or in debug mode
• USB Debugging Detection: Detects if USB debugging is enabled
• VPN Detection: Identifies active VPN connections
• Hook Detection: Detects if app is hooked by frameworks like Xposed
• Tamper Detection: Checks if app has been tampered with
• Virtual Space Detection: Identifies virtual environment apps
• Suspicious Apps Detection: Detects known suspicious applications
• Sandbox Detection: Identifies sandbox environments
• Anti-Debug Detection: Detects if debugger is currently attached
• Background Detection: Identifies if app is running in background
• Proxy Detection: Detects proxy and VPN applications
• Network Monitoring Detection: Identifies network monitoring tools
• Biometric Security: Checks for biometric bypass applications
• Performance Anomaly Detection: Identifies unusual performance patterns
• Runtime Integrity: Detects runtime manipulation and tampering

iOS Security Checks

• Jailbreak Detection: Comprehensive jailbreak detection using multiple methods
• Emulator Detection: Identifies iOS Simulator
• Debug Detection: Detects if debugger is attached
• Hook Detection: Detects hooking frameworks like Substrate, Frida
• Tamper Detection: Validates app signature and detects code injection
• Simulator Detection: Identifies if running on iOS Simulator
• Suspicious Apps Detection: Detects known jailbreak apps
• Sandbox Detection: Identifies sandbox environments
• Virtual Space Detection: Detects virtual environment apps
• Cloning Detection: Checks for multiple app instances
• Anti-Debug Detection: Detects if debugger is currently attached
• Proxy Detection: Detects proxy and VPN applications
• Network Monitoring Detection: Identifies network monitoring tools
• Biometric Security: Checks for biometric bypass applications
• Performance Anomaly Detection: Identifies unusual performance patterns
• Runtime Integrity: Detects runtime manipulation and tampering

Installation

npm install react-native-security-checker

iOS Setup

Add the following to your ios/Podfile:

pod 'react-native-security-checker', :path => '../node_modules/react-native-security-checker'

Then run:

cd ios && pod install

Android Setup

No additional setup required for Android.

Usage

Basic Usage (All Checks)

import { detectEnvironment, SecurityCheckResult } from 'react-native-security-checker';

const checkSecurity = async () => {
  try {
    const result: SecurityCheckResult = await detectEnvironment();
    
    console.log('Security Check Results:', result);
    
    if (result.isInsecureEnvironment) {
      console.warn('Insecure environment detected!');
      
      // Handle specific threats
      if (result.isRooted || result.isJailbroken) {
        console.warn('Device is rooted/jailbroken');
      }
      
      if (result.isEmulator || result.isRunningInSimulator) {
        console.warn('Running on emulator/simulator');
      }
      
      if (result.isHooked) {
        console.warn('App is hooked by frameworks');
      }
      
      if (result.isTampered) {
        console.warn('App has been tampered with');
      }
    } else {
      console.log('Environment appears secure');
    }

    // Display user-friendly messages
    if (result.messages && result.messages.length > 0) {
      result.messages.forEach(message => {
        console.log(`${message.type.toUpperCase()}: ${message.title}`);
        console.log(message.message);
        if (message.suggestion) {
          console.log(`Suggestion: ${message.suggestion}`);
        }
      });
    }
  } catch (error) {
    console.error('Security check failed:', error);
  }
};

// Run security check
checkSecurity();

Continuous Monitoring with Hook

For continuous security monitoring with automatic checks on app state changes, use the useSecurityChecker hook:

import React from 'react';
import { View, Text, Button, Alert } from 'react-native';
import { useSecurityChecker, createDefaultConfig } from 'react-native-security-checker';

function MyComponent() {
  const config = createDefaultConfig();
  
  const {
    state,
    checkSecurity,
    startMonitoring,
    stopMonitoring,
    reset
  } = useSecurityChecker(
    (result) => {
      // Called when security issues are detected
      console.log('Security issue detected:', result);
      Alert.alert('Security Alert', 'Security threat detected!');
    },
    5000, // Check every 5 seconds
    {
      config,
      checkOnBackground: true,    // Check when app goes to background
      checkOnForeground: true,   // Check when app comes to foreground
      startImmediately: true,    // Start monitoring immediately
      enableContinuousMonitoring: true // Enable periodic checks
    }
  );

  return (
    <View>
      <Text>Monitoring: {state.isMonitoring ? 'Active' : 'Inactive'}</Text>
      <Text>Checks performed: {state.checkCount}</Text>
      <Text>Last check: {state.lastCheckTime ? new Date(state.lastCheckTime).toLocaleTimeString() : 'Never'}</Text>
      
      <Button title="Start Monitoring" onPress={startMonitoring} />
      <Button title="Stop Monitoring" onPress={stopMonitoring} />
      <Button title="Manual Check" onPress={checkSecurity} />
      <Button title="Reset" onPress={reset} />
      
      {state.lastError && (
        <Text style={{color: 'red'}}>Error: {state.lastError.message}</Text>
      )}
    </View>
  );
}

Configurable Usage

import { 
  detectEnvironment, 
  createDefaultConfig, 
  createMinimalConfig, 
  createComprehensiveConfig,
  SecurityCheckConfig 
} from 'react-native-security-checker';

// Use predefined configurations
const minimalResult = await detectEnvironment(createMinimalConfig());
const defaultResult = await detectEnvironment(createDefaultConfig());
const fullResult = await detectEnvironment(createComprehensiveConfig());

// Custom configuration
const customConfig: SecurityCheckConfig = {
  // Basic Security Checks
  checkRooted: true,
  checkJailbroken: true,
  checkEmulator: true,
  checkSimulator: true,
  checkHooked: true,
  checkTampered: true,
  
  // Advanced Security Checks
  checkProxy: true,
  checkNetworkMonitoring: false, // Skip network monitoring
  
  // Performance Options
  includeRootDetails: true,
  enableFastMode: false,
  enableDetailedChecks: true,
};

const customResult = await detectEnvironment(customConfig);

Hook Options

The useSecurityChecker hook accepts the following options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | config | SecurityCheckConfig | undefined | Configuration for security checks | | interval | number | 5000 | Interval in milliseconds for periodic checks | | checkOnBackground | boolean | true | Check when app goes to background | | checkOnForeground | boolean | true | Check when app comes to foreground | | startImmediately | boolean | true | Start monitoring immediately | | enableContinuousMonitoring | boolean | true | Enable periodic checks |

Configuration Options

const config: SecurityCheckConfig = {
  // Basic Security Checks
  checkWorkProfile: boolean,           // Android work profile detection
  checkCloned: boolean,               // App cloning detection
  checkSecondaryUser: boolean,        // Secondary user detection
  checkRooted: boolean,               // Root detection (Android)
  checkJailbroken: boolean,           // Jailbreak detection (iOS)
  checkEmulator: boolean,             // Emulator detection
  checkSimulator: boolean,            // Simulator detection (iOS)
  checkDebuggable: boolean,           // Debuggable app detection
  checkDeveloperMode: boolean,        // Developer mode detection
  checkUSBDebugging: boolean,         // USB debugging detection
  checkVPN: boolean,                  // VPN detection
  checkHooked: boolean,               // Hook detection
  checkTampered: boolean,             // Tamper detection
  checkVirtualSpace: boolean,         // Virtual space detection
  checkSuspiciousApps: boolean,       // Suspicious apps detection
  checkSandbox: boolean,              // Sandbox detection
  
  // Advanced Security Checks
  checkDebuggerAttached: boolean,     // Debugger attachment detection
  checkRunningInBackground: boolean,  // Background execution detection
  checkProxy: boolean,                // Proxy detection
  checkNetworkMonitoring: boolean,    // Network monitoring detection
  checkBiometricCompromised: boolean, // Biometric security detection
  checkPerformanceAnomaly: boolean,   // Performance anomaly detection
  checkRuntimeIntegrity: boolean,     // Runtime integrity detection
  
  // Root Detection Details
  includeRootDetails: boolean,        // Include detailed root detection info
  
  // Performance Options
  enableFastMode: boolean,            // Skip expensive checks
  enableDetailedChecks: boolean,      // Include detailed analysis
};

API Reference

detectEnvironment(): Promise<SecurityCheckResult>

Performs comprehensive security checks and returns a promise with the results.

SecurityCheckResult Interface

interface SecurityCheckResult {
  // Android specific checks
  isWorkProfile?: boolean;           // Device is in work profile
  isCloned?: boolean;               // App is running in cloned environment
  isSecondaryUser?: boolean;        // Running as secondary user
  isRooted?: boolean;               // Device has root access
  isEmulator?: boolean;             // Running on emulator
  isDebuggable?: boolean;           // App is debuggable
  isDeveloperModeOn?: boolean;      // Developer mode is enabled
  isUSBDebuggingOn?: boolean;       // USB debugging is enabled
  isVPNActive?: boolean;            // VPN connection is active
  isHooked?: boolean;               // App is hooked by frameworks
  isTampered?: boolean;             // App has been tampered with
  isRunningInVirtualSpace?: boolean; // Running in virtual space
  hasSuspiciousApps?: boolean;      // Suspicious apps detected
  isRunningInSandbox?: boolean;     // Running in sandbox environment
  
  // iOS specific checks
  isJailbroken?: boolean;           // Device is jailbroken
  isDebugging?: boolean;            // Debugger is attached
  isRunningInSimulator?: boolean;   // Running on iOS Simulator
  
  // Root detection details (Android only)
  rootDetectionDetails?: RootDetectionDetails;
  
  // Overall security status
  isInsecureEnvironment: boolean;   // True if any security threat is detected
}

interface RootDetectionDetails {
  rootBeerIsRooted: boolean;                    // RootBeer primary detection
  rootBeerIsRootedWithoutBusyBoxCheck: boolean; // RootBeer without BusyBox check
  detectRootManagementApps: boolean;            // Root management apps detected
  detectPotentiallyDangerousApps: boolean;      // Potentially dangerous apps detected
  detectTestKeys: boolean;                      // Test keys detected
  checkForBusyBoxBinary: boolean;               // BusyBox binary found
  checkForSuBinary: boolean;                    // SU binary found
  checkSuExists: boolean;                       // SU command exists
  checkForRWPaths: boolean;                     // Read-write paths detected
  checkForDangerousProps: boolean;              // Dangerous properties detected
  checkForMagiskBinary: boolean;                // Magisk binary found
  customRootAppsCheck: boolean;                 // Custom root apps check
  customRootFilesCheck: boolean;                // Custom root files check
  customDangerousPropsCheck: boolean;           // Custom dangerous props check
  customSuBinaryCheck: boolean;                 // Custom SU binary check
  customRootNativeCheck: boolean;               // Custom root native check
  customBusyBoxCheck: boolean;                  // Custom BusyBox check
}

Security Features

Root/Jailbreak Detection

• RootBeer Integration: Uses the industry-standard RootBeer library for Android root detection
• Multiple Detection Methods: Combines RootBeer with custom detection methods for comprehensive coverage
• Detailed Analysis: Provides granular information about each detection method used
• Low False Positives: RootBeer's proven algorithms minimize false positive rates
• Magisk Detection: Specifically detects Magisk root solutions
• System Integrity: Validates system properties and environment variables

Emulator/Simulator Detection

• Identifies Android emulators and iOS simulators
• Checks device properties and hardware characteristics
• Validates system files and configurations

Hook Detection

• Detects Xposed, Substrate, and Frida frameworks
• Checks for hooked system functions
• Validates library integrity

Tamper Detection

• Validates app signatures
• Detects code injection
• Checks for repackaging signs

Virtual Environment Detection

• Identifies app cloning applications
• Detects virtual space environments
• Checks for multiple app instances

User-Friendly Messages

• Clear Explanations: Each security issue comes with a user-friendly explanation
• Actionable Suggestions: Specific steps users can take to resolve issues
• Severity Levels: Critical, High, Medium, and Low priority classifications
• Message Types: Error, Warning, and Info messages for different contexts
• Contextual Help: Messages explain what each security issue means and why it matters

Example App

The package includes a comprehensive example app that demonstrates all security features. To run it:

cd example
npm install
# For iOS
npx react-native run-ios
# For Android
npx react-native run-android

Security Considerations

• This library provides detection capabilities but cannot prevent all attacks
• Some detection methods may have false positives
• Consider implementing additional security measures based on your app's requirements
• Regularly update the library to get the latest detection methods

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library