# Android APK Playbook

Load this playbook for APKs, Android split APKs, DEX/JAR-derived Android code, and Android stages.

## Tools

Preferred: `jadx`, `apktool`, `aapt2`, `strings`, `rg`, `yara`, `7z`, `exiftool`, `python3`.

Useful: `bundletool`, `apkanalyzer`, `floss`, `rabin2`, `r2`, `objdump`, `readelf`, Ghidra headless for native libraries.

If a blocking tool is missing, ask before installing it. Use fallbacks such as `aapt` for `aapt2`, `unzip`/`7z` for extraction, and manual XML/resource inspection when needed.

## Workflow

1. Extract metadata: package name, version, SDK, signing info, cert metadata, file list.
2. Decode manifest/resources with `apktool` or equivalent.
3. Decompile with `jadx`; inspect smali when jadx output is incomplete.
4. Search permissions, services, receivers, providers, jobs, accessibility services, device admin, foreground services, boot receivers, notification listeners, SMS/phone/admin APIs, overlay APIs, crypto, reflection, dynamic loading, native bridges, WebView, Firebase, MQTT, WebSocket, sockets, HTTP clients, and hardcoded infrastructure.
5. Inspect `assets/`, `res/raw/`, DEX files, embedded archives, native `.so` libraries, certificates, and update/config files.
6. Trace C2/config construction from constants through decoders to network calls.
7. Reconstruct Base64, XOR, AES/DES/RSA/ECC/ChaCha/RC4/custom encoding, compressed configs, split strings, reflection targets, and runtime keys where feasible.
8. If a stage/config/drop URL is authorized for retrieval, download it using the parent request logic and analyze it as a new stage.
9. Save manifest findings, decompiled code excerpts, smali paths, assets, configs, decoder scripts, native-library notes, and stage artifacts.

## APK Edge Cases

- Follow the core Token Budget And Anti-Loop Mode.
- If Python `zipfile` fails, switch to `7z`, `unzip`, `jadx`, `apktool`, `aapt2`, `apkanalyzer`, or raw local-header carving.
- Manual ZIP/APK carving is limited to two bounded attempts. If both fail, write a checkpoint to `AGENTS.md` and `REPORT.md`, document the blocker, and pivot to DEX, assets, native libraries, jadx output, strings, services, receivers, and code-level key derivation.
- If manifest decoding fails, use `aapt2`, `apktool`, jadx output, binary XML tools, strings from DEX/resources, and decompiled references as fallbacks.
- For encrypted assets, search code/resources/native libraries for explicit key derivation before any bounded password attempt.
- For B4A apps, inspect modules and events, but never infer password or family from module names alone.

## Android Family Pattern Enrichment

Use this remote dataset when network is allowed:

`https://raw.githubusercontent.com/guelfoweb/artifacts/refs/heads/main/data/patterns.json`

Extract and compare:

- `permission`: manifest permission values.
- `application`: manifest/application definition values.
- `intent`: intent-related values found across the APK, not only in the manifest.

For intent extraction, search all decoded/extracted APK files for values matching Android intent-style patterns, including strings like `*.intent.*.*` and `intent.*.*` fragments.

Compute a similarity score percentage per family. Report top candidates with:

- family name
- match score percentage
- matched permissions
- matched application values
- matched intent-related values
- missing or divergent values

Use the score as supporting attribution only. Correlate it with code, services, receivers, config, infrastructure, crypto, and stage behavior. If scores are close or weak, report candidates as tentative. If the dataset is unavailable, continue and record that enrichment failed.

## Report Requirements

Include package name, cert/signing metadata, suspicious components, recovered C2/drop/stage/config URLs, relevant classes/methods/smali paths, native libraries, decoder or crypto algorithms, stage hashes, family candidates with APK-pattern score, confidence, and limitations.