chore(agents): 添加 Android 逆向工程 skill
包含 APK 反编译、API 调用提取、调用链分析、Kotlin 名称恢复等参考文档, 以及 jadx/fernflower 相关脚本与第三方域名过滤列表。 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
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$
|
||||
Reference in new issue
Block a user