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: '[email protected]',
isProd: true,
};
Important: The
certificateHashesfield 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.