android-sdd 1.0.0

package/skills/Security/Root Detection/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: root-detection
+description: >
+  Root detection for Android security hardening.
+  Load this skill when detecting rooted devices, implementing multi-signal
+  root checks, deciding how to respond to rooted devices, or combining
+  root detection with other integrity checks.
+---
+
+# Root Detection
+
+## Overview
+Root detection identifies devices where the Android security model has been compromised. A rooted device can bypass app-level protections, read encrypted storage, hook function calls, and tamper with app behavior. Root detection is one layer in a defense-in-depth strategy — no single check is foolproof.
+
+---
+
+## Core Principles
+
+- **Multiple signals** — no single check is reliable; combine several
+- **Fail-secure** — if detection is uncertain, treat as rooted in high-security contexts
+- **Graceful degradation** — decide per-feature whether to block, warn, or restrict
+- **Obfuscate detection logic** — easy-to-read detection code is easy to bypass
+- **Server-side validation** — combine with Play Integrity API for stronger guarantees
+
+---
+
+## Multi-Signal Root Detection
+
+```kotlin
+class RootDetector @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    data class RootCheckResult(
+        val isRooted: Boolean,
+        val signals: List<String>   // which signals triggered
+    )
+
+    fun check(): RootCheckResult {
+        val signals = mutableListOf<String>()
+
+        if (checkSuBinary()) signals.add("su_binary")
+        if (checkRootApps()) signals.add("root_apps")
+        if (checkDangerousProps()) signals.add("dangerous_props")
+        if (checkRwPaths()) signals.add("rw_system_paths")
+        if (checkTestKeys()) signals.add("test_keys")
+        if (checkMagiskFiles()) signals.add("magisk_files")
+
+        return RootCheckResult(
+            isRooted = signals.isNotEmpty(),
+            signals = signals
+        )
+    }
+
+    // ✅ Check for su binary in common locations
+    private fun checkSuBinary(): Boolean {
+        val paths = listOf(
+            "/system/bin/su", "/system/xbin/su", "/sbin/su",
+            "/system/su", "/system/bin/.ext/.su", "/system/usr/we-need-root/su-backup",
+            "/data/local/su", "/data/local/bin/su", "/data/local/xbin/su"
+        )
+        return paths.any { File(it).exists() }
+    }
+
+    // ✅ Check for known root management apps
+    private fun checkRootApps(): Boolean {
+        val rootPackages = listOf(
+            "com.topjohnwu.magisk",
+            "com.noshufou.android.su",
+            "com.koushikdutta.superuser",
+            "eu.chainfire.supersu",
+            "com.kingroot.kinguser",
+            "com.kingo.root",
+            "com.smedialink.oneclickroot"
+        )
+        return rootPackages.any { pkg ->
+            try {
+                context.packageManager.getPackageInfo(pkg, 0)
+                true
+            } catch (e: PackageManager.NameNotFoundException) {
+                false
+            }
+        }
+    }
+
+    // ✅ Check dangerous build properties
+    private fun checkDangerousProps(): Boolean {
+        val dangerousProps = mapOf(
+            "ro.debuggable" to "1",
+            "ro.secure" to "0",
+            "ro.build.type" to "eng"
+        )
+        return dangerousProps.any { (prop, dangerousValue) ->
+            readSystemProperty(prop) == dangerousValue
+        }
+    }
+
+    // ✅ Check if /system is writable (should always be read-only)
+    private fun checkRwPaths(): Boolean {
+        val rwPaths = listOf("/system", "/system/bin", "/system/sbin", "/system/xbin", "/vendor/bin")
+        return rwPaths.any { path ->
+            try {
+                val file = File(path)
+                file.exists() && file.canWrite()
+            } catch (e: Exception) {
+                false
+            }
+        }
+    }
+
+    // ✅ Check for test-keys build (non-official signing)
+    private fun checkTestKeys(): Boolean {
+        val buildTags = Build.TAGS
+        return buildTags != null && buildTags.contains("test-keys")
+    }
+
+    // ✅ Check for Magisk-specific files
+    private fun checkMagiskFiles(): Boolean {
+        val magiskPaths = listOf(
+            "/sbin/.magisk", "/sbin/.core/mirror",
+            "/sbin/.core/img", "/data/adb/magisk"
+        )
+        return magiskPaths.any { File(it).exists() }
+    }
+
+    private fun readSystemProperty(name: String): String? = try {
+        val process = Runtime.getRuntime().exec(arrayOf("getprop", name))
+        process.inputStream.bufferedReader().readLine()?.trim()
+    } catch (e: Exception) {
+        null
+    }
+}
+```
+
+---
+
+## Play Integrity API (Recommended for Production)
+
+```kotlin
+// ✅ Play Integrity API — server-side verification, harder to bypass
+class IntegrityChecker @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    suspend fun checkIntegrity(nonce: String): Result<String> = runCatching {
+        val integrityManager = IntegrityManagerFactory.create(context)
+        val request = IntegrityTokenRequest.builder()
+            .setNonce(nonce)
+            .build()
+
+        val response = integrityManager.requestIntegrityToken(request).await()
+        response.token()   // send this token to your server for verification
+    }
+}
+
+// Server verifies the token via Google Play Integrity API
+// Token contains: deviceIntegrity, appIntegrity, accountDetails
+// deviceIntegrity.deviceRecognitionVerdict includes MEETS_STRONG_INTEGRITY
+```
+
+---
+
+## Response Strategy
+
+```kotlin
+// ✅ Decide response per security level
+@HiltViewModel
+class SecurityViewModel @Inject constructor(
+    private val rootDetector: RootDetector
+) : ViewModel() {
+
+    sealed interface SecurityState {
+        data object Safe : SecurityState
+        data class Compromised(val signals: List<String>) : SecurityState
+    }
+
+    val securityState: StateFlow<SecurityState> = flow {
+        val result = rootDetector.check()
+        emit(
+            if (result.isRooted) SecurityState.Compromised(result.signals)
+            else SecurityState.Safe
+        )
+    }.stateIn(viewModelScope, SharingStarted.Eagerly, SecurityState.Safe)
+}
+
+// ✅ UI response options (choose based on app sensitivity)
+// Option 1: Block entirely (banking, health apps)
+if (securityState is SecurityState.Compromised) {
+    RootedDeviceBlockScreen()
+    return
+}
+
+// Option 2: Warn and restrict features
+if (securityState is SecurityState.Compromised) {
+    showWarning("Some features are unavailable on rooted devices")
+    disableSensitiveFeatures()
+}
+
+// Option 3: Log and monitor (lower security apps)
+if (securityState is SecurityState.Compromised) {
+    analytics.logEvent("rooted_device_detected", securityState.signals)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Relying on a single check — root tools specifically bypass known single checks
+- Blocking without user explanation — frustrates legitimate users (developers, testers)
+- Performing root check on main thread — run on IO dispatcher
+- Storing root check result in plain SharedPreferences — a rooted device can modify it
+- Skipping server-side validation for high-security operations — client checks are bypassable
+
+---
+
+## Related Skills
+- `hook-detection` — detecting Frida and Xposed hooks
+- `frida-detection` — Frida-specific detection techniques
+- `reverse-engineering-resistance` — broader anti-tampering measures
+- `obfuscation` — making detection logic harder to analyze
+- `certificate-pinning` — network-level security complement

package/skills/Security/Secure Networking/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: secure-networking
+description: >
+  Secure networking practices for Android apps.
+  Load this skill when configuring TLS, implementing certificate pinning,
+  setting up Network Security Config, handling authentication headers securely,
+  preventing cleartext traffic, or hardening OkHttp/Retrofit for production.
+---
+
+# Secure Networking
+
+## Overview
+Secure networking ensures that data in transit is protected from interception and tampering. The key concerns are: enforcing TLS, pinning certificates against MITM attacks, protecting auth credentials in requests, and preventing accidental cleartext traffic.
+
+---
+
+## Core Principles
+
+- **TLS only** — no cleartext HTTP in production; enforce via Network Security Config
+- **Certificate pinning** for high-security endpoints — prevents MITM even with compromised CAs
+- **Auth tokens in headers** — never in URL query parameters (logged by servers/proxies)
+- **Token refresh** handled transparently via OkHttp Authenticator
+- **Sensitive headers stripped** on redirects — never forward auth to different domains
+
+---
+
+## Network Security Config
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+
+    <!-- ✅ Block all cleartext traffic in production -->
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+
+    <!-- ✅ Allow cleartext only for debug builds (localhost) -->
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="system" />
+            <certificates src="user" />   <!-- allows Charles/Burp on debug -->
+        </trust-anchors>
+    </debug-overrides>
+
+</network-security-config>
+```
+
+```xml
+<!-- AndroidManifest.xml -->
+<application
+    android:networkSecurityConfig="@xml/network_security_config"
+    ...>
+```
+
+---
+
+## OkHttp Security Configuration
+
+```kotlin
+// ✅ Production OkHttpClient
+fun buildSecureOkHttpClient(
+    authInterceptor: AuthInterceptor,
+    certificatePinner: CertificatePinner? = null
+): OkHttpClient {
+    return OkHttpClient.Builder()
+        .connectTimeout(30, TimeUnit.SECONDS)
+        .readTimeout(30, TimeUnit.SECONDS)
+        .writeTimeout(30, TimeUnit.SECONDS)
+        .addInterceptor(authInterceptor)
+        .apply { certificatePinner?.let { certificatePinner(it) } }
+        .authenticator(TokenRefreshAuthenticator())
+        .build()
+}
+
+// ✅ Auth interceptor — adds token to every request
+class AuthInterceptor @Inject constructor(
+    private val securePreferences: SecurePreferences
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val token = securePreferences.authToken
+        val request = if (token != null) {
+            chain.request().newBuilder()
+                .header("Authorization", "Bearer $token")
+                .build()
+        } else {
+            chain.request()
+        }
+        return chain.proceed(request)
+    }
+}
+
+// ✅ Token refresh on 401
+class TokenRefreshAuthenticator @Inject constructor(
+    private val securePreferences: SecurePreferences,
+    private val authApi: AuthApiService
+) : Authenticator {
+    override fun authenticate(route: Route?, response: Response): Request? {
+        // Prevent infinite loops
+        if (response.request.header("Authorization") == null) return null
+        if (responseCount(response) >= 2) return null
+
+        val refreshToken = securePreferences.refreshToken ?: return null
+
+        val newToken = runBlocking {
+            authApi.refreshToken(refreshToken).getOrNull()
+        } ?: return null
+
+        securePreferences.authToken = newToken.accessToken
+        securePreferences.refreshToken = newToken.refreshToken
+
+        return response.request.newBuilder()
+            .header("Authorization", "Bearer ${newToken.accessToken}")
+            .build()
+    }
+
+    private fun responseCount(response: Response): Int {
+        var count = 1
+        var prior = response.priorResponse
+        while (prior != null) { count++; prior = prior.priorResponse }
+        return count
+    }
+}
+```
+
+---
+
+## Certificate Pinning
+
+```kotlin
+// ✅ Certificate pinning via OkHttp
+fun buildCertificatePinner(): CertificatePinner {
+    return CertificatePinner.Builder()
+        // Pin the leaf certificate + backup pin for rotation
+        .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
+        .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=") // backup
+        .build()
+}
+
+// ✅ Getting the pin value for your certificate:
+// $ openssl s_client -connect api.example.com:443 | openssl x509 -pubkey -noout |
+//   openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64
+```
+
+---
+
+## Logging Interceptor (Debug Only)
+
+```kotlin
+// ✅ Never log request bodies in release — may contain tokens or PII
+val loggingInterceptor = HttpLoggingInterceptor().apply {
+    level = if (BuildConfig.DEBUG) {
+        HttpLoggingInterceptor.Level.BODY
+    } else {
+        HttpLoggingInterceptor.Level.NONE   // ✅ no logging in production
+    }
+}
+
+// ✅ Redact sensitive headers in logs
+val loggingInterceptor = HttpLoggingInterceptor().apply {
+    level = HttpLoggingInterceptor.Level.HEADERS
+    redactHeader("Authorization")
+    redactHeader("Cookie")
+    redactHeader("Set-Cookie")
+}
+```
+
+---
+
+## Hilt Setup
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideCertificatePinner(): CertificatePinner = buildCertificatePinner()
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(
+        authInterceptor: AuthInterceptor,
+        certificatePinner: CertificatePinner
+    ): OkHttpClient = buildSecureOkHttpClient(authInterceptor, certificatePinner)
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(okHttpClient: OkHttpClient): Retrofit =
+        Retrofit.Builder()
+            .baseUrl(BuildConfig.API_BASE_URL)
+            .client(okHttpClient)
+            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+            .build()
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Passing auth tokens as URL query params — visible in server logs, browser history, proxies
+- `cleartextTrafficPermitted="true"` in production manifest — allows HTTP interception
+- Logging request/response bodies in release — leaks tokens and PII to logcat
+- No token refresh logic — forces users to re-login on every token expiry
+- Trusting user-installed CAs in production — enables corporate proxy / MITM attacks
+- Hard-coding API keys or secrets in source code — use BuildConfig from CI environment variables
+
+---
+
+## Related Skills
+- `certificate-pinning` — in-depth pinning setup and rotation strategy
+- `retrofit` — Retrofit configuration
+- `okhttp` — OkHttp interceptors and configuration
+- `authentication` — auth flow and token management
+- `network-security-config` — XML-based network security policy

package/skills/System Integration/AlarmManager/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: alarmmanager
+description: >
+  AlarmManager for time-based task scheduling in Android.
+  Load this skill when scheduling exact-time alarms, implementing
+  reminder notifications, triggering actions at a specific time,
+  or handling cases where WorkManager's timing precision is insufficient.
+---
+
+# AlarmManager
+
+## Overview
+AlarmManager schedules tasks to run at a specific time, even if the app is not running. It is the correct tool when **exact timing** matters — reminder alarms, calendar events, scheduled notifications. For flexible/deferrable work, WorkManager is preferred. Since Android 12, exact alarms require explicit permission.
+
+---
+
+## Core Principles
+
+- Use AlarmManager only when **exact timing** is required — use WorkManager for flexible scheduling
+- Request `SCHEDULE_EXACT_ALARM` or `USE_EXACT_ALARM` permission for exact alarms on Android 12+
+- Always use `PendingIntent` with `FLAG_IMMUTABLE` — required on Android 12+
+- Re-schedule alarms after device reboot via `BOOT_COMPLETED` receiver
+- Cancel alarms when they are no longer needed — they persist across app restarts
+
+---
+
+## Permissions
+
+```xml
+<!-- AndroidManifest.xml -->
+
+<!-- For exact alarms — user must grant in settings (Android 12+) -->
+<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+
+<!-- OR for specific use cases (clock, calendar apps) — always granted -->
+<uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+
+<!-- For BroadcastReceiver to survive reboot -->
+<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+```
+
+---
+
+## Scheduling an Exact Alarm
+
+```kotlin
+// ✅ Schedule exact alarm
+class ReminderScheduler @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    private val alarmManager = context.getSystemService(AlarmManager::class.java)
+
+    fun scheduleReminder(reminderId: Long, triggerAtMillis: Long) {
+        val intent = Intent(context, ReminderReceiver::class.java).apply {
+            putExtra(ReminderReceiver.EXTRA_REMINDER_ID, reminderId)
+        }
+
+        val pendingIntent = PendingIntent.getBroadcast(
+            context,
+            reminderId.toInt(),
+            intent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            if (alarmManager.canScheduleExactAlarms()) {
+                alarmManager.setExactAndAllowWhileIdle(
+                    AlarmManager.RTC_WAKEUP,
+                    triggerAtMillis,
+                    pendingIntent
+                )
+            }
+            // else: redirect user to settings
+        } else {
+            alarmManager.setExactAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP,
+                triggerAtMillis,
+                pendingIntent
+            )
+        }
+    }
+
+    fun cancelReminder(reminderId: Long) {
+        val intent = Intent(context, ReminderReceiver::class.java)
+        val pendingIntent = PendingIntent.getBroadcast(
+            context,
+            reminderId.toInt(),
+            intent,
+            PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE
+        )
+        pendingIntent?.let { alarmManager.cancel(it) }
+    }
+}
+```
+
+---
+
+## BroadcastReceiver
+
+```kotlin
+// ✅ Receiver triggered by alarm
+class ReminderReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val reminderId = intent.getLongExtra(EXTRA_REMINDER_ID, -1L)
+        if (reminderId == -1L) return
+
+        // Show notification — short work only in onReceive
+        NotificationHelper.showReminder(context, reminderId)
+    }
+
+    companion object {
+        const val EXTRA_REMINDER_ID = "reminder_id"
+    }
+}
+
+// Register in manifest
+// <receiver android:name=".ReminderReceiver" android:exported="false" />
+```
+
+---
+
+## Reschedule After Reboot
+
+```kotlin
+// ✅ Reboot receiver — reschedules all pending alarms
+class BootReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action != Intent.ACTION_BOOT_COMPLETED) return
+
+        // Reschedule all pending reminders from local DB
+        val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+        scope.launch {
+            val scheduler = ReminderScheduler(context)
+            reminderRepository.getPendingReminders().forEach { reminder ->
+                scheduler.scheduleReminder(reminder.id, reminder.triggerAt)
+            }
+        }
+    }
+}
+
+// Register in manifest
+// <receiver android:name=".BootReceiver" android:exported="true">
+//     <intent-filter>
+//         <action android:name="android.intent.action.BOOT_COMPLETED" />
+//     </intent-filter>
+// </receiver>
+```
+
+---
+
+## Directing User to Exact Alarm Settings
+
+```kotlin
+// ✅ On Android 12+ — direct user to grant exact alarm permission
+fun requestExactAlarmPermission(activity: Activity) {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        val alarmManager = activity.getSystemService(AlarmManager::class.java)
+        if (!alarmManager.canScheduleExactAlarms()) {
+            val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
+            activity.startActivity(intent)
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using AlarmManager for network sync or deferrable tasks — use WorkManager
+- Not rescheduling alarms after reboot — alarms are lost on device restart
+- Using `FLAG_MUTABLE` for PendingIntent on Android 12+ — SecurityException
+- Using `set()` instead of `setExactAndAllowWhileIdle()` — alarm delayed in Doze mode
+- Doing heavy work in `onReceive` — it runs on the main thread; delegate to a service or WorkManager
+
+---
+
+## Related Skills
+- `workmanager` — preferred for deferrable background work
+- `notification` — showing notifications from the alarm receiver
+- `broadcast-receiver` — BroadcastReceiver fundamentals
+- `background-processing` — choosing the right scheduling tool