android-sdd 1.0.0

package/skills/Security/Proguard/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: proguard
+description: >
+  ProGuard rules reference for Android apps.
+  Load this skill when writing or debugging -keep rules, understanding
+  ProGuard rule syntax, maintaining proguard-rules.pro, or resolving
+  runtime crashes caused by missing keep rules.
+---
+
+# ProGuard
+
+## Overview
+ProGuard is the rule language used by both the legacy ProGuard tool and its successor R8. In modern Android projects, you write ProGuard-syntax rules in `proguard-rules.pro`, and R8 consumes them. Understanding the rule syntax is essential for preventing runtime crashes in release builds.
+
+---
+
+## Core Principles
+
+- ProGuard rules **whitelist** — everything is removed unless kept
+- Rules are **additive** — you cannot un-keep something kept by another rule
+- Prefer **specific rules** over broad ones — broad rules defeat shrinking
+- Rules affect **shrinking, obfuscation, and optimization** independently
+- Test on a real device with a release/minified build before shipping
+
+---
+
+## Rule Syntax Reference
+
+```proguard
+# Keep a class and all its members
+-keep class com.example.MyClass { *; }
+
+# Keep a class name only (members may still be removed/renamed)
+-keep class com.example.MyClass
+
+# Keep members but allow class renaming
+-keepclassmembers class com.example.MyClass {
+    public void myMethod();
+    private String myField;
+}
+
+# Keep class if it has certain members (conditional keep)
+-keepclasseswithmembers class * {
+    public <init>(android.content.Context);
+}
+
+# Keep class name if it has certain members (class name kept, members may be renamed)
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# Keep attributes (metadata)
+-keepattributes *Annotation*
+-keepattributes Signature
+-keepattributes SourceFile,LineNumberTable
+-keepattributes Exceptions
+
+# Suppress warnings (use sparingly)
+-dontwarn com.example.third.party.**
+
+# Suppress notes
+-dontnote com.example.third.party.**
+
+# Rename source file attribute (for stack trace clarity)
+-renamesourcefileattribute SourceFile
+```
+
+---
+
+## Wildcards
+
+```proguard
+# * — matches any single package component or partial name (not dots)
+-keep class com.example.*.Model { *; }    # matches com.example.user.Model
+                                           # NOT com.example.user.detail.Model
+
+# ** — matches any number of package components (including dots)
+-keep class com.example.**.Model { *; }   # matches both
+
+# *** — matches any type (primitive or object)
+# % — matches any primitive type
+# <fields> — all fields
+# <methods> — all methods
+# <init> — constructors
+```
+
+---
+
+## Common Rules by Library
+
+```proguard
+# ── Retrofit ──────────────────────────────────────────────────────────────
+-keepattributes Signature
+-keepattributes Exceptions
+-keep interface * {
+    @retrofit2.http.* <methods>;
+}
+-dontwarn retrofit2.**
+
+# ── OkHttp ────────────────────────────────────────────────────────────────
+-dontwarn okhttp3.**
+-dontwarn okio.**
+-keep class okhttp3.** { *; }
+-keep interface okhttp3.** { *; }
+
+# ── Gson ──────────────────────────────────────────────────────────────────
+-keepclassmembers class * {
+    @com.google.gson.annotations.SerializedName <fields>;
+}
+-keep class com.example.app.data.remote.dto.** { *; }
+
+# ── kotlinx.serialization ─────────────────────────────────────────────────
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+-keepclassmembers class kotlinx.serialization.json.** {
+    *** Companion;
+}
+
+# ── Room ──────────────────────────────────────────────────────────────────
+-keep class * extends androidx.room.RoomDatabase
+-keep @androidx.room.Entity class * { *; }
+-keep @androidx.room.Dao interface * { *; }
+
+# ── Hilt / Dagger ─────────────────────────────────────────────────────────
+-keep class dagger.** { *; }
+-keep class javax.inject.** { *; }
+-keep @dagger.hilt.android.HiltAndroidApp class *
+-keep @dagger.hilt.android.AndroidEntryPoint class *
+-keep @dagger.hilt.InstallIn class *
+
+# ── Parcelable ────────────────────────────────────────────────────────────
+-keep class * implements android.os.Parcelable {
+    public static final android.os.Parcelable$Creator *;
+}
+
+# ── Enum ──────────────────────────────────────────────────────────────────
+-keepclassmembers enum * {
+    public static **[] values();
+    public static ** valueOf(java.lang.String);
+}
+
+# ── Firebase ──────────────────────────────────────────────────────────────
+-keep class com.google.firebase.** { *; }
+-keep class com.google.android.gms.** { *; }
+-dontwarn com.google.firebase.**
+
+# ── Crashlytics ───────────────────────────────────────────────────────────
+-keepattributes SourceFile,LineNumberTable
+-keep public class * extends java.lang.Exception
+```
+
+---
+
+## Diagnosing Missing Keep Rules
+
+```bash
+# Run release build and check logcat for:
+# E/AndroidRuntime: java.lang.ClassNotFoundException: com.example.MyClass
+# → Add: -keep class com.example.MyClass { *; }
+
+# E/AndroidRuntime: java.lang.NoSuchMethodException: myMethod
+# → Add: -keepclassmembers class com.example.MyClass { void myMethod(); }
+
+# Check usage.txt to see what was removed:
+# app/build/outputs/mapping/release/usage.txt
+```
+
+---
+
+## Rule Debugging
+
+```proguard
+# ✅ Print which rules were applied (outputs to build logs)
+-printconfiguration build/outputs/mapping/release/configuration.txt
+
+# ✅ Print which classes were kept
+-printseeds build/outputs/mapping/release/seeds.txt
+
+# ✅ Print which code was removed
+-printusage build/outputs/mapping/release/usage.txt
+
+# ✅ Print the mapping
+-printmapping build/outputs/mapping/release/mapping.txt
+```
+
+---
+
+## Anti-Patterns
+
+- `-keep class com.example.** { *; }` — keeps all code, no shrinking benefit
+- Writing rules without testing the release build — issues only surface at runtime
+- `-dontwarn **` — suppresses all warnings including real problems
+- Forgetting `-keepattributes Signature` — breaks Retrofit generic type resolution
+- Not keeping DTO fields with Gson — deserialized objects have null fields in release
+
+---
+
+## Related Skills
+- `r8` — R8 configuration and full mode
+- `obfuscation` — obfuscation strategy and when to apply it
+- `build-variant` — applying different rules per build type
+- `gradle` — build configuration

package/skills/Security/R8/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: r8
+description: >
+  R8 compiler for Android app shrinking, obfuscation, and optimization.
+  Load this skill when configuring R8 rules, understanding how R8 differs
+  from ProGuard, enabling full mode, troubleshooting R8-related build or
+  runtime issues, or optimizing APK/AAB size with R8.
+---
+
+# R8
+
+## Overview
+R8 is Android's default code shrinker, obfuscator, and optimizer — replacing ProGuard since AGP 3.4. R8 runs as part of the build pipeline and performs three tasks in one pass: **shrinking** (removes unused code), **obfuscation** (renames identifiers), and **optimization** (inlines, removes dead branches, optimizes bytecode).
+
+---
+
+## Core Principles
+
+- R8 is enabled via `isMinifyEnabled = true` — not a separate tool invocation
+- R8 Full Mode (`-fullmode`) is more aggressive — requires more explicit keep rules
+- R8 consumes the same `-keep` rules as ProGuard — existing rules work
+- R8 produces a `mapping.txt` — required for deobfuscating crash stack traces
+- Test release builds — R8 transformations can break reflection-heavy code
+
+---
+
+## Build Configuration
+
+```kotlin
+// ✅ Standard R8 setup
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true    // removes unused resources (requires minify)
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),  // base rules
+                "proguard-rules.pro"    // app-specific rules
+            )
+        }
+    }
+
+    // ✅ Enable R8 full mode for maximum shrinking
+    // Add to gradle.properties:
+    // android.enableR8.fullMode=true
+}
+```
+
+---
+
+## R8 vs ProGuard
+
+| Feature | ProGuard | R8 |
+|---|---|---|
+| Shrinking | ✅ | ✅ |
+| Obfuscation | ✅ | ✅ |
+| Optimization | Basic | Advanced (inlining, constant propagation) |
+| Build speed | Slower | Faster (single pass) |
+| Kotlin support | Limited | Full |
+| Full mode | ❌ | ✅ (opt-in) |
+| Default since | AGP < 3.4 | AGP 3.4+ |
+
+---
+
+## R8 Full Mode
+
+```properties
+# gradle.properties — enables more aggressive shrinking
+android.enableR8.fullMode=true
+```
+
+```proguard
+# Full mode removes default constructors — keep them explicitly if needed
+-keepclassmembers class com.example.app.data.remote.dto.** {
+    <init>();   # keep no-arg constructor for deserialization
+    <fields>;
+}
+
+# Full mode is stricter about interface default methods
+-keep interface com.example.app.domain.repository.** { *; }
+```
+
+---
+
+## Essential Keep Rules
+
+```proguard
+# ============================================================
+# Reflection — anything accessed via reflection must be kept
+# ============================================================
+-keepclassmembers class * {
+    @com.google.gson.annotations.SerializedName <fields>;
+}
+
+# ============================================================
+# kotlinx.serialization
+# ============================================================
+-keepattributes *Annotation*, InnerClasses
+-keepclasseswithmembers class * {
+    @kotlinx.serialization.Serializable *;
+}
+
+# ============================================================
+# Preserve line numbers for crash reports
+# ============================================================
+-keepattributes SourceFile,LineNumberTable
+-renamesourcefileattribute SourceFile
+
+# ============================================================
+# Keep generic signatures (needed by Retrofit)
+# ============================================================
+-keepattributes Signature
+
+# ============================================================
+# Native methods
+# ============================================================
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# ============================================================
+# Custom views (used in XML layouts)
+# ============================================================
+-keep public class * extends android.view.View {
+    public <init>(android.content.Context);
+    public <init>(android.content.Context, android.util.AttributeSet);
+    public <init>(android.content.Context, android.util.AttributeSet, int);
+}
+
+# ============================================================
+# Suppress warnings for known-safe libraries
+# ============================================================
+-dontwarn kotlin.reflect.jvm.internal.**
+-dontwarn org.slf4j.**
+```
+
+---
+
+## R8 Optimization Examples
+
+```kotlin
+// R8 inlines small functions — no performance penalty for utility wrappers
+// Before optimization:
+fun isValidEmail(email: String) = email.contains("@")
+
+// R8 may inline this at call sites:
+if (isValidEmail(input)) { ... }
+// →  if (input.contains("@")) { ... }
+
+// R8 removes unreachable code:
+if (BuildConfig.DEBUG) {
+    Log.d(TAG, "Debug only")   // removed entirely in release build
+}
+```
+
+---
+
+## Checking What R8 Removed
+
+```bash
+# ✅ Check which classes/methods were removed
+# build/outputs/mapping/release/usage.txt — lists removed code
+
+# ✅ Check final APK contents
+# Android Studio → Build → Analyze APK
+
+# ✅ R8 produces these files in build/outputs/mapping/release/:
+# mapping.txt     — obfuscated → original name mapping
+# seeds.txt       — classes/members that matched -keep rules
+# usage.txt       — code removed by shrinking
+# configuration.txt — merged ProGuard rules applied
+```
+
+---
+
+## Library AAR Keep Rules
+
+```proguard
+# ✅ If publishing an AAR library, define consumer rules
+# In library module: src/main/proguard-consumer-rules.pro
+# These are automatically applied to apps that use the library
+
+-keep public class com.example.mylibrary.PublicApi { *; }
+-keep public interface com.example.mylibrary.Callback { *; }
+```
+
+```kotlin
+// ✅ Reference consumer rules in library build.gradle.kts
+android {
+    defaultConfig {
+        consumerProguardFiles("proguard-consumer-rules.pro")
+    }
+}
+```
+
+---
+
+## Troubleshooting Checklist
+
+```
+R8 build succeeds but app crashes at runtime:
+  1. Check logcat for ClassNotFoundException, NoSuchMethodException
+  2. Add -keep rule for the missing class/method
+  3. Rebuild and test again
+
+R8 build fails:
+  1. Check build output for "R8: error" messages
+  2. Look for conflicting keep rules
+  3. Try disabling full mode temporarily
+
+APK too large after R8:
+  1. Enable isShrinkResources = true
+  2. Check if -keep rules are too broad
+  3. Use Android Studio APK Analyzer to identify large classes
+```
+
+---
+
+## Anti-Patterns
+
+- `isMinifyEnabled = false` in release — ships unoptimized, unobfuscated code
+- Broad `-keep com.example.app.** { *; }` rules — keeps entire package, defeats shrinking
+- Not saving `mapping.txt` from each release — crashes become undecodable
+- Only testing debug builds — R8 transformations only apply in release
+- Using ProGuard when R8 is available — R8 is faster and more capable
+
+---
+
+## Related Skills
+- `obfuscation` — obfuscation rules and strategy
+- `proguard` — ProGuard rules reference for older setups
+- `build-variant` — managing release/debug build types
+- `gradle` — build configuration
+- `reverse-engineering-resistance` — combining R8 with other protections

package/skills/Security/Reverse Engineering Resistance/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: reverse-engineering-resistance
+description: >
+  Reverse engineering resistance for Android apps.
+  Load this skill when designing a defense-in-depth security strategy,
+  combining multiple anti-tampering measures, protecting sensitive algorithms,
+  implementing APK integrity checks, or hardening an app against static analysis.
+---
+
+# Reverse Engineering Resistance
+
+## Overview
+Reverse engineering resistance is not a single technique — it's a layered strategy. Attackers use static analysis (decompiling the APK), dynamic analysis (runtime hooks, Frida), and debugging. No single measure stops a determined attacker, but raising the cost and complexity of an attack is a meaningful defense.
+
+---
+
+## Core Principles
+
+- **Defense in depth** — layer multiple techniques; no single measure is sufficient
+- **Detect and respond** — detect analysis attempts and fail-secure
+- **Move secrets server-side** — anything in the APK can be extracted
+- **Obfuscate detection logic** — easy-to-read detection code is easy to bypass
+- **Server-side integrity** — Play Integrity API provides the strongest client attestation
+
+---
+
+## Defense Layers
+
+```
+Layer 1: Build-time protection
+  → R8 obfuscation + shrinking
+  → String encryption
+  → Resource obfuscation
+
+Layer 2: Runtime integrity checks
+  → APK signature verification
+  → Debugger detection
+  → Emulator detection
+  → Root detection
+  → Hook detection (Xposed, Frida)
+
+Layer 3: Server-side attestation
+  → Play Integrity API
+  → Certificate pinning
+  → Short-lived tokens
+```
+
+---
+
+## APK Signature Verification
+
+```kotlin
+// ✅ Verify the app is signed with the expected certificate
+class ApkIntegrityChecker @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    // Get your signing cert hash:
+    // keytool -printcert -file CERT.RSA | grep SHA256
+    private val expectedCertHash = "AA:BB:CC:DD:..."   // replace with actual hash
+
+    fun isSignatureValid(): Boolean {
+        return try {
+            val packageInfo = context.packageManager.getPackageInfo(
+                context.packageName,
+                PackageManager.GET_SIGNING_CERTIFICATES
+            )
+            val signingInfo = packageInfo.signingInfo
+            val signatures = signingInfo?.apkContentsSigners ?: return false
+
+            signatures.any { signature ->
+                val digest = MessageDigest.getInstance("SHA-256")
+                val certHash = digest.digest(signature.toByteArray())
+                val hashHex = certHash.joinToString(":") { "%02X".format(it) }
+                hashHex == expectedCertHash
+            }
+        } catch (e: Exception) {
+            false
+        }
+    }
+}
+```
+
+---
+
+## Debugger Detection
+
+```kotlin
+// ✅ Detect if a debugger is attached
+object DebuggerDetector {
+    fun isDebuggerAttached(): Boolean =
+        android.os.Debug.isDebuggerConnected() ||
+        android.os.Debug.waitingForDebugger()
+
+    fun isDebuggableBuild(): Boolean =
+        BuildConfig.DEBUG ||
+        (android.os.Debug.isDebuggerConnected())
+
+    // ✅ Check android:debuggable in manifest at runtime
+    fun isManifestDebuggable(context: Context): Boolean {
+        val appInfo = context.applicationInfo
+        return (appInfo.flags and android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE) != 0
+    }
+}
+```
+
+---
+
+## Emulator Detection
+
+```kotlin
+// ✅ Detect common Android emulators
+object EmulatorDetector {
+    fun isEmulator(): Boolean =
+        checkBuildProperties() || checkEmulatorFiles() || checkTelephony()
+
+    private fun checkBuildProperties(): Boolean {
+        val indicators = listOf(
+            Build.FINGERPRINT.startsWith("generic"),
+            Build.FINGERPRINT.startsWith("unknown"),
+            Build.MODEL.contains("google_sdk", ignoreCase = true),
+            Build.MODEL.contains("Emulator", ignoreCase = true),
+            Build.MODEL.contains("Android SDK built for x86", ignoreCase = true),
+            Build.MANUFACTURER.contains("Genymotion", ignoreCase = true),
+            Build.HARDWARE.contains("goldfish", ignoreCase = true),
+            Build.HARDWARE.contains("ranchu", ignoreCase = true),
+            Build.PRODUCT.contains("sdk_gphone", ignoreCase = true),
+            Build.PRODUCT.contains("vbox86p", ignoreCase = true)
+        )
+        return indicators.any { it }
+    }
+
+    private fun checkEmulatorFiles(): Boolean {
+        val emulatorFiles = listOf(
+            "/dev/socket/qemud",
+            "/dev/qemu_pipe",
+            "/system/lib/libc_malloc_debug_qemu.so",
+            "/sys/qemu_trace",
+            "/system/bin/qemu-props"
+        )
+        return emulatorFiles.any { File(it).exists() }
+    }
+
+    private fun checkTelephony(): Boolean {
+        // IMEI "000000000000000" is used by many emulators
+        return Build.SERIAL == "unknown" || Build.SERIAL == "0"
+    }
+}
+```
+
+---
+
+## String Obfuscation Pattern
+
+```kotlin
+// ✅ Don't store sensitive strings as plain constants
+// ❌ Bad — visible in decompiled APK
+private const val API_SECRET = "my_secret_key_12345"
+
+// ✅ Better — obfuscate with simple XOR (raise the bar, not a crypto solution)
+object StringObfuscator {
+    private val key = byteArrayOf(0x4A, 0x3F, 0x2E, 0x1D, 0x5C)
+
+    fun decode(encoded: ByteArray): String {
+        return String(ByteArray(encoded.size) { i ->
+            (encoded[i].toInt() xor key[i % key.size].toInt()).toByte()
+        })
+    }
+}
+
+// ✅ Best — keep secrets server-side entirely; fetch at runtime with auth
+```
+
+---
+
+## Tamper Response Strategy
+
+```kotlin
+// ✅ Consolidated tamper check at app startup
+class TamperDetectionService @Inject constructor(
+    private val apkIntegrityChecker: ApkIntegrityChecker,
+    private val rootDetector: RootDetector,
+    private val hookDetector: HookDetector,
+    private val fridaDetector: FridaDetector
+) {
+    sealed interface TamperStatus {
+        data object Clean : TamperStatus
+        data class Compromised(val reasons: List<String>) : TamperStatus
+    }
+
+    suspend fun evaluate(): TamperStatus = withContext(Dispatchers.IO) {
+        val reasons = mutableListOf<String>()
+
+        if (!apkIntegrityChecker.isSignatureValid()) reasons.add("invalid_signature")
+        if (DebuggerDetector.isDebuggerAttached()) reasons.add("debugger_attached")
+        if (EmulatorDetector.isEmulator()) reasons.add("emulator")
+        if (rootDetector.check().isRooted) reasons.add("rooted")
+        if (hookDetector.check().isHooked) reasons.add("hooked")
+        if (fridaDetector.check().isDetected) reasons.add("frida")
+
+        if (reasons.isEmpty()) TamperStatus.Clean
+        else TamperStatus.Compromised(reasons)
+    }
+}
+
+// ✅ Response options per risk level
+fun respondToTamper(status: TamperStatus, sensitivity: AppSensitivity) {
+    if (status is TamperStatus.Compromised) {
+        when (sensitivity) {
+            AppSensitivity.HIGH -> {
+                // Banking, health: terminate
+                showTamperDialog()
+                finishAndRemoveTask()
+            }
+            AppSensitivity.MEDIUM -> {
+                // Restrict sensitive features only
+                disableSensitiveFeatures()
+                logThreatToServer(status.reasons)
+            }
+            AppSensitivity.LOW -> {
+                // Log silently
+                logThreatToServer(status.reasons)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Play Integrity API (Strongest Attestation)
+
+```kotlin
+// ✅ Use Play Integrity for server-verified device integrity
+// The server receives and verifies a signed token from Google
+// Token contains: appIntegrity, deviceIntegrity, accountDetails
+
+suspend fun requestIntegrityToken(context: Context, nonce: String): Result<String> =
+    runCatching {
+        val manager = IntegrityManagerFactory.create(context)
+        val request = IntegrityTokenRequest.builder().setNonce(nonce).build()
+        manager.requestIntegrityToken(request).await().token()
+    }
+
+// Server checks:
+// deviceRecognitionVerdict: MEETS_STRONG_INTEGRITY → real unmodified device
+// appIntegrityVerdict: PLAY_RECOGNIZED → APK matches Play store version
+```
+
+---
+
+## Anti-Patterns
+
+- Relying on obfuscation alone — determined attackers can re-analyze obfuscated code
+- Storing API secrets in APK — use server-side secrets with authenticated access
+- Android `debuggable=true` in release builds — allows trivial debugging and memory inspection
+- Single-point detection — check at startup only; also check before each sensitive operation
+- No server-side validation — all client-side checks are bypassable given enough effort
+
+---
+
+## Related Skills
+- `root-detection` — rooted device detection
+- `hook-detection` — Xposed/LSPosed detection
+- `frida-detection` — Frida dynamic instrumentation detection
+- `obfuscation` — R8 obfuscation configuration
+- `certificate-pinning` — network-level protection
+- `cryptography` — protecting sensitive data