From 7261609f03d8ede2973f3cc405bf6a1c9a7aef29 Mon Sep 17 00:00:00 2001 From: MacTash Date: Thu, 24 Sep 2026 19:55:06 +0530 Subject: [PATCH] add profile filters and remove blind reports --- README.md | 17 ++-- apkinspect/blind.py | 190 ++++++++++++++++++----------------------- apkinspect/profiles.py | 27 +++++- tests/test_blind.py | 41 +++++++-- tests/test_common.py | 3 + 5 files changed, 154 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index a2534f5..3d2b21d 100644 --- a/README.md +++ b/README.md @@ -202,10 +202,11 @@ apkinspect --blind APK -o blind-output | Option | Default | Meaning | |---|---|---| | `APK` | required | Input APK or carrier ZIP | -| `-o, --outdir` | `blind-output` | Directory for `final.apk`, artifacts, and `report.json` | +| `-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`, @@ -213,14 +214,16 @@ manifest repair and the known family adapters such as `upd`, `staged`, `signed`, 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. +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 `/final.apk`; every attempt and skip reason is -written to `/report.json`, together with the built-in profile metadata -used for the run. +result is written to `/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 @@ -239,8 +242,8 @@ 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 same metadata is embedded in `blind-output/report.json` so a result can be -audited without reading the implementation. +The metadata is available directly from `profiles --json` for automation. +Variant names are reported, but key and password values are never emitted. ### `lcg` diff --git a/apkinspect/blind.py b/apkinspect/blind.py index 155cf53..0a87c7c 100644 --- a/apkinspect/blind.py +++ b/apkinspect/blind.py @@ -15,7 +15,7 @@ from . import axml, cloak, dpt, fogky, lcg, shard, signed, spk, staged, upd from .common import ToolError, read_file, write_file -from .profiles import BUILTIN_PROFILES, profile_report +from .profiles import AdapterProfile, BUILTIN_PROFILES, profile_by_name from .ui import UI MAX_INPUT_BYTES = 512 * 1024 * 1024 @@ -28,13 +28,9 @@ _ATTEMPT_TOKEN = '__APKINSPECT_ATTEMPT_DIR__' KNOWN_VARIANTS = { - 'upd': (('default', upd.DEFAULT_KEY.decode('ascii')),), - 'staged': (('default', staged.DEFAULT_PASSWORD),), - 'signed': (('default', signed.DEFAULT_XOR64.decode('ascii')),), - 'spk': (('default', spk.DEFAULT_KEY.decode('ascii')),), - 'fogky': (('default', fogky.DEFAULT_KEY.hex()),), - 'shard': (('default', shard.DEFAULT_KEY.decode('ascii')),), - 'cloak': (('hk+pk-default', ''),), + profile.name: profile.variants + for profile in BUILTIN_PROFILES + if profile.variants } @@ -59,15 +55,6 @@ def _safe_error(error: Exception) -> str: return message[:MAX_REPORTED_ERROR] or type(error).__name__ -def _safe_asset(value: Optional[str]) -> Optional[str]: - if not value: - return None - if len(value) <= 80: - return value - digest = hashlib.sha256(value.encode('utf-8')).hexdigest()[:12] - return '%s...' % (value[:32], digest) - - def _safe_member_name(name: str) -> str: normalized = name.replace('\\', '/') if not normalized or '\x00' in normalized: @@ -247,28 +234,24 @@ def _invoke(module: Any, argv: Sequence[str]) -> Tuple[int, str]: class BlindRunner: def __init__(self, input_path: str, outdir: str, max_depth: int, - max_attempts: int, max_assets: int): + max_attempts: int, max_assets: int, + requested_profiles: Optional[Sequence[str]] = None): self.input_path = os.path.abspath(input_path) self.outdir = os.path.abspath(outdir) self.max_depth = max_depth self.max_attempts = max_attempts self.max_assets = max_assets + self.requested_profiles = set(requested_profiles) if requested_profiles else None self.queue: Deque[Tuple[str, int]] = deque() self.queued: Set[str] = set() self.processed: Set[str] = set() self.attempted: Set[Tuple[str, str, str, str]] = set() - self.attempts: List[Dict[str, Any]] = [] self.attempt_count = 0 self.artifact_count = 0 self.final_path: Optional[str] = None os.makedirs(os.path.join(self.outdir, 'attempts'), exist_ok=True) os.makedirs(os.path.join(self.outdir, 'artifacts'), exist_ok=True) - def _record(self, command: str, depth: int, status: str, **fields: Any) -> None: - entry: Dict[str, Any] = {'command': command, 'depth': depth, 'status': status} - entry.update(fields) - self.attempts.append(entry) - def _queue(self, path: str, depth: int) -> bool: if not _regular_file(path) or os.path.getsize(path) > MAX_ENTRY_BYTES: return False @@ -306,6 +289,9 @@ def _staged_safe(self, path: str) -> bool: except (ToolError, UnicodeDecodeError, ValueError, TypeError): return False + def _profile_enabled(self, name: str) -> bool: + return self.requested_profiles is None or name in self.requested_profiles + def _try(self, name: str, module: Any, depth: int, input_digest: str, asset: str, argv: List[str], variant: str = 'default') -> bool: marker = (name, input_digest, asset, variant) @@ -323,24 +309,18 @@ def _try(self, name: str, module: Any, depth: int, input_digest: str, if isinstance(argument, str) else argument for argument in argv ] - result, error = _invoke(module, scoped_argv) + result, _ = _invoke(module, scoped_argv) outputs: List[str] = [] if result == 0: try: outputs = _collect_files(attempt_dir) - except ToolError as collection_error: + except ToolError: result = 1 - error = _safe_error(collection_error) - self._record(name, depth, 'success' if result == 0 else 'failed', - input_sha256=input_digest, asset=_safe_asset(asset), - variant=variant, - outputs=[os.path.relpath(path, self.outdir) for path in outputs], - error=error or None) if result != 0: return False for output in outputs: if is_final_apk(output): - self._finish(output, depth) + self._finish(output) return True if _regular_file(output) and zipfile.is_zipfile(output): self._queue_nested(output, depth) @@ -348,74 +328,91 @@ def _try(self, name: str, module: Any, depth: int, input_digest: str, self._queue(output, depth + 1) return False - def _try_variants(self, name: str, module: Any, depth: int, + def _try_variants(self, profile: AdapterProfile, module: Any, depth: int, input_digest: str, asset: str, argv_builder: Any) -> bool: - for variant, value in KNOWN_VARIANTS.get(name, (('default', ''),)): - if self._try(name, module, depth, input_digest, asset, + for variant, value in profile.variants or (('default', ''),): + if self._try(profile.name, module, depth, input_digest, asset, argv_builder(value), variant=variant): return True return False - def _finish(self, source: str, depth: int) -> None: + def _finish(self, source: str) -> None: if self.final_path is not None: return target = os.path.join(self.outdir, 'final.apk') write_file(target, read_file(source, 'final APK')) self.final_path = target - self._record('blind', depth, 'final', output=target) def _try_adapters(self, path: str, depth: int, digest: str, infos: Dict[str, zipfile.ZipInfo]) -> None: self._queue_nested(path, depth) names = set(infos) - if 'AndroidManifest.xml' in names and self._try( - 'axml-trim', axml, depth, digest, '', - ['axml-trim', path, '-o', self._attempt_output('axml.apk')]): + if (self._profile_enabled('axml-trim') + and 'AndroidManifest.xml' in names + and self._try( + 'axml-trim', axml, depth, digest, '', + ['axml-trim', path, '-o', self._attempt_output('axml.apk')])): return - if 'assets/update.enc' in names and self._try_variants( - 'upd', upd, depth, digest, 'assets/update.enc', - lambda key: ['upd', path, '-o', self._attempt_output('upd.payload'), - '--key', key]): + if (self._profile_enabled('upd') + and 'assets/update.enc' in names + and self._try_variants( + profile_by_name('upd'), upd, depth, digest, 'assets/update.enc', + lambda key: ['upd', path, '-o', self._attempt_output('upd.payload'), + '--key', key])): return - if 'assets/packed/meta.json' in names and self._staged_safe(path) and self._try_variants( - 'staged', staged, depth, digest, 'assets/packed/meta.json', - lambda password: ['staged', path, - '-o', self._attempt_output('staged.payload'), - '--password', password]): + if (self._profile_enabled('staged') + and 'assets/packed/meta.json' in names + and self._staged_safe(path) + and self._try_variants( + profile_by_name('staged'), staged, depth, digest, + 'assets/packed/meta.json', + lambda password: ['staged', path, + '-o', self._attempt_output('staged.payload'), + '--password', password])): return - if {'assets/0uym5nunf4giud61', 'assets/bvxg8rspej6aqybh/u0w4uogp'} <= names and self._try_variants( - 'signed', signed, depth, digest, 'signed-family', - lambda key: ['signed', path, '--outdir', self._attempt_output('signed'), - '--xor-key', key]): + if (self._profile_enabled('signed') + and {'assets/0uym5nunf4giud61', + 'assets/bvxg8rspej6aqybh/u0w4uogp'} <= names + and self._try_variants( + profile_by_name('signed'), signed, depth, digest, 'signed-family', + lambda key: ['signed', path, '--outdir', + self._attempt_output('signed'), '--xor-key', key])): return - if 'assets/nvcgehin' in names and self._try_variants( - 'cloak', cloak, depth, digest, 'assets/nvcgehin', - lambda key: ['cloak', path, '-o', self._attempt_output('cloak.payload')]): + if (self._profile_enabled('cloak') + and 'assets/nvcgehin' in names + and self._try_variants( + profile_by_name('cloak'), cloak, depth, digest, 'assets/nvcgehin', + lambda key: ['cloak', path, '-o', + self._attempt_output('cloak.payload')])): return binary_assets = sorted( (name for name in names if name.startswith('assets/') and name.endswith('.bin')), key=lambda name: (-infos[name].file_size, name)) - if binary_assets and self._try_variants( - 'spk', spk, depth, digest, binary_assets[0], - lambda key: ['spk', path, '-o', self._attempt_output('spk.body'), - '--asset', binary_assets[0], '--key', key]): + if (self._profile_enabled('spk') + and binary_assets + and self._try_variants( + profile_by_name('spk'), spk, depth, digest, binary_assets[0], + lambda key: ['spk', path, '-o', self._attempt_output('spk.body'), + '--asset', binary_assets[0], '--key', key])): return for asset in _candidate_assets(infos, self.max_assets): - if self._try_variants( - 'fogky', fogky, depth, digest, asset, - lambda key, asset=asset: [ - 'fogky', path, asset, - '-o', self._attempt_output('fogky-%d' % len(asset)), - '--key', key]): + if (self._profile_enabled('fogky') + and self._try_variants( + profile_by_name('fogky'), fogky, depth, digest, asset, + lambda key, asset=asset: [ + 'fogky', path, asset, + '-o', self._attempt_output('fogky-%d' % len(asset)), + '--key', key])): return - if self._try_variants( - 'shard', shard, depth, digest, asset, - lambda key, asset=asset: [ - 'shard', path, asset, - '-o', self._attempt_output('shard-%d' % len(asset)), - '--key', key]): + if (self._profile_enabled('shard') + and self._try_variants( + profile_by_name('shard'), shard, depth, digest, asset, + lambda key, asset=asset: [ + 'shard', path, asset, + '-o', self._attempt_output('shard-%d' % len(asset)), + '--key', key])): return - if asset.lower().endswith('.dat'): + if self._profile_enabled('lcg') and asset.lower().endswith('.dat'): try: data = _read_member(path, asset) except ToolError: @@ -437,7 +434,8 @@ def _try_adapters(self, path: str, depth: int, digest: str, os.unlink(lcg_input) except OSError: pass - if 'assets/OoooooOooo' in names: + if (self._profile_enabled('dpt') + and 'assets/OoooooOooo' in names): self._try('dpt', dpt, depth, digest, 'assets/OoooooOooo', ['dpt', path, '-o', self._attempt_output('dpt')]) @@ -446,18 +444,13 @@ def run(self) -> int: raise ToolError('input APK is not a regular file') if os.path.getsize(self.input_path) > MAX_INPUT_BYTES: raise ToolError('input APK exceeds the size limit') - self._record('blind', 0, 'started', input=self.input_path) - for profile in BUILTIN_PROFILES: - if not profile.blind_compatible: - self._record(profile.name, 0, 'skipped', reason=profile.description) if is_final_apk(self.input_path): - self._finish(self.input_path, 0) + self._finish(self.input_path) else: self._queue(self.input_path, 0) while self.queue and self.final_path is None: path, depth = self.queue.popleft() if depth > self.max_depth: - self._record('blind', depth, 'limit', reason='maximum depth reached') continue digest = _file_digest(path) if digest in self.processed: @@ -465,40 +458,17 @@ def run(self) -> int: self.processed.add(digest) try: infos = _archive_info(path) - except ToolError as error: - self._record('input', depth, 'invalid', input_sha256=digest, - error=_safe_error(error)) + except ToolError: continue self._try_adapters(path, depth, digest, infos) if self.attempt_count >= self.max_attempts and self.queue: - self._record('blind', depth, 'limit', reason='maximum attempts reached') self.queue.clear() - self._write_report() if self.final_path is None: print('blind: no structurally complete APK found') - print('blind: report %s' % os.path.join(self.outdir, 'report.json')) return 1 print('blind: final APK %s' % self.final_path) - print('blind: report %s' % os.path.join(self.outdir, 'report.json')) return 0 - def _write_report(self) -> None: - report = { - 'input': self.input_path, - 'final': self.final_path, - 'profiles': profile_report(), - 'limits': { - 'max_depth': self.max_depth, - 'max_attempts': self.max_attempts, - 'max_assets': self.max_assets, - }, - 'attempts': self.attempts, - } - path = os.path.join(self.outdir, 'report.json') - with open(path, 'w', encoding='utf-8') as stream: - json.dump(report, stream, indent=2, sort_keys=True) - stream.write('\n') - def register(sub): parser = sub.add_parser( @@ -507,17 +477,23 @@ def register(sub): ) parser.add_argument('apk', help='input APK or carrier ZIP') parser.add_argument('-o', '--outdir', default='blind-output', - help='directory for final.apk, artifacts, and report.json') + help='directory for final.apk and artifacts') parser.add_argument('--max-depth', type=_nonnegative, default=4, help='maximum recursive payload depth (default: 4)') parser.add_argument('--max-attempts', type=_positive, default=64, help='maximum command attempts (default: 64)') parser.add_argument('--max-assets', type=_nonnegative, default=16, help='maximum ranked assets per decryptor (default: 16)') + profile_choices = tuple(profile.name for profile in BUILTIN_PROFILES + if profile.blind_compatible) + parser.add_argument('--profile', action='append', choices=profile_choices, + dest='profiles', + help='limit blind discovery to a profile; repeat for multiple profiles') parser.set_defaults(func=run) def run(args) -> int: runner = BlindRunner(args.apk, args.outdir, args.max_depth, - args.max_attempts, args.max_assets) + args.max_attempts, args.max_assets, + getattr(args, 'profiles', None)) return runner.run() diff --git a/apkinspect/profiles.py b/apkinspect/profiles.py index f30b816..c545349 100644 --- a/apkinspect/profiles.py +++ b/apkinspect/profiles.py @@ -3,6 +3,11 @@ from dataclasses import asdict, dataclass from typing import Tuple +from . import fogky, shard, signed, spk, staged, upd + + +PROFILE_SCHEMA_VERSION = 1 + @dataclass(frozen=True) class AdapterProfile: @@ -14,6 +19,7 @@ class AdapterProfile: required_assets: Tuple[str, ...] = () description: str = '' blind_compatible: bool = True + variants: Tuple[Tuple[str, str], ...] = () BUILTIN_PROFILES = ( @@ -27,12 +33,14 @@ class AdapterProfile: ('upd', '{apk}', '-o', '{output}'), asset='assets/update.enc', description='repeating-XOR update.enc carrier', + variants=(('default', upd.DEFAULT_KEY.decode('ascii')),), ), AdapterProfile( 'staged', 'staged', 'staged', ('staged', '{apk}', '-o', '{output}'), asset='assets/packed/meta.json', description='metadata-described AES-CBC staged payload', + variants=(('default', staged.DEFAULT_PASSWORD),), ), AdapterProfile( 'signed', 'signed', 'assets', @@ -42,27 +50,32 @@ class AdapterProfile: 'assets/bvxg8rspej6aqybh/u0w4uogp', ), description='two-stage signed-family payload', + variants=(('default', signed.DEFAULT_XOR64.decode('ascii')),), ), AdapterProfile( 'cloak', 'cloak', 'asset', ('cloak', '{apk}', '-o', '{output}'), asset='assets/nvcgehin', description='layered AES-GCM/LCG/HKDF carrier', + variants=(('hk+pk-default', ''),), ), AdapterProfile( 'spk', 'spk', 'binary', ('spk', '{apk}', '-o', '{output}', '--asset', '{asset}'), description='SPKZ/SPK1 repeating-XOR container', + variants=(('default', spk.DEFAULT_KEY.decode('ascii')),), ), AdapterProfile( 'fogky', 'fogky', 'ranked', ('fogky', '{apk}', '{asset}', '-o', '{output}'), description='Fogky XOR/RC4/AES-GCM carrier', + variants=(('default', fogky.DEFAULT_KEY.hex()),), ), AdapterProfile( 'shard', 'shard', 'ranked', ('shard', '{apk}', '{asset}', '-o', '{output}'), description='single-blob repeating-XOR shard', + variants=(('default', shard.DEFAULT_KEY.decode('ascii')),), ), AdapterProfile( 'lcg', 'lcg', 'dat', @@ -99,7 +112,19 @@ class AdapterProfile: def profile_report() -> list: - return [asdict(profile) for profile in BUILTIN_PROFILES] + result = [] + for profile in BUILTIN_PROFILES: + item = asdict(profile) + item['variants'] = [name for name, _ in profile.variants] + result.append(item) + return result + + +def profile_by_name(name: str) -> AdapterProfile: + for profile in BUILTIN_PROFILES: + if profile.name == name: + return profile + raise KeyError(name) def register(sub): diff --git a/tests/test_blind.py b/tests/test_blind.py index 57bdba7..509b76e 100644 --- a/tests/test_blind.py +++ b/tests/test_blind.py @@ -1,7 +1,6 @@ import argparse import contextlib import io -import json import os import struct import tempfile @@ -10,7 +9,8 @@ import zipfile from apkinspect import blind -from apkinspect.__main__ import normalize_argv +from apkinspect.__main__ import build_parser, normalize_argv +from apkinspect.profiles import profile_by_name def make_manifest(): @@ -45,7 +45,7 @@ def test_final_apk_requires_manifest_and_dex(self): self.assertTrue(blind.is_final_apk(complete)) self.assertFalse(blind.is_final_apk(missing_dex)) - def test_existing_final_apk_is_copied_and_reported(self): + def test_existing_final_apk_is_copied(self): with tempfile.TemporaryDirectory() as directory: source = os.path.join(directory, 'source.apk') output = os.path.join(directory, 'output') @@ -64,10 +64,7 @@ def test_existing_final_apk_is_copied_and_reported(self): result = blind.run(args) self.assertEqual(result, 0) self.assertTrue(os.path.isfile(os.path.join(output, 'final.apk'))) - with open(os.path.join(output, 'report.json'), encoding='utf-8') as stream: - report = json.load(stream) - self.assertEqual(report['final'], os.path.join(output, 'final.apk')) - self.assertTrue(any(profile['name'] == 'fogky' for profile in report['profiles'])) + self.assertFalse(os.path.exists(os.path.join(output, 'report.json'))) def test_nested_apk_is_followed(self): with tempfile.TemporaryDirectory() as directory: @@ -121,8 +118,34 @@ def infolist(self): def test_known_variant_matrix_is_present(self): for command in ('upd', 'staged', 'signed', 'spk', 'fogky', 'shard', 'cloak'): - self.assertIn(command, blind.KNOWN_VARIANTS) - self.assertTrue(blind.KNOWN_VARIANTS[command]) + self.assertTrue(profile_by_name(command).variants) + self.assertEqual(blind.KNOWN_VARIANTS['upd'], + profile_by_name('upd').variants) + + def test_profile_filter_limits_discovery(self): + with tempfile.TemporaryDirectory() as directory: + source = os.path.join(directory, 'carrier.zip') + output = os.path.join(directory, 'output') + write_zip(source, {'assets/update.enc': b'not-a-payload'}) + args = argparse.Namespace( + apk=source, + outdir=output, + max_depth=1, + max_attempts=4, + max_assets=0, + profiles=['fogky'], + ) + with mock.patch.object(blind, '_invoke', return_value=(1, 'blocked')) as invoke: + with contextlib.redirect_stdout(io.StringIO()): + result = blind.run(args) + self.assertEqual(result, 1) + invoke.assert_not_called() + self.assertFalse(os.path.exists(os.path.join(output, 'report.json'))) + + def test_profile_option_is_repeatable(self): + args = build_parser().parse_args([ + 'blind', 'sample.apk', '--profile', 'fogky', '--profile', 'upd']) + self.assertEqual(args.profiles, ['fogky', 'upd']) def test_blind_alias_is_normalized(self): self.assertEqual(normalize_argv(['--blind', 'sample.apk']), diff --git a/tests/test_common.py b/tests/test_common.py index 01486b9..d3c567b 100644 --- a/tests/test_common.py +++ b/tests/test_common.py @@ -84,6 +84,9 @@ def test_profiles_json_lists_builtin_metadata(self): names = {profile['name'] for profile in profiles} self.assertIn('fogky', names) self.assertIn('aes-gcm-hkdf', names) + fogky_profile = next(profile for profile in profiles if profile['name'] == 'fogky') + self.assertEqual(fogky_profile['variants'], ['default']) + self.assertNotIn(fogky.DEFAULT_KEY.hex(), stdout.getvalue()) def test_missing_file_is_clean_error(self): stderr = io.StringIO()