Variables

TalsecConfig

Specifies configuration for your app. See the table below for a detailed description of the attributes.

Classes

public class ThreatListener

Constructor

public ThreatListener(@NonNull ThreatDetected threatsCallback, @Nullable DeviceState deviceStateCallback)

• Listener for the threats detected by freeRASP

Methods

public void registerListener(Context context)

Registers your reactions to detected threats with freeRASP.

public void unregisterListener(Context context)

Unregisters the reactions to detected threats.

public final class Talsec

Methods

public static void start(Context context, TalsecConfig config)

The method used to start freeRASP's functionality.

Interfaces

public interface ThreatDetected

Methods:

• void onRootDetected()

• void onDebuggerDetected()

• void onEmulatorDetected()

• void onTamperDetected()

• void onUntrustedInstallationSourceDetected()

• void onHookDetected()

• void onDeviceBindingDetected()

• void onObfuscationIssuesDetected()

public interface DeviceState

Methods:

• void onUnlockedDeviceDetected()

• void onHardwareBackedKeystoreNotAvailableDetected()

• void onDeveloperModeDetected()

• void onADBEnabledDetected()

• void onSystemVPNDetected()

The most frequent issues occurring during integration:

For more general issues or questions, visit FAQ page. You can also check out the Issues section of our GitHub repository, where you can report issues and view existing reports.

📝 Prerequisites

freeRASP requires a minimum SDK level of 23. To update the minimum SDK level of the application, follow these steps:

1. From the root of your project (or module level), go to the build.gradle.

2. Update minSdkVersion to at least 23 (Android 6.0) or higher.

buildscript {
    ext {
      minSdkVersion 23
    }
}

📦 Add the dependency

Set Talsec's Artifact Registry in your project's settings.gradle (or build.gradle). You should comment out the relevant section in settings.gradle, if you want to use build.gradle, as settings.gradle is preferred:

repositories {
        google()
        mavenCentral()
        maven { url "https://jitpack.io"}
        maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }
}

repositories {
    google()
    mavenCentral()
    maven { url "https://jitpack.io" }
    maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }
}

Set dependencies in your :app module's build.gradle:

dependencies {
    // freeRASP SDK  
    implementation 'com.aheaditec.talsec.security:TalsecSecurity-Community:13.0.0'
}

⚙️ Setup the Configuration for your App

To ensure freeRASP functions correctly, you need to provide the necessary configuration. All required values must be filled in for the plugin to operate properly. Use the following template to configure the plugin. Detailed descriptions of the configuration options are provided on the API page.

1. Create an arbitrary subclass of Application(), override its onCreate()method and implement ThreatListener.ThreatDetected interface. You can, of course, use your Application subclass if you already have one in your project. If you encounter issues importing ThreatListener.ThreatDetected, please use 'Sync Project with Gradle Files' to resolve them.“

   TalsecApplication.kt

   Copy

   class TalsecApplication : Application(), ThreatListener.ThreatDetected {
       override fun onCreate() {
           super.onCreate()
       }
   }

2. Add a new subclass to AndroidManifest.xml, inside <application> tag:

   AndroidManifest.xml

   Copy

   <application
       android:name=".TalsecApplication"
   />

3. Set up the Configuration for your app with your values, which are explained in more detail in API.

   TalsecApplication.kt

   Copy

   companion object {
       private const val expectedPackageName = "com.aheaditec.talsec.demoapp" // Don't use Context.getPackageName!
       private val expectedSigningCertificateHashBase64 = arrayOf(
           "mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k=",
           "ZjLPK1Dle5JS1aUu1NuNEVVXarMEsCXvni/Kv/FK+tw="
       ) // Replace with your release (!) signing certificate hashes
       private const val watcherMail = "john@example.com" // for Alerts and Reports
       private val supportedAlternativeStores = arrayOf(
           "com.sec.android.app.samsungapps" // Add other stores, such as the Samsung Galaxy Store
       )
       private val isProd = true
   }

   TalsecApplication.kt

   Copy

   override fun onCreate() {
       ...
       
       val config = TalsecConfig.Builder(
           expectedPackageName,
           expectedSigningCertificateHashBase64)
           .watcherMail(watcherMail)
           .supportedAlternativeStores(supportedAlternativeStores)
           .prod(isProd)
           .build()
   }

👷 Handle detected threats

You can handle the detected threats using listeners. For example, you can log the event, show a window to the user or kill the application. See the Threat detection to learn more details about the performed checks and their importance for app security.

1. Implement methods of ThreatListener.ThreatDetected interface:

   TalsecApplication.kt

   Copy

   override fun onRootDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onDebuggerDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onEmulatorDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onTamperDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onUntrustedInstallationSourceDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onHookDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onDeviceBindingDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onObfuscationIssuesDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) {
       println("onMalwareDetected")
   }

   Do not implement the onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) callback yet. It will be soon introduced as a new feature of freeRASP, although, it is implemented via this SDK as well. You can use just println("onMalwareDetected") for now.

2. Optionally, you can use a device state listener to get additional information about the device state, like passcode lock and HW-backed Keystore state:

   TalsecApplication.kt

   Copy

   private val deviceStateListener = object : ThreatListener.DeviceState {
       override fun onUnlockedDeviceDetected() {
           TODO("Not yet implemented")
       }
       override fun onHardwareBackedKeystoreNotAvailableDetected() {
           TODO("Not yet implemented")
       }
   
       override fun onDeveloperModeDetected() {
           TODO("Not yet implemented")
       }
       
       override fun onADBEnabledDetected() {
           TODO("Not yet implemented")
       }
   
       override fun onSystemVPNDetected() {
           TODO("Not yet implemented")
       }
   }

3. Modify initialization of ThreatListener:

   TalsecApplication.kt

   Copy

   override fun onCreate() {
       ...
       // ThreatListener(this).registerListener(this)
       ThreatListener(this, deviceStateListener).registerListener(this)
   }

🛡️ Start freeRASP

override fun onCreate() {
    ...
    Talsec.start(this, config)
}

🌁 Enable source code obfuscation

You can make sure that the obfuscation is enabled by checking the value of minifyEnabled property in your module's build.gradle file.

Read more about why this is important in the wiki.

android {
    ...
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

☢️ (Optionally) Integrate freeMalwareDetection

freeMalwareDetection is a powerful feature designed to enhance the security of your Android application by quickly and efficiently scanning for malicious or suspicious applications (e.g. Android malware) based on various blacklists and security policies.

It helps to detect apps with suspicious package names, hashes, or potentially dangerous permissions.

Visit the freeMalwareDetection repository to learn more about this feature! For the integration, refer to the integration guide for the Android platform.