@leejungkiin/awkit 1.7.1 → 1.7.4

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

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

@@ -0,0 +1,116 @@
+# jadx CLI Reference
+
+## Basic Usage
+
+```bash
+jadx [options] <input-file>
+```
+
+Input can be an `.apk`, `.jar`, `.aar`, `.dex`, or `.zip` file.
+
+## Key Options
+
+| Option | Description |
+|---|---|
+| `-d <dir>` | Output directory for decompiled sources |
+| `--deobf` | Enable deobfuscation — renames obfuscated classes/methods to readable names |
+| `--show-bad-code` | Show partially decompiled code instead of error comments |
+| `--no-res` | Skip resource decoding — faster when you only need code |
+| `--no-src` | Skip source decompilation — only decode resources |
+| `--export-gradle` | Generate a Gradle project structure (useful for importing into IDE) |
+| `-e` | Same as `--export-gradle` |
+| `--threads-count <N>` | Number of processing threads (default: CPU count) |
+| `-Xmx<size>` | Set maximum Java heap (e.g., `-Xmx4g` for large APKs) |
+
+## Decompiling Different File Types
+
+### APK (Android Application Package)
+
+```bash
+jadx -d output-dir app.apk
+```
+
+Produces:
+- `output-dir/sources/` — Decompiled Java source files
+- `output-dir/resources/` — Decoded resources (AndroidManifest.xml, layouts, drawables, etc.)
+
+### JAR (Java Archive)
+
+```bash
+jadx -d output-dir library.jar
+```
+
+Useful for analyzing third-party libraries bundled within an APK.
+
+### AAR (Android Archive)
+
+```bash
+jadx -d output-dir library.aar
+```
+
+AAR files contain both compiled code and Android resources. jadx handles them directly.
+
+## Handling Obfuscated Code
+
+Apps built with ProGuard or R8 produce obfuscated bytecode with single-letter class and method names.
+
+### Strategies
+
+1. **Use `--deobf`** to generate readable replacement names:
+   ```bash
+   jadx --deobf -d output-dir app.apk
+   ```
+   jadx creates a mapping file at `output-dir/deobf-mapping.txt` that maps original obfuscated names to generated names.
+
+2. **Use the ProGuard mapping file** if available (sometimes shipped in the APK under `assets/` or obtainable from build artifacts):
+   ```bash
+   jadx --deobf-map mapping.txt -d output-dir app.apk
+   ```
+
+3. **Focus on string constants and API calls** rather than class names when navigating obfuscated code. URL strings, annotation values, and library classes are not obfuscated.
+
+## jadx-gui
+
+For interactive exploration, use the GUI version:
+
+```bash
+jadx-gui app.apk
+```
+
+Features:
+- Full-text search across all decompiled sources
+- Click-through navigation (jump to definition)
+- Deobfuscation with live renaming
+- Smali view alongside Java
+
+jadx-gui is included in the same distribution as the CLI tool.
+
+## Common Workflows
+
+### Code-only decompilation (fastest)
+
+```bash
+jadx --no-res --show-bad-code -d output app.apk
+```
+
+### Full decompilation with deobfuscation
+
+```bash
+jadx --deobf --show-bad-code -d output app.apk
+```
+
+### Export as Gradle project for IDE import
+
+```bash
+jadx -e -d output app.apk
+# Then open output/ in Android Studio or IntelliJ
+```
+
+### Decompile a specific DEX from a multi-dex APK
+
+Extract the APK (it's a ZIP), then target individual DEX files:
+
+```bash
+unzip app.apk -d extracted/
+jadx -d output extracted/classes2.dex
+```

package/skills/android-re-analyzer/references/setup-guide.md

@@ -0,0 +1,221 @@
+# Setup Guide: Dependencies for Android Reverse Engineering
+
+## Java JDK 17+
+
+jadx requires Java 17 or later.
+
+### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install openjdk-17-jdk
+```
+
+### Fedora
+
+```bash
+sudo dnf install java-17-openjdk-devel
+```
+
+### Arch Linux
+
+```bash
+sudo pacman -S jdk17-openjdk
+```
+
+### macOS (Homebrew)
+
+```bash
+brew install openjdk@17
+```
+
+After installation on macOS, follow the symlink instructions printed by Homebrew, or add to your shell profile:
+
+```bash
+export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"
+```
+
+### Verify
+
+```bash
+java -version
+# Should show version 17.x or higher
+```
+
+---
+
+## jadx
+
+jadx is the Java decompiler used to convert APK/JAR/AAR files to readable Java source.
+
+### Option 1: GitHub Releases (recommended)
+
+1. Go to <https://github.com/skylot/jadx/releases/latest>
+2. Download the `jadx-<version>.zip` file (not the source archive)
+3. Extract and add to PATH:
+
+```bash
+unzip jadx-*.zip -d ~/jadx
+export PATH="$HOME/jadx/bin:$PATH"
+# Add the export line to your ~/.bashrc or ~/.zshrc for persistence
+```
+
+### Option 2: Homebrew (macOS / Linux)
+
+```bash
+brew install jadx
+```
+
+### Option 3: Build from source
+
+```bash
+git clone https://github.com/skylot/jadx.git
+cd jadx
+./gradlew dist
+# Binaries will be in build/jadx/bin/
+export PATH="$(pwd)/build/jadx/bin:$PATH"
+```
+
+### Verify
+
+```bash
+jadx --version
+```
+
+---
+
+## Fernflower / Vineflower (optional, recommended)
+
+Fernflower is the JetBrains Java decompiler. It produces better output than jadx on complex Java constructs, lambdas, and generics. [Vineflower](https://github.com/Vineflower/vineflower) is the actively maintained community fork with published releases — prefer it over upstream Fernflower.
+
+### Option 1: Vineflower from GitHub Releases (recommended)
+
+1. Go to <https://github.com/Vineflower/vineflower/releases/latest>
+2. Download `vineflower-<version>.jar`
+3. Place it and set the environment variable:
+
+```bash
+mkdir -p ~/vineflower
+mv vineflower-*.jar ~/vineflower/vineflower.jar
+export FERNFLOWER_JAR_PATH="$HOME/vineflower/vineflower.jar"
+# Add the export to ~/.bashrc or ~/.zshrc for persistence
+```
+
+### Option 2: Build Fernflower from source
+
+```bash
+git clone https://github.com/JetBrains/fernflower.git
+cd fernflower
+./gradlew jar
+# Produces: build/libs/fernflower.jar
+export FERNFLOWER_JAR_PATH="$(pwd)/build/libs/fernflower.jar"
+```
+
+### Option 3: Homebrew (Vineflower)
+
+```bash
+brew install vineflower
+```
+
+### Verify
+
+```bash
+java -jar "$FERNFLOWER_JAR_PATH" --version
+```
+
+> **Note**: Fernflower only works on JVM bytecode (JAR, class files). For APK/DEX files, you also need **dex2jar** (see below) as an intermediate conversion step.
+
+---
+
+## dex2jar (optional, needed for Fernflower on APK files)
+
+Converts Android DEX bytecode to standard Java JAR files.
+
+### GitHub Releases
+
+1. Go to <https://github.com/pxb1988/dex2jar/releases/latest>
+2. Download and extract:
+
+```bash
+unzip dex-tools-*.zip -d ~/dex2jar
+export PATH="$HOME/dex2jar:$PATH"
+```
+
+### Homebrew
+
+```bash
+brew install dex2jar
+```
+
+### Verify
+
+```bash
+d2j-dex2jar --help
+```
+
+### Usage
+
+```bash
+# Convert APK (or DEX) to JAR
+d2j-dex2jar -f -o output.jar app.apk
+
+# Then decompile with Fernflower
+java -jar vineflower.jar output.jar decompiled/
+```
+
+---
+
+## Optional Tools
+
+### apktool
+
+Useful for decoding resources (XML layouts, drawables) that jadx sometimes handles poorly.
+
+```bash
+# Ubuntu/Debian
+sudo apt install apktool
+
+# macOS
+brew install apktool
+
+# Manual: https://apktool.org/docs/install
+```
+
+### adb (Android Debug Bridge)
+
+Useful for pulling APKs directly from a connected Android device.
+
+```bash
+# Ubuntu/Debian
+sudo apt install adb
+
+# macOS
+brew install android-platform-tools
+```
+
+Pull an APK from a device:
+
+```bash
+# List installed packages
+adb shell pm list packages | grep <keyword>
+
+# Get APK path
+adb shell pm path com.example.app
+
+# Pull the APK
+adb pull /data/app/com.example.app-xxxx/base.apk ./app.apk
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `jadx: command not found` | Ensure the jadx `bin/` directory is in your `$PATH` |
+| `Error: Could not find or load main class` | Java is missing or wrong version — verify with `java -version` |
+| jadx runs out of memory on large APKs | Increase heap: `jadx -Xmx4g -d output app.apk` or set `JAVA_OPTS="-Xmx4g"` |
+| Decompiled code has many `// Error` comments | Try `--show-bad-code` to see partial output, or use `--deobf` for obfuscated apps |
+| Fernflower hangs on a method | Use `-mpm=60` to set a 60-second timeout per method |
+| Fernflower JAR not found | Set `FERNFLOWER_JAR_PATH` env variable to the full path of the JAR |
+| dex2jar fails with `ZipException` | The APK may have a non-standard ZIP structure — try `jadx` instead |