Comprehensive device security toolkit: fingerprint-based stable IDs, root/jailbreak and emulator detection, app integrity checks, VPN/proxy inspection, remote-control/surveillance detection, modular detectors, aggregated risk scoring.
Kotlin Multiplatform SDK for comprehensive device security: fingerprinting, root/jailbreak detection, emulator detection, app integrity, network inspection, remote-control app detection, and surveillance / tampering detection — on Android, iOS, JVM/Desktop, and Web.
📘 Full documentation: https://dongnh311.github.io/DeviceGuardSDK/
Pre-release. APIs are unstable and may change before v0.1.0. See DEVICEGUARD_PLAN.md for the roadmap.
Coordinates will be published after Phase 9. Placeholder shown below.
// build.gradle.kts
dependencies {
implementation("io.github.dongnh311:deviceguard-core:0.1.0")
// or pick individual modules:
implementation("io.github.dongnh311:deviceguard-fingerprint:0.1.0")
implementation("io.github.dongnh311:deviceguard-rootcheck:0.1.0")
implementation("io.github.dongnh311:deviceguard-emulator:0.1.0")
implementation("io.github.dongnh311:deviceguard-integrity:0.1.0")
implementation("io.github.dongnh311:deviceguard-network:0.1.0")
implementation("io.github.dongnh311:deviceguard-remote:0.1.0")
implementation("io.github.dongnh311:deviceguard-surveillance:0.1.0")
}
val guard = DeviceGuard.Builder(context)
.enableFingerprint()
.enableRootCheck(strict = true)
.enableEmulatorCheck()
.enableIntegrityCheck(expectedSignature = "…")
.enableNetworkCheck()
.enableRemoteCheck()
.enableSurveillanceCheck()
.build()
val report = guard.analyze()
println("Risk: ${report.riskScore}/100")
println("Threats: ${report.threats}")
println("Device ID: ${report.fingerprint.id}")
analyze() gives a one-shot snapshot. For continuously monitoring the device, collect
DeviceGuard.observe(periodMs): it polls at the configured interval and only emits when
the threat set or fingerprint actually changes (same threats, same report → no emission).
guard.observe(periodMs = 5_000L).collect { report ->
updateUi(report)
}
Minimum period is 500 ms — leaves headroom above the 200 ms p95 per-analyze budget.
Legend: ✅ full coverage · ⚠️ partial / best-effort · — not applicable on this platform, or deferred pending a follow-up (cell text clarifies which). Both return DetectionResult.NotApplicable today.
Every detector is optional — only enabled modules run. analyze() fans them out concurrently via coroutineScope + async / awaitAll on the caller's dispatcher, isolating each with a try/catch; the orchestrator merges confidences into a single SecurityReport.riskScore (0–100) and riskLevel (SAFE / LOW / MEDIUM / HIGH / CRITICAL).
sample/ ships a Compose Multiplatform demo across every target. The UI lives once in
sample/shared/ (Material 3, Compose Multiplatform 1.7.x); each platform wrapper is a
thin entry point that hosts the shared App() composable.
Every app shows the same screen: toggle detectors, tap Analyze, inspect the live
SecurityReport — risk score with a coloured progress bar, threat list, fingerprint id,
error list, and end-to-end timing.
End-to-end smoke-verified on 2026-04-20 across all 4 samples with the full 7-detector build enabled: Desktop headless
./gradlew :sample:desktop:run— report produced; Android (Pixel 6 API 34 emulator) — 2 threats, 16 signals, MEDIUM risk, no false positives on the new Remote/Surveillance toggles; iOS (iPhone 16 Simulator, iOS 18) — CRITICAL risk on simulator (expected:Emulatoralways;ScreenBeingCapturedonly when AirPlay / ReplayKit / Control-Center recording is active); Web (Chromium headless @jsBrowserProductionWebpackoutput) — LOW risk, 1 threat, 13 signals, 21 ms elapsed.
Before the first release, each threat path must fire at least once on a real target. The table below is the checklist for that sweep — tick boxes as devices are exercised.
The v0.1.0 publish (Phase 9) is gated on every row above being confirmed on a real host.
Recording a short video or sharing the Copy JSON report payload per row is enough
evidence — attach to the release notes PR.
See the detector × platform matrix above for what each detector does on each OS, including the signal weights and how they're collected.
The deviceguard-fingerprint module collects non-PII platform signals and hashes them
(SHA-256 with length-prefixed encoding, no collision risk) into a stable device id.
Signals collected per platform:
No IMEI, advertising id, account name, email, or other directly identifying value is read — the fingerprint is stable across app launches but invalidates on a factory reset or MAC change.
deviceguard-rootcheck surfaces root on Android and jailbreak on iOS. Opt in via
DeviceGuard.Builder(context).enableRootCheck(strict = true). The detector aggregates
per-signal weights in [0.0, 1.0] and trips RootCheckResult.isRooted at:
strict = false (default): confidence ≥ 0.5 — a single strong signal wins.strict = true: confidence ≥ 0.2 — any moderate signal wins.Signals per platform:
When isRooted is true, the detector adds a ThreatType.Root (Android) or
ThreatType.Jailbreak (iOS) threat to SecurityReport.threats with the aggregated
confidence. The indicators list is suitable for forensic logging and contains no PII.
deviceguard-emulator surfaces emulator / virtual-device signals alongside
attached-debugger signals. Opt in via
DeviceGuard.Builder(context).enableEmulatorCheck(). Two disjoint indicator lists feed
two independent confidences (each clamped to [0, 1]) and trip
ThreatType.Emulator / ThreatType.DebuggerAttached independently at a fixed 0.5
threshold — so a debug build attached to an IDE on a real device produces a debugger
threat but not an emulator threat, and vice versa.
Signals per platform:
When a threat fires, EmulatorCheckResult carries separate emulatorIndicators and
debuggerIndicators lists so consumers don't need to parse prefixed strings to route
forensic logging. Unlike root detection, no strict knob is exposed — the primary
signals are deterministic (weight 1.0) and the threshold is a fixed 0.5.
deviceguard-integrity surfaces app-tampering and dynamic-instrumentation signals. Opt in
via DeviceGuard.Builder(context).enableIntegrityCheck(expectedSignature, trustedInstallers).
Two disjoint indicator streams feed two independent confidences at a fixed 0.5 threshold:
ThreatType.SignatureMismatch and ThreatType.HookFramework.
val guard = DeviceGuard.Builder(context)
.enableIntegrityCheck(
expectedSignature = "1A:2B:3C:…", // keytool-format accepted
trustedInstallers = setOf("com.android.vending"),
)
.build()
Signals per platform:
IntegrityCheckResult exposes , ,
, confidences, and separate indicator lists. — on platforms that skip the signature stream both fields are false, and the
detector advertises this via the signal. The
string is accepted in -style hex with
whitespace; the detector normalises to lowercase packed hex before comparison.
deviceguard-network surfaces active VPN tunnels and HTTP/SOCKS proxy routing. Opt in via
DeviceGuard.Builder(context).enableNetworkCheck(). Two disjoint indicator streams feed two
independent confidences at a fixed 0.5 threshold: ThreatType.VpnActive and
ThreatType.ProxyActive.
VPN / proxy presence is not inherently hostile — corporate deployments, privacy-focused users, and ISPs all legitimately terminate on tunnels — so the emitted threats carry intentionally low default weights. The detector surfaces the state; the risk-scoring strategy decides how much it matters.
Signals per platform:
NetworkCheckResult carries vpnActive, proxyActive, confidences, and separate
vpnIndicators / proxyIndicators lists so consumers don't parse prefixes. Interface
matching is case-insensitive (TAP0 on Windows and utun3 on macOS both count).
./gradlew build # all targets
./gradlew allTests # run all platform tests
./gradlew dokkaHtml # generate API docs
./gradlew koverHtmlReport # aggregated code coverage (HTML)
./gradlew koverXmlReport # aggregated code coverage (XML, for CI ingest)
Tests run at two layers:
Coverage reports are produced by the Kover plugin
and aggregated at the root. After ./gradlew koverHtmlReport, open
build/reports/kover/html/index.html.
A JVM p95 latency benchmark
(deviceguard-core/src/jvmTest/.../AnalyzePerfBenchmarkJvmTest.kt) guards the orchestrator's
overhead against the SDK's 200ms p95 budget on a mid-tier device. It runs synthetic stub
detectors on Dispatchers.Default, so regressions that drop detector parallelism or add
per-run blocking work fail the suite.
See CONTRIBUTING.md for dev setup and the PR workflow. Participation is
governed by our Code of Conduct. Release history is tracked in
CHANGELOG.md.
Do not file a public issue for security vulnerabilities. Follow the private disclosure
process in SECURITY.md.
Apache License 2.0 — see LICENSE.
Surfaced from shared tags and platforms — no rankings paid for.
| Detector | Android | iOS | Desktop JVM | Web (JS) |
|---|
Fingerprint (enableFingerprint) — stable non-PII device id | ✅ SHA-256 over Build.MANUFACTURER/BRAND/MODEL/DEVICE/PRODUCT/HARDWARE, SDK_INT, SUPPORTED_ABIS, Settings.Secure.ANDROID_ID, screen density/resolution, locale, timezone | ✅ SHA-256 over UIDevice.systemName/version/model, identifierForVendor, screen scale/bounds, locale, timezone | ✅ SHA-256 over os.name/version/arch, java.vendor/version, locale, timezone, SHA-256(first non-loopback MAC) | ⚠️ SHA-256 over navigator.userAgent/platform/language/hardwareConcurrency, screen resolution/colorDepth, timezone (best-effort — UA hardening degrades stability) |
RootCheck (enableRootCheck) — root / jailbreak | ✅ 13 su/Superuser/Magisk binary paths (w 1.0) · PackageManager scan against 12 root-tooling pkgs (w 0.9) · Build.TAGS == test-keys (w 0.3). Tripped at conf ≥ 0.5 (strict: ≥ 0.2) | ✅ 14 jailbreak artifact paths (Cydia, Sileo, Zebra, MobileSubstrate, /bin/bash…) via NSFileManager (w 0.9) · sandbox-escape write probe at /private/… (w 1.0) | — | — |
EmulatorCheck (enableEmulatorCheck) — virtual device + attached debugger (2 independent threats) | ✅ emulator: Build.HARDWARE ∈ {goldfish, ranchu}, Genymotion manufacturer, FINGERPRINT starts generic/contains /sdk_, /dev/qemu_pipe. Debugger: Debug.isDebuggerConnected() (w 1.0) + waitingForDebugger() (w 0.6) | ✅ emulator: NSProcessInfo.environment contains SIMULATOR_DEVICE_NAME / SIMULATOR_MODEL_IDENTIFIER / SIMULATOR_HOST_HOME (w 1.0). Debugger: sysctl P_TRACED deferred | ⚠️ emulator: java.vm.name ∈ {Dalvik, ART} (w 0.5 — Android-on-PC only). Debugger: -agentlib:jdwp / -Xrunjdwp / -Xdebug in RuntimeMXBean.inputArguments (w 1.0) | |
IntegrityCheck (enableIntegrityCheck) — signing cert + hook frameworks | ✅ signing cert SHA-256 vs expectedSignature (w 1.0) · signing-read failure (w 0.5) · Android Studio default debug cert (w 0.4) · installer outside trustedInstallers (w 0.3). Hook: Xposed/LSPosed/VirtualXposed/Magisk visible via one getInstalledPackages() + <queries> manifest | ⚠️ Frida artefacts (FridaGadget framework, frida-agent / frida-gadget under /usr/lib/frida/ + rootless /var/jb/usr/lib/frida/, frida-server, Cycript — w 1.0 each) + NSBundle.bundleIdentifier == nil (w 0.6). Full SecStaticCodeCheckValidity + dyld scanning deferred | — (JAR verification different threat model) | — (browser SRI different threat model) |
NetworkCheck (enableNetworkCheck) — VPN + proxy (2 independent threats, low default weights) | ✅ VPN: ConnectivityManager + TRANSPORT_VPN / missing NET_CAPABILITY_NOT_VPN (API 23+, w 1.0) · NetworkInterface tun*/utun*/ipsec*/ppp*/wg*/tap* up (w 0.8). Proxy: http(s).proxyHost (w 1.0) · socksProxyHost (w 0.9) | — (cinterop for getifaddrs() / NEVPNManager deferred) | ✅ VPN: NetworkInterface scan for same prefixes (w 1.0). Proxy: http/https/socks system properties (1.0 / 1.0 / 0.9) + ProxySelector.getDefault().select() non-DIRECT (w 0.8) | — (needs server-side IP correlation) |
RemoteCheck (enableRemoteCheck) — remote-control apps + live screen capture | ✅ PackageManager scan against 16 known remote-control pkgs (AnyDesk, TeamViewer, RustDesk, Chrome Remote Desktop…) with <queries> manifest · AccessibilityManager running-services scan for known remote services. Fires RemoteControlInstalled | ⚠️ UIScreen.mainScreen.captured for live screen mirror/record only (fires ScreenBeingCaptured). Sandbox blocks app enumeration | ✅ ProcessHandle.allProcesses() basename scan for known remote binaries (vncserver, x11vnc, teamviewerd, rustdesk, anydesk, screensharingd on macOS). Fires RemoteControlInstalled | — (sandbox) |
SurveillanceCheck (enableSurveillanceCheck) — apps that can spy on or interfere with other apps | ✅ 4 categories: AccessibilityManager enabled-services (non-system) → AccessibilityAbuse · Settings.Secure.ENABLED_NOTIFICATION_LISTENERS (non-system) → NotificationListener · DevicePolicyManager.getActiveAdmins() (non-system) → DeviceAdminActive · Settings.Secure.DEFAULT_INPUT_METHOD outside allow-list → SuspiciousIme | — (sandbox — jailbreak threat already implies elevated surveillance risk) | ⚠️ ProcessHandle basename scan against automation tools (pyautogui, appium, selenium, sikuli, autohotkey, keyclick) → AutomationToolRunning, and debuggers (gdb, lldb, strace, dtruss, frida-server) → DebuggerAttachedElsewhere | — (sandbox) |
| App | CI | Run locally |
|---|
sample/shared | linked via CI builds below | — (library) |
sample/android | ✅ assembleDebug | ./gradlew :sample:android:installDebug (device or emulator), or open in Android Studio |
sample/desktop | ✅ jar | ./gradlew :sample:desktop:run |
sample/web | ✅ jsBrowserProductionWebpack (artefact uploaded) | ./gradlew :sample:web:jsBrowserDevelopmentRun → http://localhost:8080 |
sample/ios | ✅ xcodegen + xcodebuild on Simulator | cd sample/ios && xcodegen && open DeviceGuardSample.xcodeproj; then Run in Xcode |
| Platform | Environment | Expected primary threats | Status |
|---|
| Android | Stock Pixel / Samsung / Xiaomi | SAFE or LOW | ☐ |
| Android | AOSP emulator (Google APIs image) | Root, Emulator | ☐ |
| Android | Google Play emulator image | Emulator only | ☐ |
| Android | Rooted device + Magisk (no hide) | Root, HookFramework if Zygisk modules | ☐ |
| Android | Device on corporate VPN | VpnActive | ☐ |
| Android | Device with http.proxyHost set | ProxyActive | ☐ |
| Android | Re-signed APK, wrong expected signature | SignatureMismatch | ☐ |
| iOS | Stock iPhone | SAFE | ☐ |
| iOS | iOS Simulator | Emulator | ☐ |
| iOS | Jailbroken iPhone (palera1n / Dopamine) | Jailbreak, possibly HookFramework | ☐ |
| JVM / Desktop | Plain launch | SAFE | ☐ |
| JVM / Desktop | Launched under IntelliJ Debug (JDWP) | DebuggerAttached | ☐ |
| JVM / Desktop | -Dhttp.proxyHost=proxy.example.com | ProxyActive | ☐ |
| JVM / Desktop | Connected to VPN (utun / tun interface up) | VpnActive | ☐ |
| JS / Web | Chrome, normal session | SAFE | ☐ |
| JS / Web | Chrome with DevTools open | possibly DebuggerAttached | ☐ |
| JS / Web | Selenium / Playwright automation | Emulator (navigator.webdriver) | ☐ |
| Module | Status | Purpose |
|---|
deviceguard-core | ✅ available | Public API, models, orchestrator |
deviceguard-fingerprint | ✅ available | Stable cross-platform device ID |
deviceguard-rootcheck | ✅ available | Root / Jailbreak detection |
deviceguard-emulator | ✅ available | Emulator / Debugger detection |
deviceguard-integrity | ✅ available | App tampering & hook detection |
deviceguard-network | ✅ available | VPN / Proxy / Tor inspection |
deviceguard-remote | ✅ available | Remote-control apps & screen-capture detection |
deviceguard-surveillance | ✅ available | Accessibility / notification-listener / device-admin / IME abuse + automation-tool detection |
deviceguard-bom | ✅ available | Bill of Materials for version alignment |
| Platform | Minimum | Notes |
|---|
| Android | API 21 (Lollipop) | full detector coverage — see matrix above |
| iOS | 13.0 | Fingerprint / RootCheck (jailbreak) / EmulatorCheck / IntegrityCheck / RemoteCheck (screen-capture only). Network deferred (cinterop). Surveillance N/A (sandbox) |
| JVM / Desktop | JDK 17 | Fingerprint / EmulatorCheck (JDWP) / NetworkCheck / RemoteCheck / SurveillanceCheck (best-effort via ProcessHandle). Root / Integrity N/A |
| JS / Web | ES2020 browser | Fingerprint (best-effort) / EmulatorCheck (webdriver). Root / Integrity / Network / Remote / Surveillance all N/A — sandbox |
Build.MANUFACTURER/BRAND/MODEL/DEVICE/PRODUCT/HARDWARE, SDK_INT,
SUPPORTED_ABIS, Settings.Secure.ANDROID_ID, screen density and resolution, locale, timezone.UIDevice.systemName/systemVersion/model, identifierForVendor, screen scale and
bounds, locale, timezone.os.name/version/arch, java.vendor/version, locale, timezone, and a SHA-256
digest of the first non-loopback MAC address (the raw bytes never leave the detector).navigator.userAgent/platform/language/hardwareConcurrency, screen resolution and
color depth, timezone and UTC offset.su/Superuser/Magisk binary paths (weight 1.0); a single
PackageManager.getInstalledPackages() scan matched against 12 root-tooling package names
(weight 0.9); Build.TAGS contains test-keys (weight 0.3). The module's manifest
pre-declares the package list under <queries> so it works on Android 11+ without
QUERY_ALL_PACKAGES./bin/bash, apt cache, etc.) via NSFileManager.fileExistsAtPath (weight 0.9); a
sandbox-escape write probe at /private/DeviceGuardProbe-<uuid>.txt with try/finally
cleanup (weight 1.0).DetectionResult.NotApplicable.Build.HARDWARE ∈ {goldfish, ranchu}, Build.MANUFACTURER
contains Genymotion, Build.FINGERPRINT starts with generic or contains /sdk_,
Build.PRODUCT contains sdk/emulator, /dev/qemu_pipe or /dev/socket/qemud
exists. Debugger: android.os.Debug.isDebuggerConnected() (weight 1.0),
waitingForDebugger() (weight 0.6).NSProcessInfo.processInfo.environment contains
SIMULATOR_DEVICE_NAME / SIMULATOR_MODEL_IDENTIFIER / SIMULATOR_HOST_HOME
(weight 1.0 each). Debugger: sysctl P_TRACED probe deferred to a follow-up.java.vm.name ∈ {Dalvik, ART} (weight 0.5, weak signal for
Android-on-PC runtimes). Debugger: RuntimeMXBean.inputArguments carries
-agentlib:jdwp, -Xrunjdwp, or -Xdebug (weight 1.0).navigator.webdriver === true for WebDriver/Selenium and most
headless browsers (weight 0.9). Debugger: window.outerHeight == 0 DevTools heuristic
(weight 0.5). Node callers — where window is absent — see an empty outcome.expectedSignature (weight 1.0); signing
read failure (weight 0.5, fires when PackageManager can't read the signing info);
Android Studio's default debug cert SHA-1 (weight 0.4, intentionally weak — swappable
by the build system); installer outside trustedInstallers (weight 0.3, skipped if the
set is empty). Hook: Xposed installer, LSPosed manager, Virtual-Exposed, or Magisk is
visible via a single getInstalledPackages() call (weight 1.0). The manifest declares
those packages under <queries> so detection works on Android 11+ without
QUERY_ALL_PACKAGES.frida-agent / frida-gadget dylibs under
/usr/lib/frida/ and /var/jb/usr/lib/frida/, frida-server, Cycript (weight 1.0
each). Signature stream: NSBundle.mainBundle.bundleIdentifier == nil (weight 0.6).
Full SecStaticCodeCheckValidity, in-memory _dyld_image_count scanning, and
embedded.mobileprovision inspection are deferred.signatureMismatchhookFrameworkDetectedsignatureCheckRunsignatureCheckRun before treating signatureMismatch == false as "signature is
valid"integritycheck.signature_check_runexpectedSignaturekeytoolAB:CD:EF:…ConnectivityManager.getActiveNetwork() +
getNetworkCapabilities() reporting TRANSPORT_VPN or lacking
NET_CAPABILITY_NOT_VPN (weight 1.0, API 23+ only; API 21/22 falls back to the
interface scan); NetworkInterface named tun*/utun*/ipsec*/ppp*/wg*/tap*
while up (weight 0.8). Proxy: http.proxyHost / https.proxyHost (weight 1.0 each);
socksProxyHost (weight 0.9). Module manifest declares ACCESS_NETWORK_STATE.NetworkInterface.getNetworkInterfaces() scan for the same
prefixes (weight 1.0). Proxy: http/https/socks system properties (1.0 / 1.0 / 0.9)
plus ProxySelector.getDefault().select(…) returning a non-DIRECT proxy (weight 0.8).NotApplicable pending a dedicated cinterop for getifaddrs(). The posix
bindings shipped by default Kotlin/Native don't expose it, and the
SCNetworkInterface / NEVPNManager alternatives need more surface. Deferred to a
follow-up that won't change the public API.NotApplicable. Reliable in-browser VPN/proxy detection needs
server-side IP correlation.commonTestjvmTest source sets exercise the desktop probes directly:
fingerprint signals (os.*, jvm.*, net.mac_hash shape), proxy detection via
System.getProperty + ProxySelector, and the NotApplicable bypasses for rootcheck
and integrity on desktop. Android-instrumented, iOS-device, and JS browser tests remain
follow-up work.⚠️ emulator: navigator.webdriver === true for Selenium/Playwright (w 0.9). Debugger: window.outerHeight == 0 DevTools heuristic (w 0.5) |