Android SDK — Integration Guide - InsightAI Documentation

Repository

github.com/InsightAI-Pinnacle-Technologies/di-sdk-android-rasp-v1.0.2

Requirements

minSdk 24 (Android 7.0+)
NDK r26+ and CMake 3.22+ — required for the native ptrace/TracerPid layer that makes debugger/Frida detection resistant to Java-layer hooking
A GitHub Personal Access Token with read:packages scope (this SDK is distributed privately via GitHub Packages while pre-GA — see Authentication for your tenant credentials, which are separate from your GitHub PAT)

Install

Add the GitHub Packages repository

settings.gradle

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/InsightAI-Pinnacle-Technologies/di-sdk-android-rasp-v1.0.2")
            credentials {
                username = "your-github-username"
                password = "your-github-personal-access-token"
            }
        }
    }
}

Add the dependency

app/build.gradle

dependencies {
    implementation 'ai.insight:rasp-sdk:1.0.0'
}

Install the NDK

Android Studio → Tools → SDK Manager → SDK Tools tab → check “NDK (Side by side)” and “CMake”. Without this, the native detection layer won’t link — see Testing for how to confirm it did.

Initialize

// Application.onCreate()
InsightAiSdk.init(
    context = this,
    config = InsightAiConfig(
        tenantId = "your_tenant_id",
        ingestUrl = "https://ingest.insightsecure.ai/v1/rasp/ingest",
        hmacSecretKey = BuildConfig.INSIGHTAI_HMAC_SECRET, // from your tenant credentials — see Authentication
        expectedApkSignatureHashes = setOf("<your release cert SHA-256>"),
        maliciousPackageList = RemoteThreatList.current(), // fetch from your backend, don't hardcode
    )
)

Gate a sensitive action

val evaluation = InsightAiSdk.evaluate(context)
when (evaluation.raspAction) {
    "BLOCK"  -> showBlockedScreen()
    "REVIEW" -> proceedWithStepUpAuth()
    else     -> proceedNormally()
}

Protect a sensitive screen

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    InsightAiSdk.protectScreen(this) // FLAG_SECURE — blocks screenshots, recording, mirroring
}

// Also forward touch events for active overlay detection:
override fun dispatchTouchEvent(event: MotionEvent): Boolean {
    InsightAiSdk.forwardTouchEvent(event)
    return super.dispatchTouchEvent(event)
}

MITM detection

Wire your network layer’s pin-mismatch callback:

try {
    val response = client.newCall(request).execute()
} catch (e: SSLPeerUnverifiedException) {
    InsightAiSdk.reportSslPinMismatch(host = request.url.host)
    throw e
}

2+ mismatches in one session sets MITM_SUSPECTED and hard-blocks — same tier as a signature mismatch.

Device binding (Play Integrity)

val token = PlayIntegrityBridge.requestIntegrityToken(
    context = this,
    cloudProjectNumber = YOUR_CLOUD_PROJECT_NUMBER, // Play Console → App Integrity
    requestHash = sha256("$transactionId:$amount:$timestamp"),
)

This token must be verified server-side against Google’s decode API. The SDK cannot verify it locally — a compromised client could fake a local “verified” result, which defeats the entire point of the check.

SIM binding

Not bundled — this requires a paid third-party provider (tru.ID, Twilio Verify). The SDK ships the integration interface only:

SimBindingConfig.provider = YourChosenProvider(apiKey = BuildConfig.SIM_PROVIDER_KEY)

// Gate to high-value transactions or REVIEW-tier events — per-verify
// cost compounds fast at volume if called on every evaluate().
val swapDetected = SimBindingConfig.provider?.checkSimSwap(user.phoneNumber)

OTP-less authentication

val response = OtpLessAuthManager.respondToChallenge(challengeNonce, deviceId)
if (response == null) {
    // No binding key yet — fall back to OTP for this session
} else {
    // Send response.signature to your backend for verification
}

Testing each control

Control	How to test
Root detection	Rooted physical device (Magisk) or `adb root` on an AVD
Frida/debugger	`frida-server` on a rooted device, attach with `frida -U -f <package>`
Tamper (signature mismatch)	Re-sign the APK with a different keystore, reinstall
MITM	Route traffic through Burp Suite/mitmproxy with its CA trusted — the connection should fail before reaching the proxy
Overlay	Grant a test app `SYSTEM_ALERT_WINDOW`, have it draw over your app during a touch
Native ptrace layer specifically	Confirm the NDK actually linked — attach a debugger and check `nativeTracerNonzero` reads `true`, not just the Java-layer `debuggerConnected`

Known limitations

SIM binding needs your own provider integration — not included
Play Integrity verdict decoding is a backend responsibility, not something this SDK does
No iOS equivalent to Android’s signature-hash tamper check exists — if you also integrate InsightAI’s iOS SDK, its tamper detection is a weaker sideload heuristic by platform necessity, not an oversight

Get Started

Device Intelligence

AML Case Investigation

Android SDK — Integration Guide

Repository

Requirements

Install

Initialize

Gate a sensitive action

Protect a sensitive screen

MITM detection

Device binding (Play Integrity)

SIM binding

OTP-less authentication

Testing each control

Known limitations

Next steps

Full RASP detection reference

Webhook payload reference

Repository

​Requirements

​Install

​Initialize

​Gate a sensitive action

​Protect a sensitive screen

​MITM detection

​Device binding (Play Integrity)

​SIM binding

​OTP-less authentication

​Testing each control

​Known limitations

​Next steps

Full RASP detection reference

Webhook payload reference

Requirements

Install

Initialize

Gate a sensitive action

Protect a sensitive screen

MITM detection

Device binding (Play Integrity)

SIM binding

OTP-less authentication

Testing each control

Known limitations

Next steps