Securing Your React Native App with FreeRasp: A Practical Implementation Guide

Introduction

Building a mobile application that handles sensitive financial data — crypto transactions, KYC verification, gift cards — means security is not an afterthought. It is a core deliverable.

During the development of a cross-platform fintech application, one of the non-negotiables on the security checklist was runtime application self-protection (RASP). After evaluating our options, we integrated FreeRasp — an open-source mobile security library — into our React Native codebase.

In this article, I'll walk you through what FreeRasp is, why we chose it, how we integrated it into a React Native project, and the key lessons learned along the way.

What is FreeRasp?

FreeRasp is an open-source RASP (Runtime Application Self-Protection) SDK maintained by Talsec. It provides real-time threat detection for mobile applications by monitoring the environment in which your app is running.

It detects threats such as:

• Rooted or jailbroken devices — devices where OS security boundaries have been removed
• Debugger attachment — active reverse engineering attempts
• Emulator detection — app running in an emulated environment (common in fraud scenarios)
• Tampering / repackaging — modified APKs or IPAs being distributed
• Unofficial stores — app installed from an untrusted source
• Hook frameworks — tools like Frida being used to intercept app behaviour
• Overlay attacks — malicious apps drawing over your UI to steal input

For a fintech app handling real user funds and identity documents, these are not theoretical threats.

Why FreeRasp Over the Alternatives?

We considered a few options:

Option	Pros	Cons
FreeRasp	Open source, React Native support, active maintenance, no per-user cost	Requires configuration per platform
Appdome	Comprehensive, no-code	Expensive, vendor lock-in
Custom RASP	Full control	Enormous dev effort, hard to maintain

FreeRasp hit the sweet spot for our stage: production-grade security without the enterprise price tag.

Installation

npm install freerasp-react-native
# or
yarn add freerasp-react-native

For iOS, run pod install after:

cd ios && pod install

Basic Configuration

FreeRasp is configured once — typically in your app's entry point or a dedicated security module. Here is the configuration structure we used:

import { useFreeRasp, setThreatListeners } from 'freerasp-react-native';

const config = {
  androidConfig: {
    packageName: 'com.yourapp.package',
    certificateHashes: ['your-certificate-hash'],
    supportedAlternativeStores: [],
  },
  iosConfig: {
    appBundleId: 'com.yourapp.bundle',
    appTeamId: 'YOUR_TEAM_ID',
  },
  watcherMail: '[e-mail]',
  isProd: true,
};

Important: The certificateHashes field must match the SHA-256 hash of your app's signing certificate. A mismatch will trigger a tamper alert even in your own build.

Handling Threats

This is where the real implementation decision lies. FreeRasp detects threats and calls your handler — but what you do with that information is entirely your responsibility.

const actions = {
  // Critical threats — terminate session or block access
  rootDetected: () => handleCriticalThreat('root'),
  debugDetected: () => handleCriticalThreat('debug'),
  hookDetected: () => handleCriticalThreat('hook'),

  // High severity — warn and limit functionality
  emulatorDetected: () => handleHighThreat('emulator'),
  tamperDetected: () => handleCriticalThreat('tamper'),

  // Medium severity — log and monitor
  unofficialStoreDetected: () => handleMediumThreat('unofficialStore'),
  deviceBindingDetected: () => handleMediumThreat('deviceBinding'),

  // Informational
  passcodeNotSet: () => promptUserToSetPasscode(),
};

const handleCriticalThreat = (threatType) => {
  // Log the event to your backend
  logSecurityEvent(threatType, 'critical');

  // Clear sensitive data from state
  clearSensitiveData();

  // Navigate to a blocked screen
  navigationRef.current?.navigate('SecurityBlock', { reason: threatType });
};

Our Threat Response Strategy

We categorised threats into three tiers and responded accordingly:

Tier 1 — Block immediately (root, hook, tamper, debug in prod)
The user sees a security error screen. No financial actions are possible. The session is terminated and the backend is notified.

Tier 2 — Degrade gracefully (emulator, unofficial store)
Read-only mode is allowed. Transactions and KYC submission are disabled. The user is informed that full functionality requires a verified device.

Tier 3 — Log and monitor (passcode not set, device binding)
The user is prompted with a recommendation. Functionality is not blocked but the event is logged for analytics.

Lessons Learned

1. Test certificate hashes early
We spent time debugging what looked like a tamper detection issue in staging. The root cause was a mismatch between our debug and release certificate hashes. Always configure separate hashes per environment.

2. Don't block users silently
Your UX around security matters. We initially just crashed the blocked screen with no explanation. We updated it to clearly tell users their device environment isn't trusted and guide them to contact support if they believe it's an error.

3. False positives are real
Some older Android devices or development builds can trigger emulator detection unexpectedly. Build a backend feedback mechanism so your security team can review flagged sessions rather than blindly blocking users.

4. Combine with backend validation
FreeRasp is a client-side layer. A determined attacker can bypass it. Pair it with server-side checks: JWT binding, IP monitoring, transaction anomaly detection. Defence in depth is the goal.

5. isProd matters
Always ensure isProd: true in your production builds. FreeRasp behaves differently in dev mode and will not enforce certain checks. We added this as a required CI check before any release.

Conclusion

Integrating FreeRasp into our React Native fintech application significantly raised our security baseline without adding meaningful friction to the user experience. For any app handling financial data, identity documents, or crypto assets, runtime protection is no longer optional.

The library is actively maintained, well-documented, and free — which makes it an easy recommendation for any React Native team working in regulated domains.

If you have questions about the implementation or want to discuss your own RASP strategy, feel free to reach out or leave a comment below.

Nathaniel Toju is a cross-platform mobile and backend engineer based in Lagos, Nigeria, building fintech and healthcare products. He specialises in React Native, NestJS, and secure application architecture.