chore(agents): 添加 Android 逆向工程 skill

包含 APK 反编译、API 调用提取、调用链分析、Kotlin 名称恢复等参考文档,
以及 jadx/fernflower 相关脚本与第三方域名过滤列表。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:15:24 +08:00
1 parent 252b7088cf
commit c29e425996
19 files changed
+4392

No files matched your search

@@ -0,0 +1,197 @@
# 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/
```
## Ktor (Kotlin)
Ktor is the dominant HTTP client in Kotlin Multiplatform and modern
Kotlin-only Android apps. Unlike Retrofit, Ktor does **not** use annotations
to declare endpoints — paths appear as plain string arguments to
`client.get(...)` / `client.post(...)`, often inside an extension function.
```bash
# Calls
grep -rn '\b\(client\|httpClient\|HttpClient\)\.\(get\|post\|put\|delete\|patch\|head\|request\)\s*[<(]' sources/
# Default request / base URL configuration
grep -rn 'HttpRequestBuilder\|defaultRequest\s*{\|\burl\s*(\s*"\|URLBuilder' sources/
# Auth plugin (bearer / refresh)
grep -rn '\bbearer\s*{\|BearerTokens\s*(\|loadTokens\s*{\|refreshTokens\s*{' sources/
```
Typical Ktor call (after decompile):
```java
client.get("api/v1/users/profile") {
parameter("locale", "en-US");
}
```
The base URL is usually applied via `defaultRequest { url { host = "..." } }`
in the client builder. Search for `host =` and `URLProtocol.HTTPS` references
to pin it down.
**Note on obfuscation:** in heavily R8-shrunk apps the call site
`client.get("path")` is inlined to something like `aVar.a(dVar, "path")`
and the `client.<verb>(` regex misses it. The path string itself is **not**
obfuscated, however — fall back to the generic path-literal search
(`--paths`) for the endpoint inventory in those cases. Ktor library
internals (`BearerTokens`, `loadTokens`, `refreshTokens`, `URLProtocol`)
remain searchable because Ktor keeps these on its public API.
Ktor's authentication plugin uses the
[`Auth { bearer { loadTokens { ... }; refreshTokens { ... } } }`](https://ktor.io/docs/auth.html)
DSL — bearer access tokens with automatic refresh. After R8, the DSL
lambdas appear as `Function2`/`Function3` impls referencing
`BearerTokens(...)` calls.
## Apollo Kotlin (GraphQL)
```bash
# Client setup
grep -rn 'ApolloClient\|\.serverUrl(\|HttpNetworkTransport' sources/
# Operations (queries / mutations / subscriptions)
grep -rn '\.query(\s*[A-Z]\|\.mutation(\s*[A-Z]\|\.subscription(\s*[A-Z]' sources/
```
Apollo generates one class per operation under a generated package; once you
find the GraphQL endpoint URL via `ApolloClient.serverUrl("...")`, use the
operation classes themselves as the API documentation — each carries its
GraphQL document text in `OPERATION_DOCUMENT`.
## 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.
## Endpoint-Shaped Path Literals (obfuscation-resistant)
When the HTTP client cannot be identified (custom abstraction, heavy
inlining, KMP shared module), or the call sites are obfuscated to
`a.b(c, "path")`, fall back to extracting the path string literals
themselves. R8 does not obfuscate string contents, so paths leak through.
```bash
# All quoted strings shaped like an API path, deduplicated
grep -rhoE '"(/[A-Za-z0-9_{}.\-]+(/[A-Za-z0-9_{}.\-]+)+/?|(api|v[0-9]+|graphql|users?|account|auth|sso|oauth|profile|cart|basket|order|product|inventory|search|category|address|location|delivery|payment|invoice|favo[u]?rites?)(/[A-Za-z0-9_{}.\-]+)+/?)"' sources/ \
| grep -Ev '^"(image|video|audio|text|application|content)/|^"/(proc|sys|dev|tmp|etc)/' \
| sort -u
```
The skill ships this as `find-api-calls.sh --paths`, which prints both a
deduplicated inventory and the full list of call sites. On real-world
Kotlin apps this single command typically produces 100–300 distinct
endpoint paths, which is the most useful first artifact for documentation.
## 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
@@ -0,0 +1,210 @@
# 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
```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/
```
### Koin
Koin is the dominant DI framework in Kotlin Multiplatform and a large
share of Kotlin-only Android apps. It uses a runtime DSL rather than
compile-time generated factories, so the search patterns are different:
```bash
# Confirm Koin is actually wired up
grep -rn 'org\.koin\.' sources/
# DI module declarations
grep -rn 'fun [A-Za-z]\+Module\|module\s*{\|module(' sources/
# Bindings inside a module DSL
grep -rn 'single\s*[<{(]\|factory\s*[<{(]\|viewModel\s*[<{(]\|scoped\s*[<{(]\|singleOf\|factoryOf' sources/
# Resolution call-sites (where a binding is consumed)
grep -rn '\bget\s*<\|\binject\s*<\|by\s\+inject\b\|by\s\+viewModel\b\|getKoin' sources/
```
After R8, every binding lambda becomes an anonymous
`Function2<Scope, ParametersHolder, T>` impl. To find the binding for an
interface `Foo`, look for files that contain both a Koin import / module
DSL marker and a reference to `Foo`:
```bash
grep -rln 'org\.koin\.core\.module' sources/ | xargs grep -l 'Foo'
```
### Trace through DI
1. Find where an interface is used (e.g. `ApiService` injected into a
repository).
2. Find the `@Provides` / `@Binds` method (Hilt) **or** the
`single { ... }` / `factory { ... }` block (Koin) 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. **Recover original Kotlin names from metadata**: `@DebugMetadata` and `@Metadata.d2` strings preserve the original FQNs even after R8 obfuscation. Run `scripts/recover-kotlin-names.sh` to build an `obf -> real` map (typically recovers 30-50% of classes — and almost 100% of `*Repository` / `*ViewModel` / `*Impl`). See [`kotlin-name-recovery.md`](./kotlin-name-recovery.md). This is the single highest-leverage step on any Kotlin app.
5. **Cross-reference**: If `class a` calls `Retrofit.create(b.class)`, then `b` is a Retrofit service interface
6. **`--deobf` is rarely enough on its own**: jadx's `--deobf` renames obfuscated symbols with synthetic placeholders (`p001a`, `C0123Foo`) — useful for disambiguation but it does **not** recover original names. Pair it with the metadata recovery above.
## 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/` |
@@ -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
@@ -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
```
@@ -0,0 +1,108 @@
# Recovering Original Class Names from Kotlin Metadata
When R8/ProGuard obfuscates a Kotlin app, JVM symbols are renamed but the
**Kotlin metadata strings cannot be stripped** — the Kotlin runtime depends
on them at runtime for reflection, coroutines, and `data class` features.
Two annotations leak the original fully-qualified names:
## `@DebugMetadata`
Generated for nearly every Kotlin coroutine `SuspendLambda` (i.e. almost
every `suspend` function in a modern app):
```java
@DebugMetadata(
c = "com.example.feature.account.AccountRepositoryImpl$fetch$1",
f = "AccountRepositoryImpl.kt",
l = {42, 51},
m = "invokeSuspend"
)
public final class a extends SuspendLambda implements Function2<...> { ... }
```
The `c =` field carries the original outer class FQN (with a `$` suffix
for inner / lambda scopes — strip everything after the first `$` to get the
declaring class).
## `@Metadata.d2`
Every Kotlin class carries a top-level `@Metadata` annotation. The `d2`
array lists internal class refs in JVM type-descriptor format
(`Lcom/example/Foo;`):
```java
@Metadata(d1 = {"..."},
d2 = {"...","Lcom/example/feature/account/AccountRepositoryImpl;","..."})
public final class b implements ... { ... }
```
The first non-stdlib descriptor in `d2` is usually the file's primary
class.
## How to mine them
The skill ships two scripts:
```bash
# Build a mapping from a decompiled sources directory:
bash scripts/recover-kotlin-names.sh <output>/sources [mapping-dir]
# Outputs:
# <mapping-dir>/mapping.tsv obf_fqn real_fqn file
# <mapping-dir>/mapping.json same data, JSON
# <mapping-dir>/by_package/ per-real-package index files
# Query the mapping:
bash scripts/lookup-name.sh <mapping-dir> Repository # search
bash scripts/lookup-name.sh <mapping-dir> -o ab.cd # obf -> real
bash scripts/lookup-name.sh <mapping-dir> -p com.example.feature # list package
bash scripts/lookup-name.sh <mapping-dir> --grep '"api/' <output>/sources
# ^ greps decompiled code and appends '// real.fqn' to each hit
```
## What you typically recover
On a real-world obfuscated Kotlin app the script recovers **30 – 50 % of
classes** — but more importantly, **almost 100 % of the classes you
actually want to read**:
| Class kind | Recovery rate |
|---------------------------|---------------|
| `*Repository` / `*Impl` | ~100 % |
| `*ViewModel` | ~100 % |
| `*UseCase` / `*Interactor`| ~100 % |
| Plain `data class` DTOs | ~80 % |
| Pure-Java helper classes | low (no Kotlin metadata) |
| Anonymous inner classes | sometimes recovered as the parent FQN |
## Why `jadx --deobf` is not enough
`--deobf` renames obfuscated identifiers using internal heuristics, but the
output is still synthetic (`p001a`, `C0123Foo`). It does **not** recover
the *original* names. Kotlin metadata recovery is the only reliable way to
map back to the names the developer actually wrote, and it costs essentially
nothing — just a regex pass over the decompiled sources.
Run both: `--deobf` for fields/methods that have no metadata source, plus
the recovery script for class names.
## Limitations
- **Method names and field names** are not recovered. Kotlin metadata only
preserves class-level FQNs and a few signatures. For method names you
still need jadx-gui's interactive rename or pattern inference.
- **Pure-Java classes** carry no `@Metadata`, so they remain obfuscated.
- **Heavily inlined classes** (`@JvmInline value class`, top-level fun
files compiled into shared `*Kt.class` synthetic classes) sometimes show
up under the wrong filename — treat results as a strong hint, not gospel.
## Reading flow with the mapping
1. Run `recover-kotlin-names.sh` once after decompiling.
2. Use `lookup-name.sh --grep '<pattern>' <sources>` instead of plain `grep`
so every hit comes annotated with the real owning class.
3. When you hit an obfuscated FQN in code (e.g. `nq.e`), resolve it with
`lookup-name.sh <mapping-dir> -o nq.e` — you will often see siblings
(`nq.d`, `nq.f`, ...) that are the same class's split lambdas/inner
classes, which is useful context.
@@ -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/ThexXTURBOXx/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 |
@@ -0,0 +1,122 @@
# Third-party host denylist used by find-api-calls.sh --urls.
#
# Patterns are extended-regex hostname suffixes / fragments. A host is
# considered "third-party noise" if any pattern below matches anywhere
# in the hostname. Lines starting with '#' and blank lines are ignored.
#
# This list is intentionally conservative: when a pattern would hide a
# legitimate first-party host (e.g. an app may run its own *.s3.amazonaws.com
# bucket), keep the pattern but expect manual review of the bucketed output.
# Google / Firebase / Play / Crashlytics
\.googleapis\.com$
\.google\.com$
\.gstatic\.com$
\.googleusercontent\.com$
\.googletagmanager\.com$
\.googlesyndication\.com$
\.firebaseio\.com$
\.firebaseapp\.com$
\.firebaseinstallations\.googleapis\.com$
\.firebaseremoteconfig\.googleapis\.com$
\.crashlytics\.com$
\.app-measurement\.com$
# Apple / Microsoft / Adobe
\.apple\.com$
\.icloud\.com$
\.microsoft\.com$
\.live\.com$
\.office\.com$
\.adobe\.com$
ns\.adobe\.com
# Meta
\.facebook\.com$
\.fbcdn\.net$
\.instagram\.com$
\.whatsapp\.com$
# Other social / messaging / video
\.twitter\.com$
\.x\.com$
\.tiktok\.com$
\.youtube\.com$
\.youtu\.be$
\.linkedin\.com$
\.snapchat\.com$
\.pinterest\.com$
\.reddit\.com$
# Mobile attribution / analytics / observability
\.appsflyersdk\.com$
\.appsflyer\.com$
\.adjust\.com$
\.branch\.io$
\.amplitude\.com$
\.segment\.com$
\.mixpanel\.com$
\.hotjar\.com$
\.clarity\.ms$
\.datadoghq\.(com|eu|us)$
\.sentry\.io$
\.bugsnag\.com$
\.newrelic\.com$
\.instabug\.com$
\.embrace\.io$
\.rollout\.io$
\.launchdarkly\.com$
# Push / notifications
\.onesignal\.com$
\.urbanairship\.com$
\.airship\.com$
# Support / chat
\.zendesk\.com$
\.intercom\.io$
\.intercomcdn\.com$
\.helpshift\.com$
\.salesforce\.com$
\.freshchat\.com$
\.kustomerapp\.com$
# Payments
\.stripe\.com$
\.braintreepayments\.com$
\.braintreegateway\.com$
\.payu\.com$
\.payu\.in$
\.paypal\.com$
\.adyen\.com$
\.checkout\.com$
\.klarna\.com$
# Maps / location
\.mapbox\.com$
\.openstreetmap\.org$
# Storage / CDN (often third-party even when the bucket name is app-specific)
\.s3\.amazonaws\.com$
\.cloudfront\.net$
\.akamaihd\.net$
\.akamaized\.net$
\.fastly\.net$
\.cloudflare\.com$
\.azureedge\.net$
# DNS / well-known infra
\.localhost$
^localhost
^127\.
# Standards / RFCs / placeholders that show up as XML/XMP namespaces
\.w3\.org$
\.w3c\.org$
example\.(com|org|net)$
# Certificate authorities
\.sectigo\.com$
\.entrust\.com$
\.digicert\.com$
\.letsencrypt\.org$