apkinspect is a static analysis and unpacking CLI for Android APKs. It
contains focused transforms for observed packer, loader, and protector
families. It does not run an APK, emulate Android, or bypass application
signing.
The project is usable in two ways:
npm install -g https://github.com/throwshotputaway-cmd/apkinspect.gitfor a direct repository installation that exposes theapkinspectcommand.python -m pip install .when Python packaging is preferred.
Both paths install the complete runtime command set. There are no optional command dependency groups to select.
- Python 3.9 or newer, including
venvandpip. - Node.js 18 or newer when installing through npm.
- Network access during installation so npm and pip can download runtime packages.
- Android SDK
dexdumpis an additional external tool forsplitkey; it is not bundled or invoked automatically.
npm provides the command wrapper and bootstrap process. It does not bundle a Python interpreter, so Python must already be installed and discoverable.
Install directly from the repository:
npm install --global https://github.com/throwshotputaway-cmd/apkinspect.git
apkinspect --help
apkinspect --versionThis installs the repository directly and exposes the same command as a local
checkout installation. Use the full apkinspect repository name and the HTTPS
URL above; npm's github: shorthand may attempt SSH and require a GitHub key.
From a checkout of this repository, the equivalent local installation is:
npm install --global .
apkinspect --helpFor a project-local installation:
npm install
npx apkinspect --helpThe launcher creates an isolated Python environment inside the installed
package on first use and installs apkinspect plus all runtime dependencies
there. It does not modify the user's global Python environment.
If the Python executable is not on PATH, set APKINSPECT_PYTHON before
running apkinspect. For example, in PowerShell:
$env:APKINSPECT_PYTHON = 'C:\Python312\python.exe'
apkinspect --helpOn macOS and Linux, use the equivalent environment variable:
APKINSPECT_PYTHON=/path/to/python3 apkinspect --helpAPKINSPECT_VENV can be set when a different private environment directory is
needed. The default is .apkinspect-venv inside the installed npm package.
The launcher checks for its private environment on first use and runs the
Python bootstrap automatically. There is no npm lifecycle hook, so installing
directly from GitHub does not require npm script-policy exceptions. The first
apkinspect command may take longer while Python dependencies are installed.
Install every runtime dependency and the command entry point directly:
python -m pip install .
apkinspect --helpFrom a checkout, an editable installation is useful for development:
python -m pip install -e .The legacy requirements file is also a complete runtime installation:
python -m pip install -r requirements.txtContributor tools are separate from runtime command dependencies:
python -m pip install -e ".[dev]"Every normal installation includes:
| Package | Used by |
|---|---|
cryptography |
AES, HMAC, and GCM/CBC/CTR transforms |
androguard |
dpt DEX parsing and method mapping |
lief |
elforacle ELF parsing |
capstone |
elforacle x86-64 disassembly |
rich |
terminal status and progress rendering |
dexdump remains an external prerequisite for creating the input consumed by
splitkey. No other Android build tools are required by the commands below.
apkinspect <command> [options]
apkinspect --version
apkinspect --help
apkinspect <command> --help
The equivalent Python-module form is useful in a source checkout:
python -m apkinspect <command> [options]
Common options may appear before or after the command:
apkinspect --no-color <command> [options]
apkinspect --quiet <command> [options]
apkinspect --progress auto|always|never <command> [options]
--no-colordisables ANSI colors.NO_COLORhas the same effect.--quiet/-qsuppresses status and progress messages.--progress autoenables progress on an interactive terminal.--progress alwaysforces progress/status output even when redirected.--progress neverdisables progress rendering for automation.- Status and progress go to stderr. Command result reports go to stdout, so
--quietdoes not remove those result lines.
Successful commands return exit code 0. Invalid or foreign input returns
1 with a concise error. An interrupted command returns 130.
Output files are written atomically. ZIP verification checks ZIP structure and
entry integrity; it does not validate an Android manifest or APK signatures.
--expect dex checks the DEX magic, while auto recognizes ZIP or DEX output.
Direct archive asset reads are capped at 256 MiB per member before decompression.
| Command | Purpose |
|---|---|
blind |
Try compatible static unpackers and follow payloads to a final APK |
profiles |
List built-in adapter metadata for discovery and automation |
lcg |
Decrypt an LCG stream-cipher .dat blob |
upd |
Decrypt an update.enc repeating-XOR carrier |
shard |
Decrypt a repeating-XOR staged asset |
spk |
Unwrap an SPK XOR/DEFLATE blob |
staged |
Reassemble, decrypt, hash-check, and inflate staged parts |
fogky |
Decrypt XOR/RC4x4/AES-GCM assets and containers |
signed |
Recover the two signed-family stages |
oracle |
Decode numeric DEX string-oracle call sites |
splitkey |
Reconstruct split-array keys from dexdump output |
elforacle |
Extract indexed XOR strings from an x86-64 .so |
midctr |
Decrypt mid-counter AES-CTR assets |
cloak |
Unwrap multi-layer AES-GCM/LCG/HKDF assets |
aes-gcm-hkdf |
Decrypt direct salt/nonce AES-GCM/HKDF assets |
chunked-aes-gzip |
Reassemble and decrypt numbered AES-CBC/gzip chunks |
xor-gzip |
Decrypt repeating-XOR plus gzip assets |
dpt |
Restore dpt-shell method bodies statically |
axml-trim |
Rebuild an APK with a trimmed binary manifest |
Runs a bounded, static discovery pipeline over an APK. It sweeps the repository's known family keys/passwords across compatible transforms, follows valid ZIP/APK artifacts recursively, and stops when it finds a structurally complete APK. It never runs, installs, or emulates the sample.
apkinspect blind APK -o blind-output [options]
apkinspect --blind APK -o blind-output
| Option | Default | Meaning |
|---|---|---|
APK |
required | Input APK or carrier ZIP |
-o, --outdir |
blind-output |
Directory for final.apk and artifacts |
--max-depth |
4 |
Maximum recursive payload depth |
--max-attempts |
64 |
Maximum command attempts |
--max-assets |
16 |
Maximum ranked assets tried per decryptor |
--profile |
all compatible profiles | Limit discovery to one profile; repeat for multiple profiles |
The pipeline first checks whether the input is already complete. It then tries
manifest repair and the known family adapters such as upd, staged, signed,
cloak, spk, fogky, shard, lcg, and dpt when their expected assets
exist. Encrypted archive members are skipped individually, so readable payload
assets can still be tested. Successful ZIP outputs and nested .apk members
are queued for further analysis, with digest-based cycle detection and the
configured limits. Use --profile when a run should stay within a known
adapter family. Run apkinspect profiles --json separately when the built-in
profile metadata is needed for automation.
A result is accepted as final only when the ZIP passes integrity checks, the
root binary AndroidManifest.xml parses, and classes.dex has a coherent DEX
header. Signatures and Android installation validity are not verified. The
result is written to <outdir>/final.apk. The command does not generate a
report file; it reports only the final APK path or that no complete APK was
found.
Commands requiring sample-specific keys or offsets (aes-gcm-hkdf,
chunked-aes-gzip, xor-gzip, and midctr) are reported as skipped rather
than brute-forced. blind returns 0 when it finds a final APK and 1 when
the bounded search finds none.
Lists the built-in adapter metadata used by bounded discovery. The output is plain text by default and can be consumed by automation as JSON:
apkinspect profiles
apkinspect profiles --json
Each profile records its command module, trigger type, default asset or required
assets, command template, and whether it is safe for keyless blind discovery.
The metadata is available directly from profiles --json for automation.
Variant names are reported, but key and password values are never emitted.
Decrypts a standalone encrypted .dat blob using a linear congruential
stream. Extract the blob from the carrier APK before running this command;
the command does not open an APK itself.
apkinspect lcg INPUT -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
INPUT |
required | Standalone encrypted file |
-o, --output |
required | Plaintext output path |
--seed |
0x4394D |
Initial LCG state; accepts base-0 integer syntax |
--header |
16 |
Bytes skipped before decryption |
--no-verify |
off | Allow output that is not a valid ZIP |
The command applies the LCG update and XORs the high state byte with each
payload byte. A nonstandard prefix emits a warning but does not stop
processing. Verification is enabled by default, so the normal result should
be a healthy ZIP/APK; use --no-verify only for an intermediate blob.
Decrypts the conventional assets/update.enc carrier with a repeating XOR
key. This is usually the first layer around an inner APK.
apkinspect upd APK -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Decrypted output path |
--asset |
assets/update.enc |
Asset path inside the APK |
--key |
family default | Literal UTF-8 repeating-XOR key |
--no-verify |
off | Allow output that is not a valid ZIP |
The key is text, not hex. Pass a sample-specific key with --key when the
carrier does not use the family default. Output is verified as a ZIP unless
verification is disabled.
Decrypts one asset in a repeating-XOR staged family. The stream offset lets multiple shards be decrypted as one logical byte stream.
apkinspect shard APK ASSET -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
ASSET |
required | Asset path inside the APK |
-o, --output |
required | Output path |
--key |
family default | Literal UTF-8 repeating-XOR key |
--offset |
0 |
Initial stream offset |
--no-verify |
off | Allow output that is not a valid ZIP |
The byte at position i is XORed with key[(i + offset) % len(key)]. Use
the same key and an increasing offset when reconstructing a multi-shard
chain.
Unwraps the SPK carrier format. It selects an encrypted .bin asset,
repeating-XOR decrypts it, verifies the SPKZ wrapper, inflates the DEFLATE
stream, verifies the inner SPK1 marker, and writes the inflated body.
apkinspect spk APK -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Inflated SPK body |
--asset |
largest assets/*.bin |
Exact asset to process |
--key |
family default | Literal UTF-8 XOR key |
The command validates the complete DEFLATE stream and does not accept
trailing bytes. It writes the SPK1 body; it does not automatically extract
a nested shell ZIP or DEX from that body.
Reassembles metadata-described encrypted parts, decrypts each part with AES-CBC, checks compressed and original SHA-256 hashes, inflates the result, and verifies the final ZIP.
apkinspect staged APK -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Inflated inner APK/ZIP |
--password |
family default | Password used to derive the AES key |
--asset-dir |
assets/packed |
Directory containing parts and metadata |
--meta |
meta.json |
Metadata filename inside --asset-dir |
Metadata is a JSON object with a files list. Every file entry must contain
file, compressedSha256, and originalSha256. Parts are decrypted strictly
in list order. Each part supplies its first 16 bytes as its IV; the AES key
is derived from the password. Wrong ordering, hashes, padding, compression,
or ZIP data fails before the output is replaced.
Decrypts the Fogky-style layered asset: an XOR pad, four RC4 KSA passes, and
AES-GCM. It also understands MSZ1 containers containing named records.
apkinspect fogky APK ASSET -o OUTPUT [--key HEX] [--raw]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
ASSET |
required | Encrypted asset path |
-o, --output |
required | File, or directory for MSZ1 |
--key |
family default | 16-, 24-, or 32-byte AES-GCM key as hex |
--raw |
off | Write decrypted bytes without unpacking MSZ1 |
For an MSZ1 container, the output must be a directory. Entry names are
flattened to safe basenames, duplicate names are rejected, and each record is
written separately. For non-container plaintext or --raw, the output is a
single file. ZIP-looking records are tested diagnostically but are still
written if they are not a valid ZIP.
Recovers the two-stage signed-family payload. Stage 1 is repeating-XOR
encrypted and checked for dex\n; stage 2 is AES-CBC encrypted with a key
derived from the stage-2 asset name and is checked as a ZIP.
apkinspect signed APK [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
--outdir |
. |
Directory for stage1.dex and stage2.zip |
--stage1 |
family path | Stage-1 asset path |
--stage2 |
family path | Stage-2 asset path |
--xor-key |
family default | Literal UTF-8 stage-1 XOR key |
This command handles the two configured family assets only. It writes
stage1.dex before attempting stage 2, so a later failure can leave a
partial output directory. It does not extract the classes inside the final
ZIP or rebuild an APK.
Scans a standalone classes.dex for numeric string-oracle call sites. It
finds seeds associated with the selected method, applies the supported
signed-family decoder, and reports readable results.
apkinspect oracle CLASSES.DEX [options]
| Option | Default | Meaning |
|---|---|---|
CLASSES.DEX |
required | Extracted DEX file, not an APK |
--method |
family method name | Exact oracle method name |
--min-score |
0.0 |
Minimum readability score to report |
-o, --output |
stdout | Optional UTF-8 result file |
The scanner is pattern-based rather than a complete Dalvik disassembler. It uses the longest DEX string as the encoded blob and deduplicates seeds in file order. If the output file is requested but no result matches, the file is still created.
Reconstructs a key assembled from separate const and aput-byte writes in
dexdump -d output.
apkinspect splitkey DEXDUMP_DUMP --class SUBSTRING --method METHOD [options]
| Option | Default | Meaning |
|---|---|---|
DEXDUMP_DUMP |
required | Text output from Android SDK dexdump -d |
--class |
required | Class descriptor substring |
--method |
required | Key-builder method name |
--size |
32 |
Key length in bytes |
-o, --output |
none | Optional raw key file |
The command always prints the recovered key as hex. Supplying -o also
writes the raw key bytes. Generate the input separately, for example:
dexdump -d classes.dex > classes.dump.txt
apkinspect splitkey classes.dump.txt --class MainActivity --method keyBuilder -o key.binThis is a focused text parser, not general Dalvik data-flow analysis.
Extracts indexed repeating-XOR strings from a protector native library. It targets the x86-64 ELF64 little-endian slice, locates the JNI oracle jump table, walks its setup instructions, and writes decoded strings.
apkinspect elforacle SOFILE -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
SOFILE |
required | Native ELF .so file |
-o, --output |
required | UTF-8 decoded-string output |
--func |
getNativeStr |
Dynamic-symbol substring to match |
--bound |
auto | Maximum string index; auto-read from a comparison |
--default-keylen |
12 |
Fallback key length in bytes |
The library must retain usable section headers plus .text and .rodata.
The command tries mirrored data/key register conventions and keeps the more
readable result. Unsupported dynamic patterns are reported as undecoded
entries instead of being silently presented as recovered text.
Decrypts a nonstandard mid-counter AES-CTR asset. The command can accept a hex key or read 16 raw key bytes directly from a native library at a literal file offset.
apkinspect midctr APK -o OUTPUT (--key HEX | --so FILE) [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Decrypted output |
--asset |
family path | Encrypted asset path |
--key |
— | 16-byte AES key as hex |
--so |
— | Native file containing the 16 key bytes |
--key-off |
0x17440 |
Literal file offset used with --so |
--const |
family constant | Eight-byte counter constant |
--no-verify |
off | Allow output that is not a valid ZIP |
--key and --so are mutually exclusive. --key-off is not an ELF virtual
address; use the actual file offset. The default verification expects a ZIP,
although it does not enforce Android-specific APK contents.
Unwraps the multi-stage cloak payload: AES-GCM, an inverse seeded LCG permutation, nibble transformation, a SHA-256 counter stream, and a final HMAC-derived AES-GCM layer.
apkinspect cloak APK -o OUTPUT [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Decrypted output |
--asset |
family path | Outer encrypted asset |
--hk |
family default | Master key for the index stage |
--pk |
family default | Master key for the APK stage |
--kind |
try P then H | H, P, or an integer kind byte |
--expect |
auto |
auto, apk, or dex output validation |
When --kind is omitted, the command tries the configured HK/PK combinations.
The first plaintext byte is a flag; odd flags trigger gzip or DEFLATE
inflation. apk fully validates a ZIP, dex checks DEX magic, and auto
recognizes either common output shape. Use sample-specific keys when the
family defaults do not match.
Decrypts a direct salt/nonce AES-GCM blob using an HMAC-SHA256-derived key. The key text is an obfuscated hex representation: its first byte is a prefix used to decode the remaining hex bytes.
apkinspect aes-gcm-hkdf APK ASSET -o OUTPUT (--hk TEXT | --hk-file FILE) [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
ASSET |
required | Encrypted asset path |
-o, --output |
required | Output file |
--hk |
— | Obfuscated key text as ASCII hex |
--hk-file |
— | File containing the obfuscated key text |
--kind |
H |
H, P, or an integer kind byte |
--expect |
dex |
auto, apk, or dex output validation |
The blob layout is a 16-byte salt, 12-byte nonce, and AES-GCM ciphertext/tag.
The derived key uses HMAC-SHA256(salt, key) followed by
HMAC-SHA256(PRK, kind || 0x01), with salt + kind as AAD. The first
plaintext byte is a compression flag and is removed. Use --hk-file for
recovered material instead of putting it in shell history.
Reads a numbered sequence of APK assets, concatenates them, XORs the combined
stream with SHA-256(key), decrypts AES-CBC, removes PKCS#7 padding, and
inflates gzip.
apkinspect chunked-aes-gzip APK -o OUTPUT (--key HEX | --key-file FILE) [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
-o, --output |
required | Inflated payload |
--key |
— | 16-, 24-, or 32-byte AES key as hex |
--key-file |
— | File containing the AES key hex |
--prefix |
assets/vbfk/iyxu_ |
Chunk path prefix |
--suffix |
.png |
Chunk path suffix |
--start |
0 |
First decimal chunk index |
--count |
10 |
Number of consecutive chunks |
--expect |
apk |
auto, apk, or dex output validation |
Chunk names are exactly <prefix><start+i><suffix> with ordinary decimal
indices. The default apk expectation fully validates the inflated ZIP but
does not check Android-specific manifest or signature content.
Decrypts an asset with a repeating XOR key and then requires standard gzip compression.
apkinspect xor-gzip APK [ASSET] -o OUTPUT (--key HEX | --key-file FILE) [options]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Carrier APK |
ASSET |
assets/f89710c8 |
Encrypted asset path |
-o, --output |
required | Inflated output |
--key |
— | Repeating-XOR key as hex |
--key-file |
— | File containing the key hex |
--expect |
dex |
auto, apk, or dex output validation |
Any nonempty decoded key length is accepted. Raw zlib without a gzip wrapper
is rejected. Use auto when the same transform can produce either a ZIP or
DEX, or apk when the result must be a structurally valid ZIP.
Statically restores method bodies from a dpt-shell packed APK. It reads the
configured bytecode store, extracts DEX files appended to the stub
classes.dex, matches method indexes to code capacity, patches instruction
bytes, and repairs DEX SHA-1/Adler-32 headers.
apkinspect dpt APK [-o OUTDIR] [--oooo ASSET]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Packed APK |
-o, --outdir |
unpacked |
Directory for restored classes*.dex |
--oooo |
assets/OoooooOooo |
Bytecode-store asset |
Both standard records and the size-first XOR-0x6f variant are supported.
Sections must map exactly to a DEX by complete code-capacity fit. The output
is a directory of DEX files, not a signed APK.
Rebuilds an APK after truncating a binary AndroidManifest.xml immediately
after its first END_NAMESPACE chunk. This can remove filler chunks that
confuse some parsers.
apkinspect axml-trim APK -o OUTPUT [--entry AndroidManifest.xml]
| Option | Default | Meaning |
|---|---|---|
APK |
required | Input APK |
-o, --output |
required | Rebuilt APK path |
--entry |
AndroidManifest.xml |
Binary manifest entry to trim |
The input entry must begin with binary AXML magic. The command rebuilds a ZIP and does not preserve arbitrary ZIP metadata or APK v2/v3 signing blocks. Resign the output before attempting to install it on a device.
- Output files are written to a temporary sibling and atomically replaced.
- Archive-derived paths are checked for traversal, absolute paths, and unsafe names before extraction.
- ZIP output is tested with
zipfile.testzip()unless a command explicitly disables verification. - Empty ZIP containers are accepted as valid ZIPs.
apk/zipmeans ZIP validation, not Android manifest or signature validation.dexchecks thedex\nmagic;autorecognizes ZIP or DEX magic.- Recovered keys and decrypted payloads should be treated as sensitive. Prefer key files, avoid shell history, and do not commit sample material.
axml-trimanddptdo not produce an installable signed APK; signing, rebuilding, and device installation remain separate steps.
Run the Python test suite and static checks from a checkout:
python -m unittest discover -s tests -v
python -m compileall -q apkinspect tests
python -m ruff check .
python -m mypy
python -m buildValidate the npm package:
npm install
npm pack --dry-runTo exercise the complete first-run path, use a disposable environment with
Python and network access, then run apkinspect --version after installation.