@leejungkiin/awkit 1.1.0 → 1.1.2

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 |

package/skills/android-re-analyzer/scripts/check-deps.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify dependencies and report what's missing
+# Output includes machine-readable INSTALL:<dep> lines for each missing dependency.
+# The install-dep.sh script can install each one.
+set -euo pipefail
+
+REQUIRED_JAVA_MAJOR=17
+errors=0
+missing_required=()
+missing_optional=()
+
+echo "=== Android Reverse Engineering: Dependency Check ==="
+echo
+
+# --- Java ---
+java_ok=false
+if command -v java &>/dev/null; then
+  java_version_output=$(java -version 2>&1 | head -1)
+  java_version=$(echo "$java_version_output" | sed -n 's/.*"\([0-9]*\)\..*/\1/p')
+  if [[ -z "$java_version" ]]; then
+    java_version=$(echo "$java_version_output" | grep -oP '\d+' | head -1)
+  fi
+  if [[ "$java_version" == "1" ]]; then
+    java_version=$(echo "$java_version_output" | sed -n 's/.*"1\.\([0-9]*\)\..*/\1/p')
+  fi
+
+  if [[ -n "$java_version" ]] && (( java_version >= REQUIRED_JAVA_MAJOR )); then
+    echo "[OK] Java $java_version detected"
+    java_ok=true
+  else
+    echo "[WARN] Java detected but version $java_version is below $REQUIRED_JAVA_MAJOR"
+    errors=$((errors + 1))
+    missing_required+=("java")
+  fi
+else
+  echo "[MISSING] Java is not installed or not in PATH"
+  errors=$((errors + 1))
+  missing_required+=("java")
+fi
+
+# --- jadx ---
+if command -v jadx &>/dev/null; then
+  jadx_version=$(jadx --version 2>/dev/null || echo "unknown")
+  echo "[OK] jadx $jadx_version detected"
+else
+  echo "[MISSING] jadx is not installed or not in PATH"
+  errors=$((errors + 1))
+  missing_required+=("jadx")
+fi
+
+# --- Fernflower / Vineflower ---
+ff_found=false
+if command -v vineflower &>/dev/null; then
+  echo "[OK] vineflower CLI detected"
+  ff_found=true
+elif command -v fernflower &>/dev/null; then
+  echo "[OK] fernflower CLI detected"
+  ff_found=true
+else
+  for candidate in \
+    "${FERNFLOWER_JAR_PATH:-}" \
+    "$HOME/.local/share/vineflower/vineflower.jar" \
+    "$HOME/fernflower/build/libs/fernflower.jar" \
+    "$HOME/vineflower/build/libs/vineflower.jar" \
+    "$HOME/fernflower/fernflower.jar" \
+    "$HOME/vineflower/vineflower.jar"; do
+    if [[ -n "$candidate" ]] && [[ -f "$candidate" ]]; then
+      echo "[OK] Fernflower/Vineflower JAR found: $candidate"
+      ff_found=true
+      break
+    fi
+  done
+fi
+if [[ "$ff_found" == false ]]; then
+  echo "[MISSING] Fernflower/Vineflower not found (optional — better output on complex Java code)"
+  missing_optional+=("vineflower")
+fi
+
+# --- dex2jar ---
+if command -v d2j-dex2jar &>/dev/null || command -v d2j-dex2jar.sh &>/dev/null; then
+  echo "[OK] dex2jar detected"
+else
+  echo "[MISSING] dex2jar not found (optional — needed to use Fernflower on APK/DEX files)"
+  missing_optional+=("dex2jar")
+fi
+
+# --- Optional: apktool ---
+if command -v apktool &>/dev/null; then
+  echo "[OK] apktool detected (optional)"
+else
+  echo "[MISSING] apktool not found (optional — useful for resource decoding)"
+  missing_optional+=("apktool")
+fi
+
+# --- Optional: adb ---
+if command -v adb &>/dev/null; then
+  echo "[OK] adb detected (optional)"
+else
+  echo "[MISSING] adb not found (optional — useful for pulling APKs from devices)"
+  missing_optional+=("adb")
+fi
+
+# --- Machine-readable summary ---
+echo
+if [[ ${#missing_required[@]} -gt 0 ]]; then
+  for dep in "${missing_required[@]}"; do
+    echo "INSTALL_REQUIRED:$dep"
+  done
+fi
+if [[ ${#missing_optional[@]} -gt 0 ]]; then
+  for dep in "${missing_optional[@]}"; do
+    echo "INSTALL_OPTIONAL:$dep"
+  done
+fi
+
+echo
+if (( errors > 0 )); then
+  echo "*** ${#missing_required[@]} required dependency/ies missing. ***"
+  echo "Run install-dep.sh <name> to install, or see references/setup-guide.md."
+  exit 1
+else
+  if [[ ${#missing_optional[@]} -gt 0 ]]; then
+    echo "Required dependencies OK. ${#missing_optional[@]} optional dependency/ies missing."
+    echo "Run install-dep.sh <name> to install optional tools."
+  else
+    echo "All dependencies are installed. Ready to decompile."
+  fi
+  exit 0
+fi