@leejungkiin/awkit 1.1.0 → 1.1.2

package/skills/android-re-analyzer/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: android-re-analyzer
+description: >-
+  Android APK/XAPK/JAR/AAR decompiler & API extractor. Decompiles Android packages
+  using jadx and Fernflower/Vineflower, traces call flows from UI to network layer,
+  and produces structured API documentation. Complements smali-to-kotlin (rebuild)
+  by focusing on analysis & extraction.
+author: SimoneAvogadro (adapted by Antigravity Team)
+version: 1.0.0
+license: Apache-2.0
+original_repo: https://github.com/SimoneAvogadro/android-reverse-engineering-skill
+trigger: conditional
+activation_keywords:
+  - "/decompile"
+  - "decompile apk"
+  - "reverse engineer android"
+  - "extract api"
+  - "jadx"
+  - "fernflower"
+  - "vineflower"
+  - "find api endpoints"
+  - "trace call flow"
+  - "analyze apk"
+  - "dịch ngược apk"
+  - "phân tích apk"
+priority: high
+platform: android
+---
+
+# 🔍 Android RE Analyzer Skill
+
+> **Purpose:** Decompile Android APK/XAPK/JAR/AAR → Analyze structure → Extract & document HTTP APIs.
+> **Philosophy:** "Scan → Understand → Document" — analysis & extraction, not rebuilding.
+
+---
+
+## ⚠️ SCOPE CLARITY
+
+| This skill DOES | This skill DOES NOT |
+|-----------------|---------------------|
+| Decompile APK/XAPK/JAR/AAR to Java source | Rebuild app in modern Kotlin |
+| Extract HTTP API endpoints & auth patterns | Write new production code |
+| Trace call flows from UI → Network | Modify or repackage APKs |
+| Analyze app architecture & manifest | Crack/bypass security |
+| Handle obfuscated code (ProGuard/R8) | Deploy to Play Store |
+| Auto-install dependencies (jadx, etc.) | Handle iOS apps |
+
+**For rebuilding apps** → delegate to `smali-to-kotlin` skill
+**For iOS reverse engineering** → delegate to `smali-to-swift` skill
+
+---
+
+## 🎯 ROLE DEFINITION
+
+When this skill is active, the agent becomes:
+
+> **Expert Android Reverse Engineer & API Analyst**
+> - Master at navigating decompiled Java source (obfuscated or clean)
+> - Fluent in Retrofit, OkHttp, Volley API patterns
+> - Knows how to trace DI (Dagger/Hilt) bindings to find implementations
+> - Uses dual-engine decompilation for maximum accuracy
+
+---
+
+## 🛠️ PREREQUISITES
+
+Required: **Java JDK 17+** and **jadx**.
+Optional (recommended): **Vineflower** (Fernflower fork) and **dex2jar**.
+
+Check dependencies:
+```bash
+bash SKILL_ROOT/scripts/check-deps.sh
+```
+
+Install missing ones:
+```bash
+bash SKILL_ROOT/scripts/install-dep.sh <dep>
+# Available: java, jadx, vineflower, dex2jar, apktool, adb
+```
+
+> `SKILL_ROOT` = path to this skill directory (e.g. `~/.gemini/antigravity/skills/android-re-analyzer`)
+
+---
+
+## 📋 EXECUTION PIPELINE (5 Phases)
+
+> **Rule:** Complete each phase before proceeding to the next.
+> **Rule:** After each phase, summarize findings for the user.
+
+### Phase 1: Verify & Install Dependencies
+
+**Action:** Run `check-deps.sh`. If missing required deps → run `install-dep.sh <dep>`.
+Re-run check after installation. Do NOT proceed until all required deps are OK.
+
+For optional deps (vineflower, dex2jar), ask user if they want them installed.
+Recommend both for best results.
+
+---
+
+### Phase 2: Decompile
+
+**Action:** Run the decompile script:
+```bash
+bash SKILL_ROOT/scripts/decompile.sh [OPTIONS] <file>
+```
+
+Options:
+- `-o <dir>` — output directory (default: `<filename>-decompiled`)
+- `--deobf` — enable deobfuscation (for obfuscated apps)
+- `--no-res` — skip resources, code only (faster)
+- `--engine ENGINE` — `jadx` (default), `fernflower`, or `both`
+
+**Engine selection:**
+
+| Situation | Engine |
+|---|---|
+| First pass on any APK | `jadx` |
+| JAR/AAR library analysis | `fernflower` |
+| jadx output has warnings | `both` (compare) |
+| Complex lambdas/generics | `fernflower` |
+| Quick overview of large APK | `jadx --no-res` |
+
+XAPK files are auto-extracted and each APK inside is decompiled separately.
+
+---
+
+### Phase 3: Analyze Structure
+
+1. **Read `AndroidManifest.xml`:**
+   - Identify launcher Activity, Application class
+   - List Activities, Services, BroadcastReceivers, ContentProviders
+   - Note permissions (especially INTERNET, ACCESS_NETWORK_STATE)
+
+2. **Survey package structure** under `<output>/sources/`:
+   - Distinguish app code from third-party libraries
+   - Look for packages: `api`, `network`, `data`, `repository`, `service`, `retrofit`
+
+3. **Identify architecture pattern:**
+   - MVP: `Presenter` classes
+   - MVVM: `ViewModel` + `LiveData`/`StateFlow`
+   - Clean Architecture: `domain`, `data`, `presentation` packages
+
+---
+
+### Phase 4: Trace Call Flows
+
+Follow execution paths from entry points to network calls:
+
+1. Start from Activities identified in Phase 3
+2. Follow initialization: `Application.onCreate()` → HTTP client setup
+3. Trace user actions: `onClick()` → ViewModel → Repository → API service
+4. Map DI bindings (`@Module`, `@Provides`, `@Binds`, `@Inject`)
+5. Handle obfuscated code: use strings, annotations, and library APIs as anchors
+
+See `SKILL_ROOT/references/call-flow-analysis.md` for detailed grep commands and techniques.
+
+---
+
+### Phase 5: Extract & Document APIs
+
+**Action:** Run API search script:
+```bash
+bash SKILL_ROOT/scripts/find-api-calls.sh <output>/sources/
+# Targeted: --retrofit, --okhttp, --volley, --urls, --auth
+```
+
+For each endpoint, document:
+```markdown
+### `METHOD /path/to/endpoint`
+- **Source**: `com.example.api.ApiService` (file:line)
+- **Base URL**: `https://api.example.com/v1`
+- **Path params**: `id` (String)
+- **Query params**: `page` (int), `limit` (int)
+- **Headers**: `Authorization: Bearer <token>`
+- **Request body**: `LoginRequest { email: String, password: String }`
+- **Response type**: `ApiResponse<User>`
+- **Called from**: `LoginActivity → ViewModel → Repository → ApiService`
+```
+
+See `SKILL_ROOT/references/api-extraction-patterns.md` for all search patterns.
+
+---
+
+## 🔄 WORKFLOW INTEGRATION
+
+```yaml
+triggers_from:
+  - "/decompile" workflow command
+  - Keywords: "decompile", "extract api", "analyze apk", "jadx"
+
+delegates_to:
+  - smali-to-kotlin — when user wants to rebuild the app after analysis
+  - smali-to-swift — when user wants iOS equivalent
+
+works_with:
+  - memory-sync — saves analysis findings, API docs
+  - symphony-orchestrator — tracks progress per phase
+  - orchestrator — routes to this skill based on intent
+
+independent_from:
+  - brainstorm-agent
+  - ios-engineer
+```
+
+---
+
+## 🚫 ANTI-PATTERNS
+
+```yaml
+never_do:
+  - Skip dependency check → always verify tools are available first
+  - Guess at API endpoints → always use grep patterns to find them
+  - Ignore obfuscation → use --deobf and string-based tracing
+  - Assume app architecture → verify from code before tracing
+
+always_do:
+  - Run check-deps.sh before any decompilation
+  - Offer dual-engine decompilation when jadx has warnings
+  - Document every discovered API endpoint with the template
+  - Report architecture pattern before tracing call flows
+  - Ask user before proceeding to rebuild (delegate to smali-to-kotlin)
+```
+
+---
+
+## 📚 REFERENCES
+
+Detailed guides available in `SKILL_ROOT/references/`:
+- `setup-guide.md` — Installing Java, jadx, Vineflower, dex2jar
+- `jadx-usage.md` — jadx CLI options and workflows
+- `fernflower-usage.md` — Fernflower/Vineflower CLI options
+- `api-extraction-patterns.md` — Library-specific grep patterns
+- `call-flow-analysis.md` — Techniques for tracing call flows
+
+---
+
+*android-re-analyzer v1.0.0 — Based on SimoneAvogadro/android-reverse-engineering-skill (Apache 2.0)*
+*Adapted for Antigravity by Antigravity Team*

package/skills/android-re-analyzer/references/api-extraction-patterns.md

@@ -0,0 +1,119 @@
+# API Extraction Patterns
+
+Patterns and grep commands for finding HTTP API calls in decompiled Android source code.
+
+## Retrofit
+
+Retrofit is the most common HTTP client in Android apps. API endpoints are declared as annotated interface methods.
+
+### Annotations to search for
+
+```bash
+# HTTP method annotations
+grep -rn '@GET\|@POST\|@PUT\|@DELETE\|@PATCH\|@HEAD' sources/
+
+# Parameter annotations
+grep -rn '@Query\|@QueryMap\|@Path\|@Body\|@Field\|@FieldMap\|@Part\|@Header\|@HeaderMap' sources/
+
+# Headers annotation (static headers)
+grep -rn '@Headers' sources/
+
+# Base URL configuration
+grep -rn 'baseUrl\|\.baseUrl(' sources/
+```
+
+### Typical Retrofit interface
+
+```java
+public interface ApiService {
+    @GET("users/{id}")
+    Call<User> getUser(@Path("id") String userId);
+
+    @POST("auth/login")
+    @Headers({"Content-Type: application/json"})
+    Call<LoginResponse> login(@Body LoginRequest request);
+}
+```
+
+When documenting, capture: HTTP method, path, path parameters, query parameters, request body type, response type, and any static headers.
+
+## OkHttp
+
+OkHttp is often used directly or as the transport layer for Retrofit.
+
+```bash
+# Request building
+grep -rn 'Request\.Builder\|Request.Builder\|\.url(\|\.post(\|\.put(\|\.delete(\|\.patch(' sources/
+
+# URL construction
+grep -rn 'HttpUrl\|\.addQueryParameter\|\.addPathSegment' sources/
+
+# Interceptors (often add auth headers)
+grep -rn 'Interceptor\|addInterceptor\|addNetworkInterceptor\|intercept(' sources/
+
+# Response handling
+grep -rn '\.execute()\|\.enqueue(' sources/
+```
+
+## Volley
+
+```bash
+grep -rn 'StringRequest\|JsonObjectRequest\|JsonArrayRequest\|Volley\.newRequestQueue\|RequestQueue' sources/
+```
+
+Volley requests typically pass the URL as a constructor argument and override `getHeaders()` or `getParams()` for custom headers/parameters.
+
+## HttpURLConnection (legacy)
+
+```bash
+grep -rn 'HttpURLConnection\|HttpsURLConnection\|openConnection\|setRequestMethod\|setRequestProperty' sources/
+```
+
+## WebView
+
+```bash
+grep -rn 'loadUrl\|evaluateJavascript\|addJavascriptInterface\|WebViewClient\|shouldOverrideUrlLoading' sources/
+```
+
+WebView-based apps may load API endpoints via JavaScript bridges. Look for `@JavascriptInterface` annotated methods.
+
+## Hardcoded URLs and Secrets
+
+```bash
+# HTTP/HTTPS URLs
+grep -rn '"https\?://[^"]*"' sources/
+
+# API keys and tokens
+grep -rni 'api[_-]\?key\|api[_-]\?secret\|auth[_-]\?token\|bearer\|access[_-]\?token\|client[_-]\?secret' sources/
+
+# Base URL constants
+grep -rni 'BASE_URL\|API_URL\|SERVER_URL\|ENDPOINT\|API_BASE' sources/
+```
+
+## Documentation Template
+
+For each discovered API endpoint, document it using this template:
+
+```markdown
+### `METHOD /path/to/endpoint`
+
+- **Source**: `com.example.app.api.ApiService` (file:line)
+- **Base URL**: `https://api.example.com/v1`
+- **Full URL**: `https://api.example.com/v1/path/to/endpoint`
+- **Path parameters**: `id` (String)
+- **Query parameters**: `page` (int), `limit` (int)
+- **Headers**:
+  - `Authorization: Bearer <token>`
+  - `Content-Type: application/json`
+- **Request body**: `LoginRequest { email: String, password: String }`
+- **Response type**: `ApiResponse<User>`
+- **Notes**: Called from `LoginActivity.onLoginClicked()`
+```
+
+## Search Strategy
+
+1. Start with **base URL constants** — find where the API root is configured
+2. Search for **Retrofit interfaces** — they give the clearest picture of all endpoints
+3. Check **interceptors** — they reveal auth schemes and common headers
+4. Search for **hardcoded URLs** — catch any one-off API calls outside the main client
+5. Look for **WebView URLs** — some apps use hybrid web/native approaches

package/skills/android-re-analyzer/references/call-flow-analysis.md

@@ -0,0 +1,176 @@
+# Call Flow Analysis
+
+Techniques for tracing execution flows in decompiled Android applications, from entry points down to network calls.
+
+## 1. Start from AndroidManifest.xml
+
+The manifest declares all entry points. After decompilation, find it at:
+
+```
+<output-dir>/resources/AndroidManifest.xml
+```
+
+Key elements to look for:
+
+```bash
+# Activities (UI screens)
+grep -n 'android:name=.*Activity' resources/AndroidManifest.xml
+
+# Services (background work)
+grep -n 'android:name=.*Service' resources/AndroidManifest.xml
+
+# BroadcastReceivers
+grep -n '<receiver' resources/AndroidManifest.xml
+
+# ContentProviders
+grep -n '<provider' resources/AndroidManifest.xml
+
+# Launcher activity (main entry point)
+grep -A5 'MAIN' resources/AndroidManifest.xml | grep 'android:name'
+```
+
+## 2. Follow the Android Lifecycle
+
+Typical call chain from UI to network:
+
+```
+Activity.onCreate()
+  → setContentView(R.layout.activity_main)
+  → findViewById() / View Binding
+  → button.setOnClickListener()
+    → onClick()
+      → viewModel.doSomething()
+        → repository.fetchData()
+          → apiService.getEndpoint()
+            → HTTP request
+```
+
+Key lifecycle methods to search:
+
+```bash
+grep -rn 'onCreate\|onResume\|onStart\|onViewCreated' sources/
+```
+
+## 3. Identify Click Handlers
+
+User interactions trigger API calls. Common patterns:
+
+```bash
+# XML onClick
+grep -rn 'setOnClickListener\|onClick\|OnClickListener' sources/
+
+# Data Binding
+grep -rn '@BindingAdapter\|android:onClick' sources/ resources/
+
+# Navigation actions
+grep -rn 'findNavController\|NavController\|navigate(' sources/
+```
+
+## 4. Application Class Initialization
+
+The `Application` subclass initializes global singletons (HTTP clients, DI frameworks, analytics):
+
+```bash
+# Find Application subclass
+grep -rn 'extends Application\|: Application()' sources/
+
+# Check onCreate for initialization
+# Then read the class to see what gets configured at startup
+```
+
+Look for:
+- Retrofit/OkHttp client setup
+- Dagger/Hilt component initialization
+- Firebase/analytics initialization
+- Base URL configuration
+
+## 5. Dependency Injection (Dagger / Hilt)
+
+Modern Android apps use DI. Trace bindings to find implementations:
+
+```bash
+# Hilt modules
+grep -rn '@Module\|@InstallIn\|@Provides\|@Binds' sources/
+
+# Hilt entry points
+grep -rn '@HiltAndroidApp\|@AndroidEntryPoint\|@HiltViewModel' sources/
+
+# Dagger components
+grep -rn '@Component\|@Subcomponent' sources/
+
+# Injected fields
+grep -rn '@Inject' sources/
+```
+
+To trace a call flow through DI:
+1. Find where an interface is used (e.g., `ApiService` injected into a repository)
+2. Find the `@Provides` or `@Binds` method that creates the implementation
+3. Follow the implementation to the actual HTTP call
+
+## 6. Find Constants and Configuration
+
+Hardcoded values are rarely obfuscated:
+
+```bash
+# Base URLs
+grep -rni 'BASE_URL\|API_URL\|SERVER_URL\|HOST' sources/
+
+# API keys
+grep -rni 'API_KEY\|CLIENT_ID\|APP_KEY\|SECRET' sources/
+
+# BuildConfig values
+grep -rn 'BuildConfig\.' sources/
+
+# SharedPreferences keys (runtime config)
+grep -rn 'getSharedPreferences\|getString(\|putString(' sources/
+```
+
+## 7. Navigating Obfuscated Code
+
+When code is obfuscated (ProGuard/R8):
+
+### What gets obfuscated
+- Class names → `a`, `b`, `c`
+- Method names → `a()`, `b()`, `c()`
+- Field names → `f1234a`, `f1235b`
+
+### What does NOT get obfuscated
+- **String literals** — URLs, keys, error messages remain readable
+- **Android framework classes** — `Activity`, `Fragment`, `Intent` keep their names
+- **Library public APIs** — Retrofit annotations, OkHttp builders retain names
+- **AndroidManifest entries** — Activity/Service names must be real
+
+### Strategy for obfuscated code
+
+1. **Start from strings**: Search for URLs, error messages, and known constants
+2. **Start from framework classes**: Activities and Fragments are named in the manifest
+3. **Follow library calls**: Retrofit `@GET`/`@POST` annotations are readable even when the interface class name is obfuscated
+4. **Use `--deobf`**: jadx can generate readable replacement names
+5. **Cross-reference**: If `class a` calls `Retrofit.create(b.class)`, then `b` is a Retrofit service interface
+
+## 8. Tracing a Complete Call Flow: Example
+
+Goal: Find how login works in an obfuscated app.
+
+```
+1. grep for "login" in strings → find "auth/login" URL in class `c.a.b.d`
+2. Class `c.a.b.d` has @POST("auth/login") → it's a Retrofit interface
+3. grep for `c.a.b.d` usage → class `c.a.b.f` calls it (the repository)
+4. grep for `c.a.b.f` usage → class `c.a.a.g` calls it (the ViewModel)
+5. grep for `c.a.a.g` usage → `LoginActivity` has a field of this type
+6. Read LoginActivity.onCreate() → sets click listener → calls ViewModel method
+```
+
+Result: `LoginActivity → ViewModel → Repository → Retrofit @POST("auth/login")`
+
+## 9. Tools and Commands Summary
+
+| Goal | Command |
+|---|---|
+| Find entry points | `grep 'android:name' resources/AndroidManifest.xml` |
+| Find lifecycle methods | `grep -rn 'onCreate\|onResume' sources/` |
+| Find click handlers | `grep -rn 'setOnClickListener\|onClick' sources/` |
+| Find DI bindings | `grep -rn '@Provides\|@Binds\|@Inject' sources/` |
+| Find constants | `grep -rni 'BASE_URL\|API_KEY' sources/` |
+| Find usages of a class | `grep -rn 'ClassName' sources/` |
+| Follow a string | `grep -rn '"some text"' sources/` |

package/skills/android-re-analyzer/references/fernflower-usage.md

@@ -0,0 +1,115 @@
+# Fernflower / Vineflower CLI Reference
+
+Fernflower is the JetBrains analytical Java decompiler. [Vineflower](https://github.com/Vineflower/vineflower) is the actively maintained community fork with better output quality and published releases. They share the same CLI interface.
+
+## When to Use Fernflower vs jadx
+
+| Scenario | Recommended |
+|---|---|
+| APK with resources needed | jadx |
+| Standard Java JAR/library | Fernflower |
+| jadx output has warnings/errors on specific classes | Fernflower on those classes |
+| Complex lambdas, generics, streams | Fernflower |
+| Large APK (>50MB), quick overview | jadx |
+| Obfuscated Android app | jadx first, Fernflower on problem areas |
+| Both decompilers available | Use `--engine both` and compare |
+
+## Basic Usage
+
+```bash
+java -jar fernflower.jar [options] <source>... <destination>
+```
+
+- `<source>` — JAR file, class file, or directory containing class files
+- `<destination>` — output directory
+
+For a JAR input, Fernflower produces a JAR in the destination containing `.java` source files. Extract it with `unzip` to browse the sources.
+
+## Key Options
+
+Options use the format `-<key>=<value>`. Boolean options: `1` = enabled, `0` = disabled.
+
+| Option | Default | Description |
+|---|---|---|
+| `-dgs=1` | 0 | Decompile generic signatures (recommended) |
+| `-ren=1` | 0 | Rename obfuscated identifiers |
+| `-mpm=60` | 0 | Max seconds per method — prevents hangs (recommended) |
+| `-hes=0` | 1 | Show empty super() calls |
+| `-hdc=0` | 1 | Show empty default constructors |
+| `-udv=1` | 1 | Use debug variable names if available |
+| `-ump=1` | 1 | Use debug parameter names if available |
+| `-lit=1` | 0 | Output numeric literals as-is |
+| `-asc=1` | 0 | Encode non-ASCII as unicode escapes |
+| `-lac=1` | 0 | Decompile lambdas as anonymous classes |
+| `-log=WARN` | INFO | Reduce output verbosity |
+| `-e=<lib>` | — | Add library for context (not decompiled, improves type resolution) |
+
+## Recommended Presets
+
+### General use
+
+```bash
+java -jar fernflower.jar -dgs=1 -mpm=60 input.jar output/
+```
+
+### Obfuscated code
+
+```bash
+java -jar fernflower.jar -dgs=1 -ren=1 -mpm=60 input.jar output/
+```
+
+### Maximum detail
+
+```bash
+java -jar fernflower.jar -dgs=1 -hes=0 -hdc=0 -mpm=60 input.jar output/
+```
+
+### With Android SDK context (better type resolution)
+
+```bash
+java -jar fernflower.jar -dgs=1 -mpm=60 -e=$ANDROID_HOME/platforms/android-34/android.jar input.jar output/
+```
+
+## Working with APK Files
+
+Fernflower cannot read APK/DEX files directly. Use dex2jar first:
+
+```bash
+# Step 1: Convert DEX to JAR
+d2j-dex2jar -f -o app-converted.jar app.apk
+
+# Step 2: Decompile with Fernflower
+java -jar fernflower.jar -dgs=1 -mpm=60 app-converted.jar output/
+
+# Step 3: Extract the resulting source JAR
+unzip -o output/app-converted.jar -d output/sources/
+```
+
+The `decompile.sh --engine fernflower` script automates these steps.
+
+## Supported Input Formats
+
+| Format | Direct support | Via dex2jar |
+|---|---|---|
+| `.jar` | Yes | — |
+| `.class` | Yes | — |
+| `.zip` (with classes) | Yes | — |
+| `.apk` | No | Yes |
+| `.dex` | No | Yes |
+| `.aar` | No | Yes |
+
+## Output Format
+
+- **JAR input** → Produces `<destination>/<input-name>.jar` containing `.java` files
+- **Class file input** → Produces `.java` files directly in the destination
+- **No resource decoding** — Fernflower only produces Java source, never XML/resources
+
+## Fernflower vs Vineflower
+
+Vineflower is the recommended fork. Improvements over upstream Fernflower:
+
+- Published releases on GitHub and Maven Central
+- Better handling of modern Java (records, sealed classes, pattern matching)
+- More accurate lambda and switch expression decompilation
+- Active bug fixes and community maintenance
+- Same CLI interface — drop-in replacement