apkpatch

apkpatch is a small command-line workflow wrapper for APK security review and smali patch testing.

It hides the repetitive details around:

• decoding APKs with apktool
• initializing a clean git baseline for decoded smali
• rebuilding with apktool b
• aligning with zipalign
• signing with apksigner
• generating a non-interactive debug keystore
• verifying signatures
• installing with adb install -r

The tool does not modify smali for you. It manages the workflow around your manual smali/resource edits.

Install

From the repository root:

python3 -m pip install -e .

Then run:

apkpatch doctor

You can also run without installing:

PYTHONPATH=src python3 -m apkpatch doctor

External Tools

apkpatch expects these tools to exist:

• apktool
• java
• keytool
• zipalign
• apksigner
• adb for install only
• git for baseline/diff only

zipalign and apksigner are searched in this order:

1. $PATH
2. --build-tools-dir
3. $ANDROID_HOME/build-tools/*
4. $ANDROID_SDK_ROOT/build-tools/*
5. ~/Library/Android/sdk/build-tools/* on macOS

Basic Workflow

Decode an APK:

apkpatch decode app.apk -o app_workdir

By default this also creates a git repository inside app_workdir and commits the decoded APK as:

baseline: decoded apk

Make your smali/resource changes manually, then inspect them:

cd app_workdir
apkpatch diff

Build, align, sign, and verify:

apkpatch build \
  --generate-ks ~/.apkpatch/debug.keystore \
  --out dist/app-patched-signed.apk

Install:

apkpatch install

Or build and install in one step:

apkpatch build --install
apkpatch build --install -s DEVICE_SERIAL

Commands

doctor

Check tool discovery:

apkpatch doctor

decode

Decode an APK with apktool d:

apkpatch decode input.apk -o workdir

Useful options:

apkpatch decode input.apk -o workdir --force
apkpatch decode input.apk -o workdir --no-git

build

Build a decoded workdir:

apkpatch build

build defaults to the current directory. You can still pass a workdir explicitly:

apkpatch build workdir

Default output uses the decoded package name when available:

workdir/dist/com.example.app-signed.apk

Unsigned and aligned intermediate APKs are removed after a successful build by default.

If the package name cannot be inferred, apkpatch falls back to the workdir name.

Useful options:

apkpatch build --clean
apkpatch build --name review-false
apkpatch build --suffix review-false
apkpatch build --keep-intermediates
apkpatch build --out /tmp/review-false-signed.apk
apkpatch build --install

rebuild

Build again using metadata saved from the previous build:

apkpatch rebuild

sign

Sign an existing APK:

apkpatch sign unsigned.apk -o signed.apk --ks ~/.apkpatch/debug.keystore

align

Run only zipalign:

apkpatch align unsigned.apk -o aligned.apk

install

Install an APK:

apkpatch install signed.apk
apkpatch install signed.apk -s DEVICE_SERIAL

If no APK is provided, install defaults to last_signed_apk in the current workdir's .apkpatch.json:

apkpatch install
apkpatch install -s DEVICE_SERIAL

If --workdir is provided, install failures can include package-name hints:

apkpatch install signed.apk --workdir app_workdir

diff

Show changed files and smali/resource diffs:

apkpatch diff
apkpatch diff --stat

git-init

Initialize git tracking for an existing decoded workdir:

apkpatch git-init

Keystore Behavior

If no keystore is provided, apkpatch build uses:

~/.apkpatch/debug.keystore

If it does not exist, it is generated non-interactively with:

alias: apkpatchdebug
password: android

You can override:

apkpatch build \
  --ks ./debug-review.keystore \
  --alias debugreview \
  --ks-pass android \
  --key-pass android

Existing keystores are not overwritten unless:

--force-generate-ks

Signature Scheme v4

By default apkpatch disables APK Signature Scheme v4, so apksigner does not create a .idsig sidecar file.

Enable it explicitly:

apkpatch build --v4

Safety Notes

apkpatch is intended for local APK security review, reverse engineering, and patch validation on apps you are authorized to inspect.

It does not bypass platform security checks by itself. It only wraps common APK tooling and makes the workflow reproducible.