Inside apk-reverse: an agent skill that turns APK patching into a gated procedure

apk-reverse packages Android APK reverse engineering — dex patching, unpacking, repacking, and Frida instrumentation — as a procedural skill for authorized analysis agents.

Tool	newliver666/apk-reverse — an Agent Skill for Android APK reverse engineering, patching, repacking, and runtime analysis
Category	Android reverse engineering / agent skill package
Primary Use	Guiding an AI agent through authorized APK analysis: packer identification, dex byte-patching, repacking, and runtime instrumentation with frida
Safe Use	For authorized security assessments, malware analysis, and research on apps you own or have written permission to test
Telemetry Note	Purely a local documentation/script skill — no network callbacks; defenders would observe any underlying tooling it invokes (frida, adb, rebuild tools) on managed endpoints

newliver666/apk-reverse is not a conventional Python tool so much as a discipline encoded as a package: an Agent Skill, written in Python 3.9+ and MIT-licensed, designed to be loaded by an agent harness such as Claude Code or Codex while it works on an Android APK. The repository's core claim is that the dominant failure mode in automated reverse engineering is not ignorance but undisciplined reasoning — a model that reads the procedure, agrees with it, and then reasons from first principles anyway. The skill counters that with a short, decision-oriented SKILL.md, on-demand references/ files, and parameterized scripts/ intended for authorized analysis, debloating, and runtime/server research on applications the operator owns or is contracted to test.

The architecture follows the Agent Skills format's progressive-disclosure principle. SKILL.md is deliberately small — a procedure with gates — while heavier material lives in references/ with one topic per file (recon.md, byte-level-patching.md, packers.md, server-config-and-updates.md, code-virtualization-and-custom-linkers.md, advanced-unpacking.md) and is loaded only when a specific step needs it. Everything sits under skills/apk-reverse/; repository-root tooling is maintenance scaffolding shared across skills, not part of the installed artifact. This layering is what makes it usable by an agent: context is spent on the decision at hand, not on a manual dump.

The most distinctive design element is what the README calls a procedure with gates. Four override rules (R1–R4) take precedence over the agent's current plan until evidence overrides them. A symptom index maps already-paid-for failures to reference files, and a matching row is defined as a stop signal — load that file before running another command rather than after three more attempts. Four gates (G1–G4) are actions with explicit pass criteria, forcing classification, environment verification, and a control build to happen before the first patch rather than after the third failure. A two-strike rule closes the loop: two failures of the same shape mean the model's hypothesis is wrong, not the parameters.

The skill's diagnostic scope reads like a distillation of expensive field lessons. It tries to decide quickly whether a request is achievable client-side at all — a paywall enforced by a server is not a patching problem — and to fix the deliverable's form before work starts, since an unrooted, self-contained artifact is a fundamentally different target than a machine-local fix. It explicitly catalogs the repack failure that looks like success: an app that installs, launches, and renders perfectly while every signed request is rejected, because the client derives its request-signing key from its own signing certificate. That class of trap, where the repack itself corrupts an authentication path, is exactly what a naive agent pipeline misses.

On the patching side, byte-level-patching.md argues for equal-length byte edits over method rebuilding — a claim the README marks as measured — and documents instruction-width traps that desynchronize a dex decode, the dex header integrity field order, the verifier's move-result rule, and the distinction between neutralizing a branch and redirecting it. This is surgical work at the layer that keeps the rest of the app intact, and the skill's stated principle is choosing the safest patch layer for a given change rather than the most impressive one. For hardened targets, packers.md covers rejection signals, measuring the validation boundary with single-variable tests, and choosing a native host.

Packed and virtualized targets get proportionate treatment. The skill distinguishes Java2C from an extraction shell before hours are burned hunting a decrypted DEX that never exists in the process lifetime — because the code was compiled into a .so. It handles whole classes converted to native declarations behind a private loader whose SONAME mismatches its filename, embedded self-decrypting payloads, and the Java-layer signature killer that logs success while a native check still kills the process. For genuine Dex VMP, it describes a known-plaintext differential approach that can prove a derived private-opcode table instead of asserting one.

Runtime instrumentation is treated with equal skepticism. The skill recognizes when userspace hooking cannot reach a check at all — raw svc syscalls or init_array-early detection — and what the layers above and below can actually do. It documents a hardened library that deliberately terminates the process with a fake null-dereference shape (fault addr 0x4) and the rule that a neutralization must not make the check fail to return, or the whole app freezes. On OLLVM-flattened native functions, Stalker-based instruction-level evidence gathering is described alongside the two measured ways it bites back on a real device. There is even a pragmatic escape hatch: calling a routine via emulated execution on the host or service-ifying it over Frida RPC when reversing costs more than invoking.

The first command the skill asks an agent to run is python skills/apk-reverse/scripts/doctor.py, which reports which tools exist in the environment, which scripts can actually run, and whether something already present is poisoning measurements. That environment-first posture also appears in the guidance to separate your own mistakes from the app's or server's problems — a feature-scoped failure is often a TLS/certificate issue on one code path, and device state, a dead device server, and clock drift masquerade the same way. For split APK / App Bundle sets, the skill covers reading the set off a device and signing every member with one keystore for pm install-multiple.

From a defensive and research-integrity standpoint, two elements stand out. First, the skill enforces a strict definition of done — six items, none of which is a clean log — plus stop conditions and a fallback ladder (system-level module, local RPC service, or an honest report with a stated boundary) for when a repack is genuinely blocked. Second, it has an explicit policy on publishing findings without publishing the target: a scanner that reports identity shapes with context, and a list of what must not be redacted — tools, libraries, protocol fields, CVEs, hardening products, public crackmes — because redacting those destroys the reusable knowledge. Exit codes gate commits.

Where this fits in an authorized workflow is clear: it is best understood as a process governor for agents doing APK analysis in assessment, malware triage, or app-security research contexts, where the alternative is an LLM freestyle-patching its way into silent breakage. Practitioners should note the honest scope statement — the skill knows which tools exist only as GUIs and instructs the agent to request a human rather than silently substituting a weaker method. With 1,445 stars, CI via ci.yml, and bilingual documentation (README.zh-CN.md), it is an actively maintained, well-structured piece of agent-era reverse-engineering tradecraft rather than a script dump.

Official project repository for newliver666/apk-reverse.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.