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).

Works on its own — its own CLI, no navig required · v0.5.0 · PyPI

On its own (no navig needed)

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

With navig

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

Commands

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 · info · extract .
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 · pull · push .
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).

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 (Android over ADB)
  • pip install "navig-mobile[ios]" → 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 (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).