# newliver666/apk-reverse architecture

> Architecture diagram of the GitHub repository newliver666/apk-reverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/newliver666/apk-reverse
- Repository: https://github.com/newliver666/apk-reverse

## Overview

apk-reverse is an Agent Skill and toolkit for Android APK reverse engineering, patching, runtime investigation, and repacking. Its principal workflow is to check host/device capabilities, inspect or recover target code, identify and bound a change, patch at a suitable layer, then validate and package the deliverable. Separate branches cover native and protocol analysis, on-device workflows, and runtime instrumentation. The excerpts show dex-tool imports and the documented doctor entry point; several other script-to-stage mappings are inferred from names and README capabilities, so those links are marked unverified.

Main entry points: [`skills/apk-reverse/scripts/dexutil.py`](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dexutil.py) (DEX reader), [`skills/apk-reverse/scripts/doctor.py`](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/doctor.py) (Environment doctor), [`skills/apk-reverse/scripts/dex_find_insn.py`](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_find_insn.py) (Instruction search), [`skills/apk-reverse/scripts/find_refs.py`](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/find_refs.py) (Reference analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Environment"]
  node_doctor["Environment doctor<br/>[doctor.py]"]
  node_capabilities["Capability registry<br/>[capabilities.py]"]
end

subgraph group_apk_analysis["APK Analysis"]
  node_dex_reader["DEX reader<br/>[dexutil.py]"]
  node_dex_search["Instruction search<br/>[dex_find_insn.py]"]
  node_references["Reference analysis<br/>[find_refs.py]"]
  node_dump_validation["Dump validation"]
  node_vmp_analysis["VMP comparison"]
  node_apk_diff["APK comparison<br/>[apk_diff.py]"]
  node_blob_decode["Blob decoding<br/>[blob_decode.py]"]
  node_native_analysis["Native analysis<br/>[elf_plt.py]"]
  node_protocol_analysis["Protocol decoding"]
end

subgraph group_modification["Modification"]
  node_dex_patch["DEX byte patching<br/>[dex_patch_bytes.py]"]
  node_smali_patch["Smali patching<br/>[patch_smali.py]"]
  node_repack["APK repacking<br/>[repack.py]"]
end

subgraph group_runtime["Runtime Analysis"]
  node_runtime_probe["Runtime probing<br/>[run_probe.py]"]
  node_frida_probe["Frida instrumentation<br/>[frida_probe.js]"]
  node_rpc_service["Frida RPC service<br/>[frida_rpc_serve.py]"]
  node_crash_analysis["Crash analysis<br/>[native_crash.py]"]
  node_tls_analysis["TLS analysis<br/>[tls_check.py]"]
  node_stalker["Instruction tracing<br/>[stalker_trace.js]"]
end

node_agent(("Reverse engineer"))
node_device["Android device"]

node_agent -->|"checks first"| node_doctor
node_doctor -->|"queries capabilities"| node_capabilities
node_agent -.->|"investigates on"| node_device
node_agent -.->|"validates dumps"| node_dump_validation
node_agent -.->|"locates code"| node_dex_search
node_dex_search -->|"uses reader"| node_dex_reader
node_references -->|"uses reader"| node_dex_reader
node_dump_validation -->|"uses reader"| node_dex_reader
node_vmp_analysis -->|"uses reader"| node_dex_reader
node_agent -.->|"checks blast radius"| node_references
node_agent -.->|"patches DEX"| node_dex_patch
node_agent -.->|"patches smali"| node_smali_patch
node_agent -.->|"packages result"| node_repack
node_agent -.->|"analyzes libraries"| node_native_analysis
node_agent -.->|"analyzes protocols"| node_protocol_analysis
node_agent -.->|"probes runtime"| node_runtime_probe
node_agent -.->|"instruments runtime"| node_frida_probe
node_agent -.->|"calls routines"| node_rpc_service
node_agent -.->|"investigates crashes"| node_crash_analysis
node_agent -.->|"checks TLS"| node_tls_analysis
node_agent -.->|"traces execution"| node_stalker

click node_doctor "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/doctor.py"
click node_capabilities "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/capabilities.py"
click node_dex_reader "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dexutil.py"
click node_dex_search "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_find_insn.py"
click node_references "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/find_refs.py"
click node_dump_validation "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_dump_validate.py"
click node_vmp_analysis "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/vmp_diff_harness.py"
click node_apk_diff "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/apk_diff.py"
click node_blob_decode "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/blob_decode.py"
click node_dex_patch "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_patch_bytes.py"
click node_smali_patch "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/patch_smali.py"
click node_repack "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/repack.py"
click node_native_analysis "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/elf_plt.py"
click node_protocol_analysis "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/protobuf_decode_raw.py"
click node_runtime_probe "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/run_probe.py"
click node_frida_probe "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/frida_probe.js"
click node_rpc_service "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/frida_rpc_serve.py"
click node_crash_analysis "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/native_crash.py"
click node_tls_analysis "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/tls_check.py"
click node_stalker "https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/stalker_trace.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_doctor,node_capabilities toneBlue
class node_dex_reader,node_dex_search,node_references,node_dump_validation,node_vmp_analysis,node_apk_diff,node_blob_decode,node_native_analysis,node_protocol_analysis toneAmber
class node_dex_patch,node_smali_patch,node_repack toneMint
class node_runtime_probe,node_frida_probe,node_rpc_service,node_crash_analysis,node_tls_analysis,node_stalker toneRose
class node_agent,node_device toneIndigo
```

## Components

### Environment

- [Environment doctor](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/doctor.py): `skills/apk-reverse/scripts/doctor.py`
- [Capability registry](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/capabilities.py): `skills/apk-reverse/scripts/capabilities.py`

### APK Analysis

- [DEX reader](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dexutil.py): `skills/apk-reverse/scripts/dexutil.py`
- [Instruction search](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_find_insn.py): `skills/apk-reverse/scripts/dex_find_insn.py`
- [Reference analysis](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/find_refs.py): `skills/apk-reverse/scripts/find_refs.py`
- [Dump validation](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_dump_validate.py): `skills/apk-reverse/scripts/dex_dump_validate.py`
- [VMP comparison](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/vmp_diff_harness.py): `skills/apk-reverse/scripts/vmp_diff_harness.py`
- [APK comparison](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/apk_diff.py): `skills/apk-reverse/scripts/apk_diff.py`
- [Blob decoding](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/blob_decode.py): `skills/apk-reverse/scripts/blob_decode.py`
- [Native analysis](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/elf_plt.py): `skills/apk-reverse/scripts/elf_plt.py`
- [Protocol decoding](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/protobuf_decode_raw.py): `skills/apk-reverse/scripts/protobuf_decode_raw.py`

### Modification

- [DEX byte patching](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/dex_patch_bytes.py): `skills/apk-reverse/scripts/dex_patch_bytes.py`
- [Smali patching](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/patch_smali.py): `skills/apk-reverse/scripts/patch_smali.py`
- [APK repacking](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/repack.py): `skills/apk-reverse/scripts/repack.py`

### Runtime Analysis

- [Runtime probing](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/run_probe.py): `skills/apk-reverse/scripts/run_probe.py`
- [Frida instrumentation](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/frida_probe.js): `skills/apk-reverse/scripts/frida_probe.js`
- [Frida RPC service](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/frida_rpc_serve.py): `skills/apk-reverse/scripts/frida_rpc_serve.py`
- [Crash analysis](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/native_crash.py): `skills/apk-reverse/scripts/native_crash.py`
- [TLS analysis](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/tls_check.py): `skills/apk-reverse/scripts/tls_check.py`
- [Instruction tracing](https://github.com/newliver666/apk-reverse/blob/main/skills/apk-reverse/scripts/stalker_trace.js): `skills/apk-reverse/scripts/stalker_trace.js`

### Other components

- **Reverse engineer**
- **Android device**

## Connections

- Reverse engineer → Environment doctor: checks first (evidence: `README.md`)
- Environment doctor → Capability registry: queries capabilities (evidence: `skills/apk-reverse/scripts/doctor.py`)
- Reverse engineer → Android device: investigates on
- Reverse engineer → Dump validation: validates dumps
- Reverse engineer → Instruction search: locates code
- Instruction search → DEX reader: uses reader (evidence: `skills/apk-reverse/scripts/dex_find_insn.py`)
- Reference analysis → DEX reader: uses reader (evidence: `skills/apk-reverse/scripts/find_refs.py`)
- Dump validation → DEX reader: uses reader (evidence: `skills/apk-reverse/scripts/dex_dump_validate.py`)
- VMP comparison → DEX reader: uses reader (evidence: `skills/apk-reverse/scripts/vmp_diff_harness.py`)
- Reverse engineer → Reference analysis: checks blast radius
- Reverse engineer → DEX byte patching: patches DEX
- Reverse engineer → Smali patching: patches smali
- Reverse engineer → APK repacking: packages result
- Reverse engineer → Native analysis: analyzes libraries
- Reverse engineer → Protocol decoding: analyzes protocols
- Reverse engineer → Runtime probing: probes runtime
- Reverse engineer → Frida instrumentation: instruments runtime
- Reverse engineer → Frida RPC service: calls routines
- Reverse engineer → Crash analysis: investigates crashes
- Reverse engineer → TLS analysis: checks TLS
- Reverse engineer → Instruction tracing: traces execution
