mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/phone_io/install.py

@@ -0,0 +1,188 @@
+"""Install a local .app or .ipa on a device with devicectl or simctl, run without a shell."""
+
+import json
+import os
+import plistlib
+import re
+import subprocess
+import tempfile
+import threading
+import time
+import zipfile
+from pathlib import Path
+
+from . import PhoneIOError
+
+TIMEOUT = 600
+UNPACK_LIMIT = 8 * 1024 ** 3
+
+PROBLEMS = (
+    ("developer_mode", re.compile(r"developer ?mode|0xe8000094|DeveloperModeDisabled", re.I),
+     "Developer Mode is off on the iPhone.",
+     "Turn it on in Settings › Privacy & Security › Developer Mode, restart the iPhone, then try again."),
+    ("not_signed", re.compile(r"0xe80080(?:15|16|18|1c)|ApplicationVerificationFailed|provisioning profile|"
+                              r"could not be verified|not been signed|code ?sign|signature|unsigned|"
+                              r"not (?:authorized|trusted)|integrity|untrusted developer", re.I),
+     "The build isn't signed for this iPhone.",
+     "Sign it with a development profile that includes this iPhone (Xcode › Signing & Capabilities), build it "
+     "for a device, then try again."),
+    ("locked", re.compile(r"device is locked|while (?:the device is )?locked|0xe80000e2", re.I),
+     "The iPhone is locked.", "Unlock it, then try again."),
+    ("no_device", re.compile(r"no devices? (?:matched|are booted|found)|unable to (?:find|locate)|not connected|"
+                             r"is not available|disconnected|invalid device|state: shutdown", re.I),
+     "The device isn't reachable.", "Plug it in (or boot the simulator) and try again."),
+)
+
+
+def check_path(path):
+    """``path`` as a local .app folder or .ipa file that exists; PhoneIOError (usage) otherwise."""
+    text = str(path or "").strip()
+    if not text or "://" in text:
+        raise PhoneIOError("Pass the path of a local .app or .ipa, not a link.", "usage")
+    candidate = Path(text).expanduser()
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+    candidate = candidate.resolve()
+    if candidate.suffix.lower() == ".ipa":
+        if not candidate.is_file() or not zipfile.is_zipfile(candidate):
+            raise PhoneIOError(f"{candidate} isn't an .ipa file.", "usage")
+        return candidate
+    if candidate.suffix.lower() == ".app":
+        if not (candidate.is_dir() and (candidate / "Info.plist").is_file()):
+            raise PhoneIOError(f"{candidate} isn't an app bundle (no Info.plist).", "usage")
+        return candidate
+    raise PhoneIOError(f"{candidate.name} isn't an .app or an .ipa.", "usage")
+
+
+def unpack(ipa, folder):
+    """The .app inside ``ipa`` (Payload/X.app), unpacked into ``folder``; no entry may leave it."""
+    root = Path(folder).resolve()
+    with zipfile.ZipFile(ipa) as archive:
+        total = 0
+        for info in archive.infolist():
+            target = (root / info.filename).resolve()
+            if root not in target.parents and target != root:
+                raise PhoneIOError(f"{Path(ipa).name} has an entry outside its folder; Mobster won't unpack it.",
+                                   "usage")
+            total += info.file_size
+            if total > UNPACK_LIMIT:
+                raise PhoneIOError(f"{Path(ipa).name} unpacks to more than 8 GB.", "usage")
+        archive.extractall(root)
+    apps = sorted((root / "Payload").glob("*.app"))
+    if len(apps) != 1:
+        raise PhoneIOError(f"{Path(ipa).name} has no single app in its Payload folder.", "usage")
+    return apps[0]
+
+
+def bundle_id(app):
+    try:
+        with open(Path(app) / "Info.plist", "rb") as handle:
+            value = plistlib.load(handle).get("CFBundleIdentifier")
+        return value if isinstance(value, str) else None
+    except (OSError, plistlib.InvalidFileException, ValueError, AttributeError):
+        return None
+
+
+def install_argv(record, app, json_path=None):
+    """The command that installs ``app`` (an .app) on ``record``'s device. No shell: a list of arguments."""
+    kind, udid = record.get("kind"), record.get("udid") or record.get("id")
+    if kind == "usb":
+        argv = ["xcrun", "devicectl", "device", "install", "app", "--device", str(udid), str(app)]
+        if json_path:
+            argv += ["--json-output", str(json_path)]
+        return argv
+    if kind == "simulator":
+        return ["xcrun", "simctl", "install", str(udid), str(app)]
+    raise PhoneIOError(f"Mobster can't install a build on “{record.get('name')}”: it's a WebDriverAgent address, "
+                       "not an iPhone or simulator it knows.", "usage", "Install with Xcode instead.")
+
+
+def explain(output, returncode):
+    """PhoneIOError for a failed install, from the tool's output."""
+    for code, pattern, message, fix in PROBLEMS:
+        if pattern.search(output or ""):
+            return PhoneIOError(message, code, fix)
+    lines = [line.strip() for line in (output or "").splitlines() if line.strip()]
+    last = next((line for line in reversed(lines) if line.lower().startswith(("error", "an error"))),
+                lines[-1] if lines else "")
+    return PhoneIOError(f"The install failed (exit {returncode}){': ' + last[:300] if last else ''}.", "failed")
+
+
+def run_streaming(argv, progress=None, timeout=TIMEOUT):
+    """(exit code, output) of ``argv``, each line handed to ``progress`` as it comes."""
+    try:
+        process = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL,
+                                   text=True, errors="replace")
+    except FileNotFoundError:
+        raise PhoneIOError("Xcode's command-line tools aren't installed.", "tools",
+                           "Install Xcode, open it once, then try again.") from None
+    lines = []
+
+    def pump():
+        # Its own thread: a tool that hangs without printing must still meet the time limit.
+        for line in process.stdout:
+            lines.append(line)
+            if progress is not None and line.strip():
+                try:
+                    progress(line.rstrip())
+                except Exception:
+                    pass
+    reader = threading.Thread(target=pump, daemon=True, name="mobster-install-output")
+    reader.start()
+    try:
+        code = process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        limit = f"{timeout / 60:g} minutes" if timeout >= 60 else f"{timeout:g} seconds"
+        raise PhoneIOError(f"The install took over {limit}; Mobster stopped it.", "failed") from None
+    finally:
+        if process.poll() is None:
+            process.kill()
+            try:
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                pass
+        reader.join(5)
+        if not reader.is_alive():
+            process.stdout.close()
+    return code, "".join(lines)
+
+
+def installed_bundle(json_path):
+    try:
+        data = json.loads(Path(json_path).read_text())
+    except (OSError, ValueError):
+        return None
+    apps = ((data.get("result") or {}).get("installedApplications") or []) if isinstance(data, dict) else []
+    for app in apps:
+        if isinstance(app, dict) and isinstance(app.get("bundleID"), str):
+            return app["bundleID"]
+    return None
+
+
+def install(record, path, *, runner=None, progress=None):
+    """Install the .app or .ipa at ``path`` on ``record``'s device."""
+    source = check_path(path)
+    if runner is None:
+        from ..native_helpers import require_devices
+        require_devices()  # a test or local CI never reaches a phone
+    runner = runner or (lambda argv: run_streaming(argv, progress))
+    started = time.monotonic()
+    with tempfile.TemporaryDirectory(prefix="mobster-install-") as folder:
+        app = unpack(source, folder) if source.suffix.lower() == ".ipa" else source
+        json_path = Path(folder) / "devicectl.json"
+        argv = install_argv(record, app, json_path)
+        if progress is not None:
+            progress(f"Installing {app.name} on {record.get('name') or record.get('id')}…")
+        code, output = runner(argv)
+        if code != 0:
+            raise explain(output, code)
+        bundle = installed_bundle(json_path) or bundle_id(app)
+    return {"ok": True, "device": record.get("id"), "name": record.get("name"), "path": str(source),
+            "bundle_id": bundle, "seconds": round(time.monotonic() - started, 1)}
+
+
+def describe_path(path):
+    """A path for messages: the user's home as ~."""
+    home = os.path.expanduser("~")
+    text = str(path)
+    return "~" + text[len(home):] if text.startswith(home + os.sep) else text

mobile_agent/phone_io/network_capture.py

@@ -0,0 +1,188 @@
+"""Bounded USB packet traces through Apple's Remote Virtual Interface, without TLS interception."""
+
+import fcntl
+import hashlib
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+from . import PhoneIOError, capture_cancellation
+
+# tcpdump holds the phone lock, so it must end by itself even when Mobster is SIGKILLed. Mobster stops it at
+# `seconds`; the kernel's SIGALRM, which survives exec, ends it this long after that.
+HARD_STOP_GRACE = 15
+
+
+def die_after(seconds):
+    """A preexec_fn that arms SIGALRM in the child; the pending alarm survives exec into tcpdump."""
+    return lambda: signal.alarm(seconds)
+
+
+def binary(name):
+    path = shutil.which(name)
+    if not path and Path("/Library/Apple/usr/bin", name).is_file():
+        path = str(Path("/Library/Apple/usr/bin", name))
+    if not path:
+        raise PhoneIOError(f"{name} isn't installed. Install Xcode and its device support tools.", "tools")
+    return path
+
+
+def rvi_for(text, udid):
+    for line in text.splitlines():
+        if re.search(r"(?<![A-Za-z0-9-])" + re.escape(udid) + r"(?![A-Za-z0-9-])", line, re.I):
+            found = re.search(r"\b(rvi\d+)\b", line)
+            if found:
+                return found.group(1)
+    return None
+
+
+def rvi_command(tool, *arguments):
+    try:
+        result = subprocess.run([tool, *arguments], capture_output=True, text=True, timeout=15,
+                                stdin=subprocess.DEVNULL)
+    except subprocess.TimeoutExpired:
+        raise PhoneIOError("rvictl didn't answer. Its outcome is unknown; "
+                           "inspect `rvictl -l` before trying again.") from None
+    except KeyboardInterrupt:
+        raise PhoneIOError("rvictl was interrupted. Its outcome is unknown; "
+                           "inspect `rvictl -l` before trying again.") from None
+    except OSError:
+        raise PhoneIOError("Mobster couldn't start rvictl. Check Xcode's device support tools.", "tools") from None
+    if result.returncode:
+        raise PhoneIOError("rvictl refused the request. Unlock the USB iPhone and check this Mac's device permissions.")
+    return result.stdout + result.stderr
+
+
+def clear_stale(rvictl, udid, state):
+    """With the phone lock held, no capture is alive, so a state file is a dead capture's leftover."""
+    if not state.exists():
+        return
+    if rvi_for(rvi_command(rvictl, "-l"), udid):
+        rvi_command(rvictl, "-x", udid)
+    state.unlink(missing_ok=True)
+
+
+def stop(process):
+    try:
+        if process.poll() is None:
+            try:
+                process.send_signal(signal.SIGINT)
+            except ProcessLookupError:
+                pass  # The process can exit between poll and signal; wait still reaps it.
+            try:
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=5)
+    except (OSError, subprocess.TimeoutExpired):
+        raise PhoneIOError("Mobster couldn't stop tcpdump. Inspect running capture processes "
+                           "before trying again.") from None
+
+
+def capture(record, output, *, seconds=30, packets=10000, snaplen=128):
+    """Capture beside a running task. A separate per-phone lock owns the RVI lifecycle, not the UI lease."""
+    from ..env_file import open_private, private_dir
+    from ..mac_tools import usb_attached
+    from ..native_helpers import require_devices
+    from ..paths import user_data_dir
+    if (isinstance(seconds, bool) or not isinstance(seconds, int) or not 1 <= seconds <= 300 or
+            isinstance(packets, bool) or not isinstance(packets, int) or not 1 <= packets <= 100000 or
+            isinstance(snaplen, bool) or not isinstance(snaplen, int) or not 64 <= snaplen <= 65535):
+        raise PhoneIOError("Use 1–300 seconds, 1–100000 packets and a snap length of 64–65535 bytes.", "usage")
+    require_devices()
+    udid = record.get("udid")
+    if record.get("kind") != "usb" or not udid or not usb_attached(udid):
+        raise PhoneIOError("Packet capture needs a paired iPhone connected by USB.", "needs_cable")
+    rvictl, tcpdump = binary("rvictl"), binary("tcpdump")
+    folder = user_data_dir() / "network-capture"
+    private_dir(folder)
+    key = hashlib.sha256(udid.upper().encode()).hexdigest()[:24]
+    with open_private(folder / (key + ".lock"), "a+") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise PhoneIOError(f"Mobster is already capturing this iPhone. Stop that capture first; an orphaned "
+                               f"one ends by itself within {HARD_STOP_GRACE} seconds of its time limit.") from None
+        state = folder / (key + ".json")
+        with capture_cancellation():
+            clear_stale(rvictl, udid, state)
+            return _capture(rvictl, tcpdump, udid, output, seconds, packets, snaplen, lock.fileno(), state)
+
+
+def _capture(rvictl, tcpdump, udid, output, seconds, packets, snaplen, lock_fd, state):
+    from ..env_file import open_private
+    target = Path(output).expanduser().absolute()
+    try:
+        stream = open(target, "xb", opener=lambda p, flags: os.open(p, flags, 0o600))
+    except FileExistsError:
+        raise PhoneIOError("The capture file already exists. Choose another --output path.", "usage") from None
+    except OSError:
+        raise PhoneIOError("Mobster couldn't create the capture file. Check the output folder.") from None
+    owned, process, interface = False, None, None
+    cleanup_error = None
+    try:
+        listing = rvi_command(rvictl, "-l")
+        interface = rvi_for(listing, udid)
+        if interface is None:
+            # Journal the intent first: if Mobster dies before `-x`, the next start removes this interface.
+            with open_private(state, "w") as intent:
+                json.dump({"owned": True}, intent)
+            result = rvi_command(rvictl, "-s", udid)
+            interface = rvi_for(result, udid)
+            if not interface or "[SUCCEEDED]" not in result:
+                raise PhoneIOError("rvictl didn't identify a created interface. Inspect `rvictl -l` before retrying.")
+            owned = True
+        try:
+            # A surviving tcpdump must keep the phone locked if Mobster is killed without cleanup.
+            with capture_cancellation(defer=True):
+                process = subprocess.Popen([tcpdump, "-i", interface, "-n", "-U", "-s", str(snaplen),
+                                            "-c", str(packets), "-w", "-"], stdin=subprocess.DEVNULL,
+                                           stdout=stream, stderr=subprocess.DEVNULL, pass_fds=(lock_fd,),
+                                           preexec_fn=die_after(seconds + HARD_STOP_GRACE))
+            try:
+                process.wait(timeout=seconds)
+            except subprocess.TimeoutExpired:
+                stop(process)
+            if process.returncode not in (0, -signal.SIGINT):
+                raise PhoneIOError("tcpdump couldn't capture packets. Check BPF capture permissions on this Mac; "
+                                   "Apple's packet-capture instructions require administrator access.")
+        except OSError:
+            raise PhoneIOError("Mobster couldn't start tcpdump. Check this Mac's capture permissions.",
+                               "tools") from None
+    finally:
+        try:
+            if process is not None:
+                stop(process)
+        finally:
+            try:
+                stream.close()
+            finally:
+                if owned:
+                    try:
+                        rvi_command(rvictl, "-x", udid)
+                        state.unlink(missing_ok=True)
+                    except PhoneIOError:
+                        cleanup_error = "The capture's RVI could not be removed. Inspect `rvictl -l`."
+                try:
+                    if target.stat().st_size == 0:
+                        target.unlink()
+                except FileNotFoundError:
+                    pass  # Removing the output during capture must not hide its original error or cleanup warning.
+                failure = sys.exception()
+                if cleanup_error and failure is not None:
+                    message = str(failure) if isinstance(failure, PhoneIOError) else "Packet capture was interrupted."
+                    raise PhoneIOError(f"{message} {cleanup_error}", getattr(failure, "code", "failed")) from None
+    try:
+        size = target.stat().st_size
+    except FileNotFoundError:
+        size = 0
+    if size < 24:
+        message = "No complete capture file remains. Check capture permissions and the output path before trying again."
+        raise PhoneIOError(f"{message} {cleanup_error}" if cleanup_error else message)
+    return {"ok": True, "path": str(target), "bytes": size, "interface": interface,
+            "snaplen": snaplen, "packetLimit": packets, "secondsLimit": seconds, "warning": cleanup_error}

mobile_agent/phone_io/network_cli.py

@@ -0,0 +1,138 @@
+"""Network profile generation and diagnostics for `mobster phone network`."""
+
+from . import PhoneIOError, choose_device
+
+
+def add_arguments(subs, helpers):
+    path_type = helpers.get("path_type")
+    parser = subs.add_parser("network", help="create network profiles, diagnose this Mac, or capture USB traffic",
+                             description="Create removable iPhone network profiles, inspect this Mac's connectivity, "
+                                         "or capture a USB iPhone's packets. Profiles need installation in Settings.")
+    verbs = parser.add_subparsers(dest="network_command", metavar="<subcommand>", required=True)
+
+    proxy = verbs.add_parser("proxy-profile", help="write a Wi-Fi HTTP proxy or PAC profile",
+                             description="Write a Wi-Fi profile for one SSID. Apps may ignore HTTP proxies; this "
+                                         "does not route cellular traffic or decrypt TLS.")
+    proxy.add_argument("--ssid", required=True, help="the Wi-Fi network name")
+    mode = proxy.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--server", help="the HTTP proxy hostname or IP address")
+    mode.add_argument("--pac", metavar="URL", help="the HTTP or HTTPS proxy auto-configuration URL")
+    proxy.add_argument("--port", type=int, default=8080, help="the HTTP proxy port (default: 8080)")
+    proxy.add_argument("--username", help="the HTTP proxy username")
+    proxy.add_argument("--password-file", type=path_type, metavar="FILE",
+                       help="read the proxy password from this UTF-8 file")
+    proxy.add_argument("--wifi-password-file", type=path_type, metavar="FILE",
+                       help="read the Wi-Fi password from this UTF-8 file")
+    proxy.add_argument("--encryption", choices=("Any", "WPA2", "WPA3", "None"), default="Any",
+                       help="the Wi-Fi encryption type (default: Any)")
+
+    vpn = verbs.add_parser("vpn-profile", help="write an IKEv2 VPN profile with username authentication",
+                           description="Write an IKEv2 EAP VPN profile for your provider. This does not create a VPN "
+                                       "server. Install the profile and connect in Settings.")
+    vpn.add_argument("--server", required=True, help="the VPN server hostname or IP address")
+    vpn.add_argument("--remote-id", required=True, help="the server identifier from your VPN provider")
+    vpn.add_argument("--local-id", required=True, help="the client identifier from your VPN provider")
+    vpn.add_argument("--username", required=True, help="the VPN account username")
+    vpn.add_argument("--password-file", type=path_type, metavar="FILE",
+                     help="read the VPN password from this UTF-8 file")
+
+    relay = verbs.add_parser("relay-profile", help="write an Apple HTTP/2 network relay profile",
+                             description="Write an Apple network relay profile for an existing compatible HTTP/2 "
+                                         "relay service. This is not an ordinary HTTP proxy or a new relay server.")
+    relay.add_argument("--url", required=True, help="the HTTPS relay endpoint")
+    relay.add_argument("--token-file", type=path_type, metavar="FILE",
+                       help="read the bearer token from this UTF-8 file")
+
+    for command, kind, name in ((proxy, "proxy", "Mobster proxy"), (vpn, "vpn", "Mobster VPN"),
+                                 (relay, "relay", "Mobster relay")):
+        command.add_argument("--output", required=True, type=path_type, metavar="FILE",
+                             help="write a new private .mobileconfig file; existing files are kept")
+        command.add_argument("--name", default=name, help=f"the profile's display name (default: {name})")
+        command.add_argument("--identifier", default=f"app.mobster.network.{kind}",
+                             help=f"the stable profile identifier (default: app.mobster.network.{kind})")
+        command.add_argument("--json", action="store_true", help="print one JSON object")
+
+    diagnose = verbs.add_parser("diagnose", help="inspect this Mac's route and optional TCP endpoint reachability",
+                                description="Check this Mac's default route and optional TCP endpoint. With --device, "
+                                            "also report USB attachment. This does not test the iPhone's internet "
+                                            "egress, proxy authentication, or installed profiles.")
+    diagnose.add_argument("--device", metavar="NAME", help="also inspect USB attachment for this device")
+    diagnose.add_argument("--host", help="the hostname or IP address to test from this Mac")
+    diagnose.add_argument("--port", type=int, default=8080, help="the TCP endpoint port (default: 8080)")
+    diagnose.add_argument("--json", action="store_true", help="print one JSON object")
+
+    capture = verbs.add_parser("capture", help="save a bounded USB iPhone packet trace",
+                               description="Capture packets through Apple's Remote Virtual Interface. Requires a "
+                                           "paired USB iPhone, Xcode tools and BPF permissions on this Mac. TLS "
+                                           "remains encrypted; packet data may contain private information.")
+    capture.add_argument("--device", required=True, metavar="NAME", help="the paired USB iPhone's id, UDID or name")
+    capture.add_argument("--output", required=True, type=path_type, metavar="FILE",
+                         help="write a new private pcap file")
+    capture.add_argument("--seconds", type=int, default=30, help="stop after 1 to 300 seconds (default: 30)")
+    capture.add_argument("--packets", type=int, default=10000, help="stop after 1 to 100000 packets (default: 10000)")
+    capture.add_argument("--snaplen", type=int, default=128, help="capture 64 to 65535 bytes per packet (default: 128)")
+    capture.add_argument("--json", action="store_true", help="print one JSON object")
+
+
+def run(args):
+    from . import network_capture
+    from . import network_profiles as profiles
+    from .cli import _print
+
+    command = args.network_command
+    if command == "diagnose":
+        result, lines = diagnose(args)
+    elif command == "capture":
+        # Validate before device discovery so bad input cannot initiate device work.
+        if not (1 <= args.seconds <= 300 and 1 <= args.packets <= 100000 and 64 <= args.snaplen <= 65535):
+            raise PhoneIOError("Use 1–300 seconds, 1–100000 packets and a snap length of 64–65535 bytes.", "usage")
+        record = choose_device(args.device)
+        result = network_capture.capture(record, args.output, seconds=args.seconds,
+                                         packets=args.packets, snaplen=args.snaplen)
+        lines = [f"Saved {result['bytes']:,} bytes to {result['path']}."]
+        if result.get("warning"):
+            lines.append(result["warning"])
+    else:
+        if command == "proxy-profile":
+            payload = profiles.proxy(ssid=args.ssid, server=args.server, port=args.port, pac=args.pac,
+                                     username=args.username, password=profiles.secret(args.password_file),
+                                     wifi_password=profiles.secret(args.wifi_password_file), encryption=args.encryption)
+        elif command == "vpn-profile":
+            payload = profiles.vpn(server=args.server, remote_id=args.remote_id, local_id=args.local_id,
+                                   username=args.username, password=profiles.secret(args.password_file))
+        else:
+            payload = profiles.relay(endpoint=args.url, token=profiles.secret(args.token_file))
+        result = profiles.write_profile(payload, args.output, name=args.name, identifier=args.identifier)
+        lines = [f"Saved {result['path']}. The profile is not installed.", result["next"]]
+    _print(result, args.json, "\n".join(lines))
+    return 0 if result["ok"] else 1
+
+
+def diagnose(args):
+    from .. import mac_tools
+    from ..wireless import network
+    from .network_profiles import host
+
+    if not 1 <= args.port <= 65535:
+        raise PhoneIOError("The endpoint port must be between 1 and 65535.", "usage")
+    endpoint_host = host(args.host) if args.host is not None else None
+    record = choose_device(args.device) if args.device else None
+    interface = network.primary_interface()
+    state = network.nwi()
+    result = {"ok": True, "scope": "mac", "mac": {"defaultInterface": interface,
+              "gateway": network.default_gateway(), "vpnInterface": network.vpn_interface(state)},
+              "phoneEgressTested": False}
+    lines = [f"Mac default interface: {interface or 'unknown'}.",
+             f"Mac VPN interface: {result['mac']['vpnInterface'] or 'none detected'}."]
+    if endpoint_host:
+        reachable = network.port_open(endpoint_host, args.port)
+        result["endpoint"] = {"host": endpoint_host, "port": args.port, "reachableFromMac": reachable}
+        result["ok"] = reachable
+        lines.append(f"TCP endpoint from this Mac: {'reachable' if reachable else 'unreachable'}.")
+    if record:
+        attached = mac_tools.usb_attached(record.get("udid")) if record.get("kind") == "usb" else None
+        result["device"] = {"id": record["id"], "kind": record.get("kind"), "usbAttached": attached}
+        lines.append(
+            f"Device USB attachment: { {True: 'connected', False: 'disconnected', None: 'unknown'}[attached]}.")
+    lines.append("The iPhone's internet egress, proxy authentication and installed profiles were not tested.")
+    return result, lines

mobile_agent/phone_io/network_profiles.py

@@ -0,0 +1,138 @@
+"""Removable Apple network profiles. Generating one never changes a device's routing.
+
+Keys follow apple/device-management's WiFi, VPN.IKEv2 and Relay payload schemas.
+Credentials come from files, never command-line arguments or result messages.
+"""
+
+import ipaddress
+import os
+import plistlib
+import re
+import tempfile
+import uuid
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from . import PhoneIOError
+
+
+def host(value):
+    value = str(value or "").strip()
+    try:
+        return str(ipaddress.ip_address(value))
+    except ValueError:
+        if (len(value) > 253 or not value or any(not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?", p)
+                                               for p in value.rstrip(".").split("."))):
+            raise PhoneIOError("Use a hostname or IP address without a scheme, path or credentials.", "usage") from None
+    return value
+
+
+def url(value, *, https=False):
+    try:
+        parsed = urlsplit(value)
+        valid = (parsed.scheme in (("https",) if https else ("http", "https")) and parsed.hostname and
+                 parsed.username is None and parsed.password is None and not parsed.fragment and
+                 not any(c.isspace() or ord(c) < 32 for c in value))
+        host(parsed.hostname)
+        if parsed.port is not None and not 1 <= parsed.port <= 65535:
+            valid = False
+    except (ValueError, TypeError, PhoneIOError):
+        valid = False
+    if not valid:
+        raise PhoneIOError("Use an HTTPS URL without embedded credentials." if https else
+                           "Use an HTTP or HTTPS URL without embedded credentials.", "usage")
+    return value
+
+
+def secret(path):
+    if not path:
+        return None
+    try:
+        with Path(path).expanduser().open("rb") as stream:
+            # Include the optional CRLF plus one extra byte so oversized files cannot be truncated into valid secrets.
+            value = stream.read(4099).decode("utf-8").removesuffix("\n").removesuffix("\r")
+    except (OSError, UnicodeError):
+        raise PhoneIOError("Mobster couldn't read the credential file as UTF-8.", "usage") from None
+    if not value or len(value.encode()) > 4096 or any(ord(c) < 32 for c in value):
+        raise PhoneIOError("The credential file must contain one nonempty line of at most 4 KB.", "usage")
+    return value
+
+
+def proxy(*, ssid, server=None, port=8080, pac=None, username=None, password=None,
+          wifi_password=None, encryption="Any"):
+    if not isinstance(ssid, str) or not 1 <= len(ssid.encode()) <= 32 or any(ord(c) < 32 for c in ssid):
+        raise PhoneIOError("The Wi-Fi name must contain 1 to 32 UTF-8 bytes.", "usage")
+    if bool(server) == bool(pac):
+        raise PhoneIOError("Choose a proxy server or a PAC URL.", "usage")
+    if encryption not in ("Any", "WPA2", "WPA3", "None") or encryption == "None" and wifi_password:
+        raise PhoneIOError("Choose Any, WPA2, WPA3 or None; an open network takes no Wi-Fi password.", "usage")
+    payload = {"PayloadType": "com.apple.wifi.managed", "SSID_STR": ssid, "EncryptionType": encryption,
+               "AutoJoin": True, "ProxyType": "Auto" if pac else "Manual"}
+    if wifi_password:
+        payload["Password"] = wifi_password
+    if pac:
+        if username or password:
+            raise PhoneIOError("PAC profiles do not take proxy credentials.", "usage")
+        payload.update(ProxyPACURL=url(pac), ProxyPACFallbackAllowed=False)
+    else:
+        if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
+            raise PhoneIOError("The proxy port must be between 1 and 65535.", "usage")
+        payload.update(ProxyServer=host(server), ProxyServerPort=port)
+        if password and not username:
+            raise PhoneIOError("A proxy password needs --username.", "usage")
+        if username:
+            payload["ProxyUsername"] = username
+        if password:
+            payload["ProxyPassword"] = password
+    return payload
+
+
+def vpn(*, server, remote_id, local_id, username, password=None):
+    if not all(isinstance(v, str) and v.strip() for v in (remote_id, local_id, username)):
+        raise PhoneIOError("IKEv2 needs a remote identifier, local identifier and username from your VPN provider.",
+                           "usage")
+    settings = {"RemoteAddress": host(server), "RemoteIdentifier": remote_id, "LocalIdentifier": local_id,
+                "AuthenticationMethod": "None", "ExtendedAuthEnabled": 1, "AuthName": username,
+                "IncludeAllNetworks": 1, "OnDemandEnabled": 0}
+    if password:
+        settings["AuthPassword"] = password
+    return {"PayloadType": "com.apple.vpn.managed", "VPNType": "IKEv2", "UserDefinedName": "Mobster VPN",
+            "IKEv2": settings}
+
+
+def relay(*, endpoint, token=None):
+    server = {"HTTP2RelayURL": url(endpoint, https=True)}
+    if token:
+        if any(ord(c) < 32 for c in token):
+            raise PhoneIOError("The relay token must be one line.", "usage")
+        server["AdditionalHTTPHeaderFields"] = {"Authorization": "Bearer " + token}
+    return {"PayloadType": "com.apple.relay.managed", "Relays": [server]}
+
+
+def write_profile(payload, output, *, name="Mobster network", identifier="app.mobster.network"):
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9.-]{1,199}", identifier):
+        raise PhoneIOError("Use a profile identifier of 2 to 200 letters, numbers, dots or hyphens.", "usage")
+    def envelope(kind, identity):
+        return {"PayloadType": kind, "PayloadVersion": 1, "PayloadIdentifier": identity,
+                "PayloadUUID": str(uuid.uuid5(uuid.NAMESPACE_URL, identity)), "PayloadDisplayName": name}
+    content = {**payload, **envelope(payload["PayloadType"], identifier + ".settings")}
+    profile = {**envelope("Configuration", identifier), "PayloadContent": [content], "PayloadRemovalDisallowed": False}
+    try:
+        data = plistlib.dumps(profile)
+    except (TypeError, ValueError):
+        raise PhoneIOError("The profile contains text Apple can't encode. Remove control characters.",
+                           "usage") from None
+    target = Path(output).expanduser().absolute()
+    try:
+        # Publish only the complete private plist; link keeps a concurrent writer's output intact.
+        with tempfile.NamedTemporaryFile(dir=target.parent, prefix=".mobster-profile-") as stream:
+            stream.write(data)
+            stream.flush()
+            os.link(stream.name, target)
+    except FileExistsError:
+        raise PhoneIOError("The output file already exists. Choose another --output path.", "usage") from None
+    except OSError:
+        raise PhoneIOError("Mobster couldn't write the profile. Check the output folder.") from None
+    return {"ok": True, "path": str(target), "identifier": identifier, "installed": False,
+            "next": "Transfer this profile to your iPhone, then review and install it in Settings > General > "
+                    "VPN & Device Management. Remove that profile there to remove this configuration."}