Metadata-Version: 2.4
Name: navig-mobile
Version: 0.5.0
Summary: NAVIG Mobile — pro-grade Android + iOS device operations: connect, device info, apps, file pull, screenshots, backups, plus forensics / spyware-scan / root-jailbreak assist / OSINT, and app UI automation (a11y snapshots, tap/fill, `ui assert` machine checks, evidence capture). Wired into `navig mobile` (+ `navig android` / `navig ios`). A first-party navig plugin (free, toggleable).
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,android,ios,mobile,adb,device
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.11.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: android
Requires-Dist: adbutils>=2.10.0; extra == "android"
Provides-Extra: ios
Requires-Dist: pymobiledevice3>=9.0.0; extra == "ios"
Provides-Extra: all
Requires-Dist: navig-mobile[android,ios]; extra == "all"
Dynamic: license-file

# navig-mobile

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Pro-grade Android + iOS device operations: connect, device info, apps, file pull, screenshots, backups, plus forensics / spyware-scan / root-jailbreak assist / OSINT, and app UI automation (a11y snapshots, tap/fill, `ui assert` machine checks, evidence capture). Wired into `navig mobile` (+ `navig android` / `navig ios`).

**Works on its own** — its own CLI, no navig required · v0.5.0 · [PyPI](https://pypi.org/project/navig-mobile/)

**On its own** (no navig needed)

```bash
pip install navig-mobile
navig-mobile --help   # no navig needed
```

**With navig**

```bash
pip install "navig[mobile]"
navig mobile --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig android connect` | adb connect over TCP/IP. |
| `navig android fastboot` | Pass arguments straight through to the fastboot binary (device in bootloader). |
| `navig android logcat` | Show recent Android logcat lines. |
| `navig android reboot` | Reboot the device (into the bootloader/recovery for rooting flows). |
| `navig android sideload` | adb sideload a zip (device must be in recovery). Consent + --yes required. |
| `navig ios crashlogs` | Pull (or list) iOS crash reports. |
| `navig ios dfu` | Guide entering DFU mode (button timing is physical — can't be automated). |
| `navig ios instruments` | Drive DVT instruments (proclist/applist/kill/signal/…) — passthrough to |
| `navig ios pcap` | Capture device network traffic to a .pcap (Ctrl-C to stop). |
| `navig ios recovery` | Enter/exit iOS Recovery mode (drives pymobiledevice3 restore enter/exit). |
| `navig ios syslog` | Stream live iOS syslog (Ctrl-C to stop). |
| `navig mobile android connect` | adb connect over TCP/IP. |
| `navig mobile android fastboot` | Pass arguments straight through to the fastboot binary (device in bootloader). |
| `navig mobile android logcat` | Show recent Android logcat lines. |
| `navig mobile android reboot` | Reboot the device (into the bootloader/recovery for rooting flows). |
| `navig mobile android sideload` | adb sideload a zip (device must be in recovery). Consent + --yes required. |
| `navig mobile apps` | Installed apps: list · install <ipa/apk> · uninstall <id> · info <id> · extract <id>. |
| `navig mobile backup` | Device backup: create a full backup, or list past backups. |
| `navig mobile battery` | Battery level. |
| `navig mobile case` | List investigation cases, or show one's evidence manifest. |
| `navig mobile connect` | Connect to an Android device over TCP/IP (adb connect). |
| `navig mobile consent` | Record/show/revoke authorization to investigate a device (required before |
| `navig mobile dev` | Developer tools — shell, enable dev-mode, frida (list/attach/spawn), objection. |
| `navig mobile devices` | List every connected/paired Android + iOS device. |
| `navig mobile doctor` | Toolchain health — what's installed for Android/iOS ops and how to get the rest. |
| `navig mobile evidence` | List a case's evidence (or --verify their integrity). |
| `navig mobile forensics` | Consent-gated logical acquisition + artifact parsing (iLEAPP/ALEAPP) → case dir. |
| `navig mobile fs` | Device filesystem: ls <remote> · pull <remote> <local> · push <local> <remote>. |
| `navig mobile info` | Unified device info (auto-detects the connected platform). |
| `navig mobile ios crashlogs` | Pull (or list) iOS crash reports. |
| `navig mobile ios dfu` | Guide entering DFU mode (button timing is physical — can't be automated). |
| `navig mobile ios instruments` | Drive DVT instruments (proclist/applist/kill/signal/…) — passthrough to |
| `navig mobile ios pcap` | Capture device network traffic to a .pcap (Ctrl-C to stop). |
| `navig mobile ios recovery` | Enter/exit iOS Recovery mode (drives pymobiledevice3 restore enter/exit). |
| `navig mobile ios syslog` | Stream live iOS syslog (Ctrl-C to stop). |
| `navig mobile jailbreak` | Jailbreak assist (iOS): status (checkm8 eligibility + dev-mode) · guide (palera1n/checkra1n). |
| `navig mobile logs` | Device log — recent logcat (Android) or live syslog (iOS). |
| `navig mobile media` | Pull the camera roll / DCIM off the device (consent-gated). |
| `navig mobile mirror` | Mirror/control the screen (scrcpy on Android). |
| `navig mobile osint` | Device-anchored OSINT: identity · app-privacy report · combined report. |
| `navig mobile pair` | Pair a device — Android wireless (`adb pair host:port`), else guidance. |
| `navig mobile restore` | Restore a backup — DESTRUCTIVE (overwrites device data). Consent + --yes required. |
| `navig mobile root` | Rooting assist (Android): status · guide · unlock · flash. Never one-click — |
| `navig mobile scan` | Scan a device/backup for spyware with MVT (Pegasus/mercenary IOCs). Consent-gated. |
| `navig mobile screenshot` | Capture the device screen to a PNG. |
| `navig mobile storage` | Storage usage. |
| `navig mobile ui apps` | List launchable apps for a platform. |
| `navig mobile ui assert` | Assert the current screen shows (or --gone: hides) a text/ref — the |
| `navig mobile ui close` | End the current UI session. |
| `navig mobile ui devices` | List app-automation targets (simulators / emulators / devices). |
| `navig mobile ui doctor` | agent-device's own environment check (SDKs, drivers, permissions). |
| `navig mobile ui exec` | Escape hatch — pass raw arguments straight to agent-device. |
| `navig mobile ui fill` | Fill a text field identified by its snapshot ref. |
| `navig mobile ui open` | Start a UI session bound to an app — snapshot/tap/… then act on it. |
| `navig mobile ui press` | Press a device button / key. |
| `navig mobile ui record` | Record your manual flow into a replayable .ad script (interactive). |
| `navig mobile ui replay` | Replay a recorded .ad script (streams progress). |
| `navig mobile ui screenshot` | Capture the app screen to a PNG (app-context — distinct from the raw |
| `navig mobile ui scroll` | Scroll the current view. |
| `navig mobile ui snapshot` | Accessibility snapshot with element refs (@e1…) — the agent's eyes. |
| `navig mobile ui tap` | Tap an element by its snapshot ref. |
| `navig mobile ui type` | Type text into the currently focused field. |
| `navig mobile ui wait` | Wait for the UI to settle. |
| `navig mobile watch` | Watch for device arrival/removal until interrupted (Ctrl-C). |

</details>

<!-- navig:plugin-card:end -->

Pro-grade **Android + iOS device operations** for NAVIG — a "3uTools for both
platforms" wired natively into the `navig` CLI. Connect a phone or tablet and
inspect it, pull its data, back it up, investigate it, scan it for spyware, and
(carefully) unlock/root it — all through one command surface.

```
navig mobile devices              # every connected/paired Android + iOS device
navig mobile info                 # unified device info (auto-detects platform)
navig mobile apps list            # installed apps
navig mobile fs pull <remote> .   # pull files off the device
navig mobile screenshot           # grab the screen
navig mobile backup create        # full backup  ·  restore <src> (consent + --yes)
navig mobile doctor               # toolchain health + install guidance
navig mobile ui open MyApp -p android   # drive/verify an app UI (agent-device)
navig mobile ui snapshot -i       # a11y tree with element refs → tap @e2 · fill @e3 "…"
navig android logcat              # platform-only ops live under android/ios…
navig ios crashlogs               #   …and as convenience alias verbs
```

## Design

- **Zero hard third-party deps in the base install** — Apache-2.0 clean, and
  `navig help` stays fast. Engines load lazily only when a device is touched.
- **Two permissively-licensed Python engines**, installed via extras:
  - `pip install "navig-mobile[android]"` → [`adbutils`](https://github.com/openatx/adbutils) (Android over ADB)
  - `pip install "navig-mobile[ios]"` → [`pymobiledevice3`](https://github.com/doronz88/pymobiledevice3) (iOS over lockdown/usbmux — the "3uTools" engine)
  - `pip install "navig-mobile[all]"` → both
- **Everything else is detected, never bundled** — the `adb`/`fastboot`/`scrcpy`
  binaries, MVT (spyware), frida/objection (instrumentation), iLEAPP/ALEAPP
  (forensic parsing), and **agent-device** (app UI automation — Node, MIT).
  `navig mobile doctor` reports what's present and how to install the rest,
  honoring each tool's own license.

## Command pillars

`navig mobile --help` groups verbs by pillar: **Device & Connect · Info &
Diagnostics · Apps · Files & Pull · Backup & Restore · Screen & Control · App
Automation · Forensics & Investigate · Spyware Scan · Rooting & Jailbreak ·
Dev-Tools · OSINT & Case**.

## App UI automation & verification (`navig mobile ui …`)

The device engines *manage* a phone; **`navig mobile ui`** *drives the app on it* —
the agent's hands + eyes for verifying real app UIs. It wraps
[`agent-device`](https://github.com/callstack/agent-device) (callstack, MIT — a Node
CLI covering iOS / Android / web / desktop), **detected + driven as a subprocess**,
never bundled (so the base package stays pure-Python + Apache-2.0). Install it only if
you want UI verification: `npm install -g agent-device@latest` (Node 22+); then
`navig mobile ui doctor`.

```
navig mobile ui open MyApp -p android   # start a session bound to an app
navig mobile ui snapshot -i             # a11y tree with element refs (@e1, @e2…)
navig mobile ui tap @e2                  # act on a ref, then snapshot again
navig mobile ui fill @e3 "test@example.com"
navig mobile ui assert "Welcome"         # VERIFY the screen — exit 0/1 (machine-checkable)
navig mobile ui assert "row" --count 3   # …or an exact number of matches
navig mobile ui screenshot -o shot.png   # capture proof  (add --case <id> for evidence)
navig mobile ui close
navig mobile ui record -o flow.ad  ·  navig mobile ui replay flow.ad   # reproducible flows
navig mobile ui devices  ·  navig mobile ui apps -p ios                # discovery
```

Primary target is a **simulator/emulator** running an app you're building. `ui assert`
is the verify primitive — it snapshots the live screen and exits 0/1 so a flow is
*proven*, not eyeballed (`--gone` inverts it; `--count n` demands an exact number of
matches). It **auto-settles**: it re-checks until the assertion holds or `-t` (default
5s) runs out, so a screen that renders a beat after the tap passes instead of flaking —
a correct screen returns immediately, and only a failing assert waits (`-t 0` = check
once). Element refs match exactly, so `assert @e2` is never satisfied by `@e20`.
`snapshot`, `screenshot`, and `record` accept `--case <id>` to hash the artifact into a
case dir's chain-of-custody manifest. Add `--json` to `snapshot`/`apps`/`devices`/`assert`
for machine output; `ui exec <args>` is a raw passthrough.

**Ownership gate:** `ui open` / `ui record` refuse to drive a *physical* device (a named
real serial) without a recorded authorization (`navig mobile consent record`); simulators
and emulators are free.

### Verify a whole app screen as one outcome — the `app-ui-verify` Block

The plugin ships the **`app-ui-verify`** Block (`navig_mobile/blocks/app-ui-verify/`) —
an installable, executable **outcome**: open → snapshot → screenshot → **verify**
(`ui assert`), producing a verified receipt only when the expected screen actually
rendered. It's auto-discovered whenever navig-mobile is installed (no extra install
step), so:

```
navig apply app-ui-verify --input app=MyApp --input platform=android --input expect_text="Welcome"
```

Inspect it first with `navig block show app-ui-verify` or `navig apply … --dry-run`.

## Safety & consent

The investigative pillars (forensics, spyware-scan, private-data pull, rooting,
jailbreak, restore) are **consent-first and warn-before-destructive**. Evidence
is written read-only into a case directory with a sha256 manifest. Extracting or
scanning a device you don't own without authorization is illegal — record
authorization with `navig mobile consent` first.

## Investigate a device (consent-first)

```
navig mobile consent record -u <udid> --authorization "I own this device" --scope "..."
navig mobile forensics acquire         # iOS backup / Android bugreport → a case dir
navig mobile scan spyware              # acquire + MVT (Pegasus/mercenary IOCs)
navig mobile case list                 # your investigation cases
navig mobile evidence <case> --verify  # re-hash the chain-of-custody manifest
```

Forensics/spyware/media-pull are **consent-gated** — they refuse without a recorded
authorization for that device. Evidence is written read-only into a per-case
directory and every artifact is sha256-hashed into an append-only `manifest.json`
(who/when-UTC/where/how). MVT (spyware), iLEAPP/ALEAPP (parsing) are detected +
guided if not installed. Public IOCs are necessary-but-not-sufficient — a clean
scan is not proof a device is uncompromised.

## Root / jailbreak assist (detect → guide → drive, never one-click)

```
navig mobile root status               # Android: rooted?, bootloader lock, SELinux, Magisk
navig mobile root guide                # step-by-step Magisk unlock+patch flow
navig mobile jailbreak status          # iOS: checkm8 chip-eligibility + dev-mode
navig mobile android reboot bootloader # then, in fastboot:
navig mobile root unlock --yes         # DESTRUCTIVE — needs consent + --yes (wipes device)
navig mobile dev enable                # iOS Developer Mode / Android USB-debugging guidance
```

Wipe-level operations (`root unlock`/`flash`, `android sideload`) are **double-gated**:
a recorded consent record **and** an explicit `--yes`, with a loud warning. navig-mobile
never runs an exploit — it detects state, guides, and drives your own `fastboot` /
`pymobiledevice3` (both detected + guided if missing).

## Dev-tools & OSINT

```
navig mobile dev frida                 # list processes/apps (frida-ps)
navig mobile dev attach <app>          # frida REPL (needs frida-server on device)
navig mobile dev objection <app>       # objection explorer
navig mobile ios crashlogs             # pull iOS crash reports  · ios syslog · ios pcap
navig mobile osint device              # identity: serial/IMEI/MACs/android_id/chip-id
navig mobile osint apps                # Android app privacy report (high-risk permissions, ranked)
navig mobile osint report -o out.json  # combined identity + privacy → file (+ war-room hand-off)
```

frida / objection are detected + guided (attaching needs a matching `frida-server` on a
rooted/jailbroken device). The OSINT app scan flags high-risk permissions per app (camera,
mic, location, SMS, contacts, accessibility, all-files, install-apps…).

## Desktop-OS / deck API

The plugin serves a read-mostly device-dashboard API at `/api/deck/mobile/*` (mounted
via the `gateway:register_routes` hook, gated on the free `mobile` module) — the backend
the desktop OS renders against:

```
GET  /api/deck/mobile/devices                     # connected devices
GET  /api/deck/mobile/doctor                       # toolchain status
GET  /api/deck/mobile/device/{udid}                # device info
GET  /api/deck/mobile/device/{udid}/apps           # installed apps
GET  /api/deck/mobile/backups   ·  /cases          # inventory
POST /api/deck/mobile/device/{udid}/screenshot     # capture (path + inline preview)
```

Investigative/destructive verbs (forensics, spyware scan, root/flash, backup) are
**not** exposed over HTTP — they stay CLI-only, behind the consent gate + typed
confirmation. The visual dashboard view lives in `apps/os`.

## Status

- **Stages 0–4** (scaffold/doctor · MVP · forensics+spyware+consent · rooting/jailbreak
  · dev-tools+OSINT) and the **Stage 5 backend** (device-dashboard API + OS/deck surface
  registration) are implemented.
- The Stage 5 **frontend** (the `apps/os` React dashboard tile) is the remaining
  follow-up, owned by the desktop-OS surface (see `CHANGELOG.md`).
