secure_shield #

Secure Shield is a layered security shield that protects your Flutter applications against rooting/jailbreaking, debuggers, emulators, hooking frameworks, and other advanced tampering methods. It detects threats in real time, analyzes risks intelligently, and responds instantly to attacks with configurable automated responses. With its ‘easy to start, difficult to master’ philosophy, beginners can enable basic protection with a single line of code, while experts can take security to a professional level with detailed policy and fine-tuning options.

✨ Table of Contents #

Features Quick Start Setup Usage and Policies Required Native Setup Known Limitations & Disclaimers License

Features #

Multi-Channel Threat Detection: Secure Shield provides comprehensive protection by simultaneously monitoring different attack channels:

• Root (Android) & Jailbreak (iOS) detection.
• Emulator (Android) & Simulator (iOS) detection.
• Debugger detection (API and process status).
• Application Integrity (Anti-Tamper) check (installer source & debuggable status).
• Hooking Framework detection.

Intelligent Analysis: It combines the detected threats to produce a meaningful Threat Level: (CRITICAL, HIGH, MEDIUM, LOW). This enables the system to evaluate both the severity and the likelihood of detected attacks.

Flexible & Automated Response: Thanks to the flexible policy engine, you can easily configure application behavior. Example: Automatically terminate the application in case of certain threats terminateOnRoot: true

Built-in Network Security: It automatically blocks insecure http:// traffic at the platform level, ensuring all communication occurs securely via https://.

Remote Management (Optional): Thanks to Firebase Remote Config integration, security policies can be updated remotely in real time — enabling risk management without releasing new versions.

Developer-Friendly Logging:

All analyses and decisions made are sent to the developer console as detailed logs, making it easy to monitor and evaluate security incidents.

Quick Start #

Add the package to your 'pubspec.yaml':

dependencies: 
	secure_shield: ^1.0.0 
# Use the latest version from pub.flutter-io.cn

In your main.dart, enable the most critical protections:

import 'package:secure_shield/secure_shield.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // --- Security Policy ---
  // Rule: If any of the threats listed below are detected,
  // the application will be immediately and automatically closed.
  SecureShield.initialize(SecureShieldConfig(
    
    // If the device is rooted (Android) or jailbroken (iOS), close the application.
    terminateOnRoot: true,

    // If the application is detected to be running on an emulator or simulator, close the application.
    terminateOnEmulator: true,

    // If a debugger is connected to the application, close the application.
    terminateOnDebugger: true,

    // If a hooking framework such as Frida is detected as active, close the application.
    terminateOnHooking: true,

    // If the app is detected as tampered with (re-packaged, in debug mode, etc.), close the app.
    terminateOnTampered: true,

  ));

  runApp(const MyApp());
}

Then, to perform a check anywhere in your app:

final Assessment assessment = await SecureShield.getAssessment();
if (assessment.threatLevel != ThreatLevel.NONE) {
  print("A security risk was detected: ${assessment.threatLevel}");
}

Setup #

pubspec.yaml Add the package under dependencies and run flutter pub get.

Android

minSdkVersion: The package is compatible with minSdkVersion 21 or higher. ProGuard / R8: If you use code minification or obfuscation, add the following rules to your android/app/proguard-rules.pro file to ensure RootBeer works correctly:

-keep class com.scottyab.rootbeer.** { *; } 
-dontwarn com.scottyab.rootbeer.**

iOS

• The package supports iOS 11.0 and higher.

Usage and Policies #

Using the package consists of two main steps: initialize to set the policy and getAssessment to trigger the check.

initialize() - Setting the Policy #

This method should be called once in your main function. It offers three levels of configuration:

1. Simple Policy (Recommended for most) Define which threats should terminate the app using simple booleans.

SecureShield.initialize(SecureShieldConfig( 
	terminateOnRoot: true, 
	terminateOnHooking: true,
	terminateOnTampered: true,
	
));

2. Advanced Policy (More granular control) Define actions based on the calculated ThreatLevel.

SecureShield.initialize(SecureShieldConfig(
  advancedPolicy: {
    ThreatLevel.CRITICAL: ThreatAction.TERMINATE_APP,
    ThreatLevel.HIGH: ThreatAction.TERMINATE_APP,
    ThreatLevel.MEDIUM: ThreatAction.REPORT_ONLY, // Warn the user but don't terminate
  },
));

3. Remote Policy (Most dynamic) Fetch the entire policy from Firebase Remote Config.

await SecureShield.initializeWithRemoteConfig();

Required Native Setup #

For some detection methods to work, you need to add the following to your project's native files.

Android (.../app/src/main/AndroidManifest.xml): Add the INTERNET permission before the <application> tag for hooking detection.

<uses-permission android:name="android.permission.INTERNET"/>

iOS (.../ios/Runner/Info.plist): Add the LSApplicationQueriesSchemes key before the closing </dict> tag for jailbreak detection.

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>cydia</string>
</array>

Known Limitations & Disclaimers #

• False-Positives: No detection method is 100% foolproof. Some manufacturer ROMs or unique device setups may trigger a false positive. Use the TERMINATE_APP policy with caution.

• Bypass Risk: A determined attacker can eventually bypass any client-side controls. This package provides a strong first line of defense that will deter the vast majority of attackers.

• iOS fork() Risk: The isJailbroken check relies on the fork() system call, which is undocumented by Apple and carries a small theoretical risk of App Store rejection (though extremely uncommon).

• Performance: All checks run on a background thread to prevent any UI performance issues, but avoid calling getAssessment() too frequently (e.g., multiple times per second).

License #

This project is licensed under the BSD 3-Clause License.