Getting Started

Installation

npm

npm install @capgo/capacitor-is-root
npx cap sync

yarn

yarn add @capgo/capacitor-is-root
npx cap sync

pnpm

pnpm add @capgo/capacitor-is-root
npx cap sync

bun

bun add @capgo/capacitor-is-root
npx cap sync

Platform Support

• Android: Full support for root and emulator detection
• iOS: No configuration required (plugin is Android-focused)

Usage Example

import { IsRoot } from '@capgo/capacitor-is-root';

// Basic root detection
const rootResult = await IsRoot.isRooted();
if (rootResult.isRooted) {
  console.log('Device is rooted');
  // Handle rooted device appropriately
  // Example: Show warning, limit functionality, or block access
}

// Extended root detection with BusyBox
const extendedResult = await IsRoot.isRootedWithBusyBox();
if (extendedResult.isRooted) {
  console.log('Device is rooted (extended check)');
}

// Check for emulator
const emulatorResult = await IsRoot.isRunningOnEmulator();
if (emulatorResult.isEmulator) {
  console.log('Running on emulator');
  // Handle emulator environment
}

// Detect root management apps
const rootAppsResult = await IsRoot.detectRootManagementApps();
if (rootAppsResult.hasRootApps) {
  console.log('Root management apps detected');
}

// Check for su binary
const suResult = await IsRoot.checkForSuBinary();
if (suResult.hasSu) {
  console.log('SU binary found on device');
}

API Reference

isRooted()

isRooted() => Promise<{ isRooted: boolean }>

Performs comprehensive root detection using default methods.

Returns: Promise<{ isRooted: boolean }>

isRootedWithBusyBox()

isRootedWithBusyBox() => Promise<{ isRooted: boolean }>

Extended root detection including BusyBox checks.

Returns: Promise<{ isRooted: boolean }>

detectRootManagementApps()

detectRootManagementApps() => Promise<{ hasRootApps: boolean }>

Identifies installed root management applications (SuperSU, Magisk, etc.).

Returns: Promise<{ hasRootApps: boolean }>

checkForSuBinary()

checkForSuBinary() => Promise<{ hasSu: boolean }>

Checks for the presence of su binary in system paths.

Returns: Promise<{ hasSu: boolean }>

isRunningOnEmulator()

isRunningOnEmulator() => Promise<{ isEmulator: boolean }>

Detects common Android emulator fingerprints.

Returns: Promise<{ isEmulator: boolean }>

Comprehensive Security Check

import { IsRoot } from '@capgo/capacitor-is-root';

async function performSecurityCheck() {
  const checks = {
    rooted: false,
    emulator: false,
    rootApps: false,
    suBinary: false
  };

  try {
    // Run all detection methods
    const [rootResult, emulatorResult, rootAppsResult, suResult] = await Promise.all([
      IsRoot.isRootedWithBusyBox(),
      IsRoot.isRunningOnEmulator(),
      IsRoot.detectRootManagementApps(),
      IsRoot.checkForSuBinary()
    ]);

    checks.rooted = rootResult.isRooted;
    checks.emulator = emulatorResult.isEmulator;
    checks.rootApps = rootAppsResult.hasRootApps;
    checks.suBinary = suResult.hasSu;

    // Determine security level
    const securityIssues = Object.values(checks).filter(v => v).length;

    if (securityIssues > 0) {
      console.warn(`Device has ${securityIssues} security concern(s)`, checks);
      return {
        secure: false,
        issues: checks
      };
    }

    return {
      secure: true,
      issues: checks
    };
  } catch (error) {
    console.error('Security check failed:', error);
    throw error;
  }
}

// Use in your app
const securityStatus = await performSecurityCheck();
if (!securityStatus.secure) {
  // Handle insecure device
  showSecurityWarning(securityStatus.issues);
}

Detection Techniques

Root Detection

The plugin employs multiple detection methods:

• Checks for root management applications (SuperSU, Magisk, KingRoot, etc.)
• Scans for suspicious system properties
• Identifies test build tags and debug flags
• Validates dangerous binary locations
• Examines system path permissions
• Detects known root cloaking apps

Emulator Detection

• Hardware fingerprint analysis
• Build property inspection
• Emulator-specific characteristics
• Virtual environment indicators

Handling Security Issues

import { IsRoot } from '@capgo/capacitor-is-root';

async function handleDeviceSecurity() {
  const rootResult = await IsRoot.isRooted();

  if (rootResult.isRooted) {
    // Option 1: Show warning and continue
    showWarning('Your device appears to be rooted. Some features may be limited.');

    // Option 2: Limit functionality
    disableSensitiveFeatures();

    // Option 3: Block access to app
    showBlockedScreen('This app cannot run on rooted devices for security reasons.');
    return false;
  }

  return true;
}

function showWarning(message: string) {
  // Show user-friendly warning dialog
  alert(message);
}

function disableSensitiveFeatures() {
  // Disable payment processing, sensitive data access, etc.
  console.log('Sensitive features disabled due to rooted device');
}

function showBlockedScreen(message: string) {
  // Show blocking screen and exit app
  alert(message);
}

Best Practices

• Use multiple detection methods for higher accuracy
• Implement graceful degradation rather than blocking access entirely
• Provide clear user communication about security concerns
• Consider the user experience when implementing security measures
• Keep the plugin updated as detection methods evolve
• Test on both rooted and non-rooted devices
• Handle detection failures gracefully

Security Considerations

• No detection method is 100% foolproof
• Advanced users can bypass detection mechanisms
• Use in combination with server-side security measures
• Consider user privacy when implementing security checks
• Follow platform guidelines for security implementations
• Regular updates recommended as root hiding techniques evolve

Use Cases

• Banking and financial apps: Prevent access on compromised devices
• DRM-protected content: Protect copyrighted material
• Enterprise apps: Enforce BYOD security policies
• Payment processing: Ensure secure transaction environment
• Sensitive data apps: Protect confidential information