morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #1552] [MERGED] feat(adb): complete ADB device support for Android reverse engineering #2965

New issue

Closed

opened 2026-10-17 21:12:21 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:12:21 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1552
Author: @3QL
Created: 10/10/2026
Status: ✅ Merged
Merged: 10/10/2026
Merged by: @morluto

Base: main ← Head: feat/adb-device-acquisition

📝 Commits (5)

f514053 feat(adb): acquire installed APK sets from connected Android devices
9dc143e feat(adb): complete the adb surface with observation, transfer, and lifecycle tools
f1dcd03 fix(adb): quote remote shell operands and protect captured output
ae87d35 Merge remote-tracking branch 'origin/main' into HEAD
49a9a40 test(adb): cover bugreport destinations containing spaces

📊 Changes

48 files changed (+6862 additions, -1 deletions)

View changed files

📝 README.md (+1 -0)
📝 README_ar.md (+1 -0)
📝 README_de.md (+1 -0)
📝 README_es.md (+1 -0)
📝 README_fa.md (+1 -0)
📝 README_fr.md (+1 -0)
📝 README_id.md (+1 -0)
📝 README_ja.md (+1 -0)
📝 README_ko.md (+1 -0)
📝 README_pl.md (+1 -0)
📝 README_pt-BR.md (+1 -0)
📝 README_ru.md (+1 -0)
📝 README_th.md (+1 -0)
📝 README_tr.md (+1 -0)
📝 README_uk.md (+1 -0)
📝 README_vi.md (+1 -0)
📝 README_zh-TW.md (+1 -0)
📝 README_zh.md (+1 -0)
➕ docs/adb-device-analysis.md (+164 -0)
📝 docs/testing.md (+31 -0)

...and 28 more files

📄 Description

feat(adb): complete ADB device support for Android reverse engineering

Summary

Add an ADB family of 24 operations over the caller's adb binary, exposed through the same shared CLI/MCP workflows as every other analysis family. Every operation composes a fixed adb argument vector — caller values occupy positional arguments only and never reach a shell. REA never installs platform tools, never starts or manages emulators, and every result embeds the producing adb client identity (binary, selection source, version) so Evidence keeps producer provenance.

Device identity and state (read-only): inspect_adb_client · list_adb_devices (inferred emulator/physical kind with basis) · inspect_adb_device (getprop whitelist + ro.kernel.qemu) · inspect_adb_display · list_adb_features (hex GL versions) · list_adb_services (AIDL /-suffixed names) · list_adb_processes · inspect_adb_window (focus declarations) · read_adb_setting (device-side nulls reported as such) · read_adb_logcat (bounded dump, count/buffer/pid).

Find and acquire (read-only): resolve_adb_packages (substring search, e.g. whatsapp → com.whatsapp) · list_adb_packages · inspect_adb_package (dumpsys projection) · pull_adb_package (complete split APK set from pm path, each file SHA-256 digested, partial pulls keep per-file failure reasons) · pull_adb_file · push_adb_file (e.g. tools into /data/local/tmp; refuses existing targets without explicit overwrite; verifies via the device's own sha256sum) · capture_adb_screen (exec-out screencap -p, PNG dimensions) · collect_adb_bugreport (digested device archive).

Lifecycle for dynamic analysis (mutatesTarget declared): install_adb_package / uninstall_adb_package (preserving the device's Success/Failure [...] verdict verbatim) · start_adb_app (resolve-activity → am start -W) · start_adb_activity (action, URI, component, up to 16 typed extras as --es/--ez/--ei/--el/--ef) · stop_adb_app (am force-stop). The dynamic-analysis loop is now one surface: install → start → read_adb_logcat --pid → `stop → uninstall.

This implements the read-only-plus-lifecycle ADB stage of the Android roadmap #717. UI driving (tap/type/monkey) and device-driver installs remain deliberately out of scope; see the docs' follow-up-lanes note on pairing mobile-device-mcp / Frida (#1359) behind explicit mutation authority.

Honesty rules baked in

Inferences carry their basis: kind_basis (serial prefix / USB transport), role_basis: file_name for APK roles, device_reported_null for absent settings keys, device_digest_source when a device can't verify a push.
Device paths stay typed as device paths; only pulls/captures produce host-local paths, always with bytes + SHA-256.
Unparseable output is preserved (unparsed_lines + coverage: "partial"), never silently dropped; the first run against a real device caught three real format variants this way (AIDL / names, hex feature versions, adb version's colon-less Version line).
Transfer/lifecycle mutations are explicit and audited in TOOL_EFFECTS (mutatesTarget, non-idempotent); everything else is read-only with respect to the device.

Verification

130+ module/adapter/boundary tests: parser goldens, provider behavior through #!/bin/sh adb stubs (fixed-argv audits via logged argv files, digest mismatch → artifact_changed, overwrite refusals, cancellation before spawn, mistyped extras rejected pre-device), service admission/Evidence composition, CLI schema advertisement (24 commands), MCP schema parity with Ajv-validated examples and rejected unknown input.
Real-device lane (npm run verify:adb): adb 34.0.5-debian on Linux vs. an Android 14 (API 34) x86_64 emulator — every operation green: 287 binder services, 92 features, 337-process listing, bounded logcat, directory listings, a real two-APK split set pulled with byte-exact on-digest agreement, a push/pull roundtrip verified by the device's own sha256sum, a 1.3 MB screen capture with dimensions, dumpsys package projection, and the full lifecycle (unique resolve → launcher start via resolve-activity + am start -W → visible in ps → force-stop → uninstall → zero matches). System packages with non-base.apk names verify honest unknown-role reporting (73.9 MB com.android.settings).
check:fast, docs:generate, docs:check, and 3,400+ tests across the domain/services/adapters/composition projects pass. Two pre-existing environment failures in the firmware lane reproduce on a clean tree and are unrelated.

Docs

docs/adb-device-analysis.md: supply tools, 24-operation table with read/mutates classification, result semantics, budgets, follow-up lanes.
docs/testing.md: full verification record. README analysis table gains the "Android devices" row in English and all 17 translations.

Towards #717. No engine, SDK, or emulator installation; no new runtime dependencies.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1552 **Author:** [@3QL](https://github.com/3QL) **Created:** 10/10/2026 **Status:** ✅ Merged **Merged:** 10/10/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `feat/adb-device-acquisition` --- ### 📝 Commits (5) - [`f514053`](https://github.com/morluto/rea/commit/f514053112a19a66b0a845128366815ee2f95157) feat(adb): acquire installed APK sets from connected Android devices - [`9dc143e`](https://github.com/morluto/rea/commit/9dc143eeb736e020fab846a017eab641d2e690da) feat(adb): complete the adb surface with observation, transfer, and lifecycle tools - [`f1dcd03`](https://github.com/morluto/rea/commit/f1dcd0347cfb015546530d396b5b01e74ecb59e5) fix(adb): quote remote shell operands and protect captured output - [`ae87d35`](https://github.com/morluto/rea/commit/ae87d35cb2c103ad397250eaaedef063ca96aa65) Merge remote-tracking branch 'origin/main' into HEAD - [`49a9a40`](https://github.com/morluto/rea/commit/49a9a40847c9acb6b0aed92de657de8eee3274f4) test(adb): cover bugreport destinations containing spaces ### 📊 Changes **48 files changed** (+6862 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+1 -0) 📝 `README_ar.md` (+1 -0) 📝 `README_de.md` (+1 -0) 📝 `README_es.md` (+1 -0) 📝 `README_fa.md` (+1 -0) 📝 `README_fr.md` (+1 -0) 📝 `README_id.md` (+1 -0) 📝 `README_ja.md` (+1 -0) 📝 `README_ko.md` (+1 -0) 📝 `README_pl.md` (+1 -0) 📝 `README_pt-BR.md` (+1 -0) 📝 `README_ru.md` (+1 -0) 📝 `README_th.md` (+1 -0) 📝 `README_tr.md` (+1 -0) 📝 `README_uk.md` (+1 -0) 📝 `README_vi.md` (+1 -0) 📝 `README_zh-TW.md` (+1 -0) 📝 `README_zh.md` (+1 -0) ➕ `docs/adb-device-analysis.md` (+164 -0) 📝 `docs/testing.md` (+31 -0) _...and 28 more files_ </details> ### 📄 Description # feat(adb): complete ADB device support for Android reverse engineering ## Summary Add an ADB family of **24 operations** over the caller's `adb` binary, exposed through the same shared CLI/MCP workflows as every other analysis family. Every operation composes a **fixed adb argument vector** — caller values occupy positional arguments only and never reach a shell. REA never installs platform tools, never starts or manages emulators, and every result embeds the producing adb client identity (binary, selection source, version) so Evidence keeps producer provenance. **Device identity and state (read-only):** `inspect_adb_client` · `list_adb_devices` (inferred emulator/physical kind *with basis*) · `inspect_adb_device` (getprop whitelist + `ro.kernel.qemu`) · `inspect_adb_display` · `list_adb_features` (hex GL versions) · `list_adb_services` (AIDL `/`-suffixed names) · `list_adb_processes` · `inspect_adb_window` (focus declarations) · `read_adb_setting` (device-side nulls reported as such) · `read_adb_logcat` (bounded dump, count/buffer/pid). **Find and acquire (read-only):** `resolve_adb_packages` (substring search, e.g. `whatsapp` → `com.whatsapp`) · `list_adb_packages` · `inspect_adb_package` (dumpsys projection) · `pull_adb_package` (**complete split APK set** from `pm path`, each file SHA-256 digested, partial pulls keep per-file failure reasons) · `pull_adb_file` · `push_adb_file` (e.g. tools into `/data/local/tmp`; refuses existing targets without explicit overwrite; verifies via the device's own `sha256sum`) · `capture_adb_screen` (exec-out `screencap -p`, PNG dimensions) · `collect_adb_bugreport` (digested device archive). **Lifecycle for dynamic analysis (`mutatesTarget` declared):** `install_adb_package` / `uninstall_adb_package` (preserving the device's `Success`/`Failure [...]` verdict verbatim) · `start_adb_app` (resolve-activity → `am start -W`) · `start_adb_activity` (action, URI, component, up to 16 typed extras as `--es/--ez/--ei/--el/--ef`) · `stop_adb_app` (`am force-stop`). The dynamic-analysis loop is now one surface: *install → start → `read_adb_logcat --pid` → `stop → uninstall*. This implements the read-only-plus-lifecycle ADB stage of the Android roadmap #717. UI driving (tap/type/monkey) and device-driver installs remain deliberately out of scope; see the docs' follow-up-lanes note on pairing mobile-device-mcp / Frida (#1359) behind explicit mutation authority. ## Honesty rules baked in - Inferences carry their basis: `kind_basis` (serial prefix / USB transport), `role_basis: file_name` for APK roles, `device_reported_null` for absent settings keys, `device_digest_source` when a device can't verify a push. - Device paths stay typed as device paths; only pulls/captures produce host-local paths, always with bytes + SHA-256. - Unparseable output is preserved (`unparsed_lines` + `coverage: "partial"`), never silently dropped; the first run against a real device caught three real format variants this way (AIDL `/` names, hex feature versions, `adb version`'s colon-less `Version` line). - Transfer/lifecycle mutations are explicit and audited in `TOOL_EFFECTS` (`mutatesTarget`, non-idempotent); everything else is read-only with respect to the device. ## Verification - **130+ module/adapter/boundary tests**: parser goldens, provider behavior through `#!/bin/sh` adb stubs (fixed-argv audits via logged argv files, digest mismatch → `artifact_changed`, overwrite refusals, cancellation before spawn, mistyped extras rejected pre-device), service admission/Evidence composition, CLI schema advertisement (24 commands), MCP schema parity with Ajv-validated examples and rejected unknown input. - **Real-device lane** (`npm run verify:adb`): adb 34.0.5-debian on Linux vs. an Android 14 (API 34) x86_64 emulator — **every operation green**: 287 binder services, 92 features, 337-process listing, bounded logcat, directory listings, a real two-APK split set pulled with byte-exact on-digest agreement, a push/pull roundtrip verified by the device's own sha256sum, a 1.3 MB screen capture with dimensions, `dumpsys package` projection, and the full lifecycle (unique resolve → launcher start via `resolve-activity` + `am start -W` → visible in `ps` → force-stop → uninstall → zero matches). System packages with non-`base.apk` names verify honest `unknown`-role reporting (73.9 MB `com.android.settings`). - `check:fast`, `docs:generate`, `docs:check`, and 3,400+ tests across the domain/services/adapters/composition projects pass. Two pre-existing environment failures in the firmware lane reproduce on a clean tree and are unrelated. ## Docs - `docs/adb-device-analysis.md`: supply tools, 24-operation table with read/mutates classification, result semantics, budgets, follow-up lanes. - `docs/testing.md`: full verification record. README analysis table gains the "Android devices" row in English and all 17 translations. Towards #717. No engine, SDK, or emulator installation; no new runtime dependencies. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:12:21 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-31 01:07:18 +00:00

[PR #2965] [CLOSED] perf(process): reuse capture-local text normalization matchers #5522

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#2965

No description provided.

Rows
Columns