ipa-forge 0.1.0__py3-none-any.whl

ipa_forge/bundle/inventory.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Bottom-up nested-executable inventory walker.
+
+Classification is purely structural (by containing directory suffix), never
+by bundle/app identifier -- this keeps the core engine app-agnostic per the
+architecture's core rule.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ipa_forge.bundle.models import AppBundle, MachOKind, MachOTarget
+from ipa_forge.bundle.plist import read_plist
+from ipa_forge.machO.detect import is_macho_file
+
+_OWNING_BUNDLE_SUFFIX: dict[MachOKind, str] = {"appex": ".appex", "watch_app": ".app"}
+
+
+def _classify(rel: Path, main_executable_name: str) -> MachOKind:
+    parts = rel.parts
+
+    if len(parts) == 1 and parts[0] == main_executable_name:
+        return "main"
+
+    # Innermost containing directory determines kind: a dylib inside a
+    # .framework is still a "framework" executable, a framework nested
+    # inside a watch app is still a "framework", etc.
+    for name in reversed(parts[:-1]):
+        if name.endswith(".appex"):
+            return "appex"
+        if name.endswith(".app"):
+            return "watch_app"
+        if name.endswith(".framework"):
+            return "framework"
+
+    if rel.suffix == ".dylib":
+        return "dylib"
+
+    return "other"
+
+
+def _owning_bundle_dir(app_root: Path, rel: Path, kind: MachOKind) -> Path | None:
+    """Directory of the bundle (.appex/.app) that owns this target's own
+    Info.plist, for kinds that can carry their own provisioning profile."""
+    suffix = _OWNING_BUNDLE_SUFFIX.get(kind)
+    if suffix is None:
+        return None
+    parts = rel.parts
+    for i in range(len(parts) - 1, -1, -1):
+        if parts[i].endswith(suffix):
+            return app_root.joinpath(*parts[: i + 1])
+    return None
+
+
+def _read_bundle_id(bundle_dir: Path) -> str | None:
+    try:
+        plist = read_plist(bundle_dir / "Info.plist")
+    except (OSError, ValueError):
+        return None
+    bundle_id = plist.get("CFBundleIdentifier")
+    return bundle_id if isinstance(bundle_id, str) else None
+
+
+def build_inventory(bundle: AppBundle) -> list[MachOTarget]:
+    """Walk bundle.root for Mach-O executables, returned in bottom-up sign order
+    (deepest-nested first; the top-level main executable always last)."""
+    app_root = bundle.root
+    main_name = bundle.main_executable_name
+
+    targets: list[MachOTarget] = []
+    for path in app_root.rglob("*"):
+        if not is_macho_file(path):
+            continue
+        rel = path.relative_to(app_root)
+        kind = _classify(rel, main_name)
+
+        target_bundle_id: str | None
+        if kind == "main":
+            target_bundle_id = bundle.bundle_id
+        else:
+            owning_dir = _owning_bundle_dir(app_root, rel, kind)
+            target_bundle_id = _read_bundle_id(owning_dir) if owning_dir else None
+
+        targets.append(
+            MachOTarget(
+                path=path,
+                bundle_relative=str(Path("Payload") / app_root.name / rel),
+                kind=kind,
+                depth=len(rel.parts),
+                bundle_id=target_bundle_id,
+            )
+        )
+
+    targets.sort(key=lambda t: (t.kind == "main", -t.depth))
+    return targets

ipa_forge/bundle/ipa.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""IPA extraction and repackaging.
+
+Uses the platform `zip`/`unzip` CLI tools rather than Python's `zipfile`
+module because Apple bundles routinely contain symlinks (e.g.
+`Foo.framework/Foo -> Versions/Current/Foo`), and `zip -y` / `unzip` round-trip
+those correctly while `zipfile` does not preserve them by default.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from ipa_forge.bundle.inventory import build_inventory
+from ipa_forge.bundle.models import AppBundle
+from ipa_forge.bundle.plist import read_plist
+
+
+def extract_ipa(ipa_path: Path, dest_dir: Path) -> Path:
+    """Extract ipa_path into dest_dir. Returns the path to Payload/<App>.app.
+
+    Structural validation of the archive itself is a separate stage
+    (validators/ipa_validator.py) run by the pipeline before this is called;
+    here we only require the extraction to yield exactly one Payload/*.app.
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["unzip", "-qq", "-o", str(ipa_path), "-d", str(dest_dir)],
+        check=True,
+    )
+    payload_dir = dest_dir / "Payload"
+    apps = [p for p in payload_dir.iterdir() if p.is_dir() and p.name.endswith(".app")]
+    if len(apps) != 1:
+        raise FileNotFoundError(f"expected exactly one Payload/*.app bundle under {payload_dir}, found {len(apps)}")
+    return apps[0]
+
+
+def repack_ipa(extraction_root: Path, output_path: Path) -> Path:
+    """Zip extraction_root/Payload back into a standard-structure .ipa at output_path."""
+    payload_dir = extraction_root / "Payload"
+    if not payload_dir.is_dir():
+        raise FileNotFoundError(f"No Payload/ directory under {extraction_root}")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if output_path.exists():
+        output_path.unlink()
+    subprocess.run(
+        ["zip", "-qq", "-r", "-y", str(output_path), "Payload"],
+        cwd=extraction_root,
+        check=True,
+    )
+    return output_path
+
+
+def validate_and_extract(ipa: Path, dest: Path) -> Path:
+    """Structure-validate (pipeline stage 1), then extract. Raises ValueError
+    on malformed input; the neutral home shared by the GUI and CLI."""
+    from ipa_forge.validators.ipa_validator import IpaValidationError, validate_ipa_structure
+
+    try:
+        validate_ipa_structure(ipa)
+    except IpaValidationError as e:
+        raise ValueError(str(e)) from e
+    return extract_ipa(ipa, dest)
+
+
+def load_bundle(app_path: Path) -> AppBundle:
+    """Build an AppBundle model (with full inventory) from an already-extracted .app."""
+    info_plist_path = app_path / "Info.plist"
+    info_plist = read_plist(info_plist_path)
+
+    bundle = AppBundle(
+        root=app_path,
+        extraction_root=app_path.parent.parent,
+        info_plist=info_plist,
+        bundle_id=info_plist["CFBundleIdentifier"],
+        version=info_plist.get("CFBundleShortVersionString", ""),
+        build=info_plist.get("CFBundleVersion", ""),
+    )
+    bundle.executables = build_inventory(bundle)
+    return bundle

ipa_forge/bundle/models.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Core bundle data model shared by the patch engine and the signing subsystem."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+MachOKind = Literal["main", "framework", "dylib", "appex", "watch_app", "other"]
+
+
+@dataclass
+class MachOTarget:
+    """A single executable within the bundle (main binary, framework, dylib, extension, watch app)."""
+
+    path: Path
+    """Absolute path on disk, inside the extraction working directory."""
+
+    bundle_relative: str
+    """Path relative to the extraction root (e.g. "Payload/App.app/Frameworks/Foo.framework/Foo"),
+    used to address this target from patch definitions and the manifest."""
+
+    kind: MachOKind
+
+    depth: int
+    """Number of path components below the top-level app root; used to derive bottom-up sign order."""
+
+    bundle_id: str | None = None
+    """CFBundleIdentifier of the owning bundle, for kinds that have their own Info.plist and can
+    carry their own embedded.mobileprovision (main, appex, watch_app). None for framework/dylib/other,
+    which are signed but never embed a profile of their own."""
+
+
+@dataclass
+class AppBundle:
+    """In-memory representation of an extracted .app, with its nested executable inventory."""
+
+    root: Path
+    """Path to Payload/<App>.app."""
+
+    extraction_root: Path
+    """Path to the temp directory containing Payload/, i.e. root.parent.parent."""
+
+    info_plist: dict[str, Any]
+    bundle_id: str
+    version: str
+    build: str
+
+    executables: list[MachOTarget] = field(default_factory=list)
+    """Populated by the inventory walker, ordered bottom-up (deepest-nested first, main app last)."""
+
+    entitlements: dict[str, Any] | None = None
+    """Populated during the signing stage; None until then."""
+
+    @property
+    def main_executable_name(self) -> str:
+        return self.info_plist["CFBundleExecutable"]

ipa_forge/bundle/plist.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Info.plist read/write helpers (binary or XML plist, transparently)."""
+
+from __future__ import annotations
+
+import plistlib
+from pathlib import Path
+from typing import Any
+
+
+def read_plist(path: Path) -> dict[str, Any]:
+    with open(path, "rb") as f:
+        return plistlib.load(f)
+
+
+def write_plist(path: Path, data: dict[str, Any]) -> None:
+    with open(path, "wb") as f:
+        plistlib.dump(data, f)

ipa_forge/cli/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: GPL-3.0-or-later

ipa_forge/cli/analysis.py

@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`forge analysis` subcommands: general-purpose reverse engineering of an
+IPA, built on the same Mach-O/ObjC analysis engine `forge hooks` uses for
+hook verification (see `ipa_forge.machO.objc`).
+
+Every command accepts ``--app-dir`` in place of the IPA, same as
+`forge hooks` — point it at an already-extracted ``Payload/<App>.app``
+directory to skip re-extraction when iterating.
+"""
+
+from __future__ import annotations
+
+import re as _re
+import tempfile
+from pathlib import Path
+
+import typer
+
+from ipa_forge.analysis.classdump import render_analysis
+from ipa_forge.analysis.diff import diff_analyses, render_diff
+from ipa_forge.analysis.security import analyze_security, render_security_posture
+from ipa_forge.analysis.strings import strings_in_bundle
+from ipa_forge.analysis.symbols import analyze_symbols
+from ipa_forge.bundle.ipa import load_bundle
+from ipa_forge.bundle.models import AppBundle
+from ipa_forge.cli.common import extract_or_use, resolve_app_path
+from ipa_forge.machO.arch import AmbiguousArchError, ArchNotFoundError, NotMachOError
+from ipa_forge.machO.detect import bundle_executable_paths
+from ipa_forge.machO.objc import analyze_bundle
+
+app = typer.Typer(help="General-purpose IPA reverse engineering: class-dump, strings, symbols, security, diff.")
+
+
+def _select_binary(bundle: AppBundle, binary: str | None) -> Path:
+    """Resolve --binary to one executable path: the main executable when
+    omitted, otherwise the unique path whose bundle-relative string contains
+    the given substring."""
+    if binary is None:
+        return bundle.root / bundle.main_executable_name
+    matches = [p for p in bundle_executable_paths(bundle) if binary in str(p)]
+    if not matches:
+        typer.secho(f"error: no executable matching '{binary}' found in the bundle", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    if len(matches) > 1:
+        typer.secho(
+            f"error: '{binary}' matches multiple executables: {[str(p) for p in matches]} -- be more specific",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    return matches[0]
+
+
+@app.command("classdump")
+def analysis_classdump(
+    ipa: Path | None = typer.Option(None, "--ipa", exists=True, help="Input .ipa (not needed when --app-dir is given)"),
+    app_dir: Path | None = typer.Option(
+        None,
+        "--app-dir",
+        exists=True,
+        help="Already-extracted Payload/<App>.app directory to analyze instead of re-extracting the IPA",
+    ),
+    class_name: str | None = typer.Option(None, "--class", help="Restrict to one class"),
+    search: str | None = typer.Option(None, "--search", help="Only classes whose name matches this regex"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write to a file instead of stdout"),
+) -> None:
+    """Dump the app's Objective-C runtime metadata as `.h`-style class-dump
+    text: every class (superclass, protocol conformance, ivars, properties,
+    method signatures), protocol declarations, and categories. `--class`/
+    `--search` restrict output to matching classes only (protocols and
+    categories are omitted in that case, matching `forge hooks extract`)."""
+    with tempfile.TemporaryDirectory(prefix="ipa_forge_analysis_") as tmp:
+        app_path = extract_or_use(ipa, app_dir, Path(tmp))
+        bundle = load_bundle(app_path)
+        analysis = analyze_bundle(bundle)
+
+    if class_name and class_name not in analysis.classes:
+        typer.secho(f"class '{class_name}' not found", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1)
+
+    text = render_analysis(analysis, class_filter=class_name, search=search)
+    if not text:
+        typer.echo("no matching classes/protocols/categories found")
+        raise typer.Exit(code=1)
+
+    if output:
+        output.write_text(text + "\n")
+        typer.echo(f"wrote {output}")
+    else:
+        typer.echo(text)
+
+
+@app.command("strings")
+def analysis_strings(
+    ipa: Path | None = typer.Option(None, "--ipa", exists=True, help="Input .ipa (not needed when --app-dir is given)"),
+    app_dir: Path | None = typer.Option(
+        None,
+        "--app-dir",
+        exists=True,
+        help="Already-extracted Payload/<App>.app directory to analyze instead of re-extracting the IPA",
+    ),
+    min_len: int = typer.Option(4, "--min-len", help="Minimum printable-ASCII run length to report"),
+    search: str | None = typer.Option(None, "--search", help="Only strings matching this regex"),
+    binary: str | None = typer.Option(None, "--binary", help="Restrict to one executable (bundle-relative substring)"),
+) -> None:
+    """Extract printable strings from every executable in the bundle (main +
+    frameworks + dylibs + extensions), tagged with which binary each string
+    came from. Pipe to grep for anything not covered by --search."""
+    with tempfile.TemporaryDirectory(prefix="ipa_forge_analysis_") as tmp:
+        app_path = extract_or_use(ipa, app_dir, Path(tmp))
+        bundle = load_bundle(app_path)
+        found = strings_in_bundle(bundle, min_len=min_len)
+
+    if binary:
+        found = [s for s in found if binary in s.binary]
+    if search:
+        pat = _re.compile(search)
+        found = [s for s in found if pat.search(s.value)]
+
+    for s in found:
+        typer.echo(f"[{s.binary}] {s.value}")
+    typer.echo(f"-- {len(found)} string(s)", err=True)
+
+
+@app.command("symbols")
+def analysis_symbols(
+    ipa: Path | None = typer.Option(None, "--ipa", exists=True, help="Input .ipa (not needed when --app-dir is given)"),
+    app_dir: Path | None = typer.Option(
+        None,
+        "--app-dir",
+        exists=True,
+        help="Already-extracted Payload/<App>.app directory to analyze instead of re-extracting the IPA",
+    ),
+    binary: str | None = typer.Option(None, "--binary", help="Which executable to inspect; default: main executable"),
+    arch: str | None = typer.Option(None, "--arch", help="Architecture slice, required for a universal binary"),
+) -> None:
+    """Linked libraries and imported/exported symbols for one Mach-O
+    executable in the bundle (`otool -L` + `nm`, structured)."""
+    with tempfile.TemporaryDirectory(prefix="ipa_forge_analysis_") as tmp:
+        app_path = extract_or_use(ipa, app_dir, Path(tmp))
+        bundle = load_bundle(app_path)
+        target = _select_binary(bundle, binary)
+        try:
+            result = analyze_symbols(target, arch)
+        except (AmbiguousArchError, ArchNotFoundError, NotMachOError) as e:
+            typer.secho(f"error: {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from None
+
+    typer.echo(f"{result.binary} ({result.arch})")
+    typer.echo(f"linked libraries ({len(result.linked_libraries)}):")
+    for lib in result.linked_libraries:
+        typer.echo(f"  {lib}")
+    typer.echo(f"imported symbols ({len(result.imported_symbols)}):")
+    for sym in result.imported_symbols:
+        typer.echo(f"  {sym}")
+    typer.echo(f"exported symbols ({len(result.exported_symbols)}):")
+    for sym in result.exported_symbols:
+        typer.echo(f"  {sym}")
+
+
+@app.command("security")
+def analysis_security(
+    ipa: Path | None = typer.Option(None, "--ipa", exists=True, help="Input .ipa (not needed when --app-dir is given)"),
+    app_dir: Path | None = typer.Option(
+        None,
+        "--app-dir",
+        exists=True,
+        help="Already-extracted Payload/<App>.app directory to analyze instead of re-extracting the IPA",
+    ),
+    binary: str | None = typer.Option(None, "--binary", help="Which executable to inspect; default: main executable"),
+    arch: str | None = typer.Option(None, "--arch", help="Architecture slice, required for a universal binary"),
+) -> None:
+    """PIE, encryption-flag (detection only, never decrypted), stack
+    protector, an ARC heuristic, min-OS, and platform for one executable."""
+    with tempfile.TemporaryDirectory(prefix="ipa_forge_analysis_") as tmp:
+        app_path = extract_or_use(ipa, app_dir, Path(tmp))
+        bundle = load_bundle(app_path)
+        target = _select_binary(bundle, binary)
+        try:
+            posture = analyze_security(target, arch)
+        except (AmbiguousArchError, ArchNotFoundError, NotMachOError) as e:
+            typer.secho(f"error: {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from None
+
+    typer.echo(render_security_posture(posture))
+
+
+@app.command("diff")
+def analysis_diff(
+    old_ipa: Path | None = typer.Option(
+        None, "--old", exists=True, help="Previous-version .ipa (not needed with --old-app-dir)"
+    ),
+    new_ipa: Path | None = typer.Option(
+        None, "--new", exists=True, help="New-version .ipa (not needed with --new-app-dir)"
+    ),
+    old_app_dir: Path | None = typer.Option(
+        None, "--old-app-dir", exists=True, help="Extracted Payload/<App>.app of the old build"
+    ),
+    new_app_dir: Path | None = typer.Option(
+        None, "--new-app-dir", exists=True, help="Extracted Payload/<App>.app of the new build"
+    ),
+) -> None:
+    """Survey what changed between two builds of the same app: classes and
+    protocols added/removed, per-class method churn, and Info.plist key
+    changes. Broader and purely informational compared to `forge hooks
+    diff`, which only re-checks one patch definition's declared hook
+    targets and fails the exit code on a required-hook regression."""
+    with tempfile.TemporaryDirectory(prefix="ipa_forge_analysis_") as tmp:
+        try:
+            old_path = resolve_app_path(old_ipa, old_app_dir, Path(tmp) / "old")
+            new_path = resolve_app_path(new_ipa, new_app_dir, Path(tmp) / "new")
+        except ValueError as e:
+            typer.secho(f"error: {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from None
+        bundle_old = load_bundle(old_path)
+        bundle_new = load_bundle(new_path)
+        diff = diff_analyses(
+            analyze_bundle(bundle_old),
+            analyze_bundle(bundle_new),
+            bundle_old.info_plist,
+            bundle_new.info_plist,
+        )
+
+    typer.echo(f"{bundle_old.bundle_id} {bundle_old.version} -> {bundle_new.version}")
+    typer.echo(render_diff(diff))

ipa_forge/cli/common.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Shared CLI helpers. The extraction helper lives in the bundle domain
+(ipa_forge.bundle.ipa.validate_and_extract); this module re-exports it so
+CLI code reads cleanly, and provides the --app-dir resolution used by the
+`forge hooks` and `forge analysis` commands to skip re-extraction during
+iteration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ipa_forge.bundle.ipa import validate_and_extract as validated_extract  # noqa: F401
+
+
+def resolve_app_path(ipa: Path | None, app_dir: Path | None, dest: Path) -> Path:
+    """Return the app bundle to analyze: the already-extracted ``app_dir``
+    when given, otherwise extract ``ipa`` into ``dest``.
+
+    Exactly one of the two inputs must be set — passing both is a mistake
+    (the dir would silently take precedence over a fresh extract) and passing
+    neither leaves nothing to analyze.
+    """
+    if app_dir is not None and ipa is not None:
+        raise ValueError("pass either --ipa or --app-dir, not both")
+    if app_dir is not None:
+        return app_dir
+    if ipa is None:
+        raise ValueError("--ipa is required when --app-dir is not given")
+    return validated_extract(ipa, dest)
+
+
+def extract_or_use(ipa: Path | None, app_dir: Path | None, tmp: Path) -> Path:
+    """`resolve_app_path`, with resolution errors reported as a clean
+    single-line CLI error instead of a traceback."""
+    try:
+        return resolve_app_path(ipa, app_dir, tmp)
+    except ValueError as e:
+        typer.secho(f"error: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from None