everettjf/copyapp/copyapp-analyze

Analyze an installed iOS app

For an ordinary or inactive-jailbreak phone, read standard mode (中文). Use analyze or prepare-app --mode standard --script ... and review its TASK.md into an ios_behavior_report with observed/inferred/unknown claims, exact script hashes and post-action assertions; finish its analysis-delivery. This UI contract needs no original package, sandbox or native-function interpretation, and must not be called a deep-function report. If those deeper conclusions are requested but unavailable, retain the missing scope explicitly. For --mode enhanced, the validated enhanced/ child is the legacy analysis input for the existing investigate-app, prepare-analysis and formal deep-report steps below; keep those citations and observation times separate from ordinary UI evidence. Do not pass the v2 UI parent where an old command requires a legacy analysis-index. Standalone imported/offline packages may supplement static claims, but version/build agreement alone does not establish phone runtime identity.

Work in the Copy APP repository. Read README.md for setup, docs/copy-workflow.md for the handoffs, and docs/architecture.md for evidence boundaries. Use an exact USB device ID and bundle ID. Record system version, jailbreak state, app version, and acquisition method before connecting UI and binary claims.

New direct Ghidra cases also contain function-facts.json v2 with bounded static callers, callees, a signature, basic blocks, instruction references and short previews of recognized strings. Read it beside pseudocode.txt; cite its exact case in the report and keep unresolved indirect calls and runtime execution as separate questions. Historical v1 cases remain valid under their saved schema.

1. When 1–12 bounded original App playbooks are ready, use copyapp prepare-app --udid <UDID> --bundle <BUNDLE_ID> --script <PLAYBOOK> ... --out <CASE> to collect the installed App without REA by default, investigate the selected flows, and prepare a verified semantic review task. Add --decrypt for an encrypted App when the pinned helper and root Frida channel are ready. Use the same arguments with --resume after failure; complete stages are source-verified and reused. The resulting preparation/draft/TASK.md still requires agent semantic review. If scripts are not yet available, start with copyapp analyze; it composes the collectors and records partial failures. If a new case fails, repair the cause and use copyapp analyze with the same UDID, Bundle ID and output plus --resume. It reuses only identity/hash-verified stages, archives failed partial output under attempts/, and retains prior errors in run-state.json. Do not resume a case whose App version has changed; begin a fresh case. Otherwise use copyapp survey, then copyapp verify. Examine the screenshot and UI tree before attributing the screen to the target; a successful launch request alone does not prove foreground ownership.
2. If the USB SSH tunnel and dedicated key are configured, run copyapp acquire and copyapp sandbox. The bundle snapshot is an analysis IPA. The sandbox index contains metadata only. For a selected state-changing flow, collect copyapp sandbox before and after a completed UI playbook, then run copyapp sandbox-diff --before ... --after ... --action ... --out ...; verify the result and import its directory into copyapp report. The comparison checks device, App, container, depth and action timing, but metadata alone does not prove file content. To inspect a specific indexed regular file, use copyapp sandbox-file --udid <UDID> --analysis <VERIFIED_ANALYSIS> --path <CONTAINER_RELATIVE_FILE> --out <CAPTURE>; it pins the app container and retains the local raw bytes in ignored cases/. For a selected SQLite database, run copyapp sqlite-schema --case <CAPTURE> --path files/<CONTAINER_RELATIVE_FILE> --out <SCHEMA>. For a preference plist, use copyapp plist-schema with the same capture case and relative path; it outputs bounded key paths and types without values. Import the resulting structure cases into a report based on the same analysis. Keep raw copies local, mark sequential/WAL snapshots as potentially non-atomic, and do not infer the app's read/write path from schema alone. Keep the original hashes and tool errors.
3. Run copyapp ipa against the acquired snapshot. If any executable is encrypted and the device has the verified root Frida and paired mobile SSH channels, prepare the pinned helper with sh scripts/prepare-ipadecrypt-helper.sh and either pass --decrypt to copyapp analyze or run copyapp decrypt-package --udid <UDID> --bundle <BUNDLE_ID> --snapshot <ACQUIRE_CASE>/bundle-snapshot.ipa --out <DECRYPT_CASE>. This command checks every Mach-O and rejects changes outside the encrypted ranges and cryptid fields. It automatically indexes the recovered IPA and main executable's Objective-C metadata. Run copyapp verify <DECRYPT_CASE> on a standalone result; current cases include a manifest that rechecks source identity, changed code bytes, unchanged members and canonical ZIP layout. Use the recovered analysis IPA for further static work only when decryption.json records a full pass. Preserve partial output and errors if the device or app is incompatible; cryptid=0 alone is insufficient proof. Do not claim the output is installable. Distinguish “no encryption load command” from “decrypted by this workflow.” Record linked libraries, embedded code, resources, entitlements, classes, and candidate methods without treating imports as locally defined classes. Objective-C metadata gives selector names and static addresses, not method bodies.
4. For selected static candidates, first use copyapp native-queue --candidates <CANDIDATE_CASE> --out <NATIVE_QUEUE> when Xcode llvm-objdump is available; review bounded ARM64 assembly, direct calls, and any unique local follow decisions without treating them as original source or runtime proof. For pseudocode without REA, run copyapp ghidra-queue --candidates <CANDIDATE_CASE> --native <NATIVE_QUEUE> --ghidra-dir <GHIDRA_INSTALL_DIR> --java-home <JDK_HOME> --out <QUEUE>, or select --provider ghidra-direct at the investigation/preparation entry. The native source is optional for a standalone queue and automatic in investigation; it adds only verified unique direct local followers, marked as static evidence. This uses Copy APP-owned Ghidra scripts and preserves candidate, native, and binary hashes. If Ghidra auto-analysis times out, reject its partial pseudocode and retry with a recorded analyzer profile when justified. Archived REA cases may be read as historical evidence; new analysis uses native inspection or direct Ghidra. For a method in the local Objective-C index, run copyapp experiment --binary <EXACT_APP_BINARY> --objc-index <INDEX_JSON> ... to count both its current Objective-C IMP and its original app entry during one gesture. This covers system or accessibility wrappers that replace the current IMP. Then run copyapp candidates --udid <UDID> --bundle <BUNDLE_ID> --binary <EXACT_BINARY> --objc-index <INDEX_JSON> --experiment <EXPERIMENT_DIR> --out <CANDIDATE_CASE> and verify the output. For a traced flow-capture case, pass --flow <FLOW_CASE> instead; the candidate case retains counts and evidence for each tap step. A mismatched current IMP is preserved as a conflict; a separately hooked, nonzero static entry can establish a candidate despite that mismatch. Without direct static-entry evidence, a mismatched current IMP excludes the candidate. Older experiments without offset evidence remain class/selector candidates only. Matching paths and offsets do not prove loaded code bytes are identical or that the gesture caused every call. Use copyapp ghidra-function for a pinned address and copyapp ghidra-queue for a bounded verified candidate queue. Explain selected user-visible flows by joining UI evidence with method relationships and any available decompiler pseudocode; mark unobserved function bodies unknown. For a running app with Frida, copyapp trace --method 'ClassName::selector:' can count calls in a bounded window; distinguish a zero count from an attach failure. Mark static call chains as inferred until a device interaction or trace verifies them. Do not present pseudocode as the author's source.

For a fresh flow on a verified analysis case, prefer copyapp investigate-flow --udid <UDID> --analysis <CASE> --script <PLAYBOOK> --out <INVESTIGATION>; it composes method scouting, UI capture, any available Frida/candidate evidence and bounded Xcode ARM64 assembly. Missing llvm-objdump is recorded and does not block the investigation. Add --provider ghidra-direct for pseudocode. The scout selects a clearly leading action method and any unique exact matches between tap labels and action method suffixes; it may select several methods for one flow. Ambiguous methods leave a reviewable shortlist and UI evidence without method trace; inspect the shortlist and run a new case with an explicit --method 'Class::selector:' if necessary. After a later failure, --resume validates and reuses completed stages, so do not repeat device gestures to repair an offline stage. For multiple selected flows, run copyapp investigate-app with repeated --script; resume the same task after a failure so completed child flows are validated and skipped. The parent can be imported into copyapp report as one evidence ID. Read each review-brief.md, then review any direct Ghidra or native call evidence and write evidence-backed conclusions; the brief is an observation index, not a final report. If selected direct Ghidra or native assembly ends at blr xN, use copyapp ghidra-indirect --udid <UDID> --investigation <FLOW_INVESTIGATION> --objc-index <MATCHING_INDEX> --ghidra-dir <DIR> --java-home <DIR> --out <NEW_CASE> to find bounded sites, replay the saved original playbook with register capture, and decompile observed app-image targets. Review run.json, the same-step Frida trace, and each function's source binding; import the queue/ child into copyapp report and cite its evidence ID in the corresponding feature-spec flow so the implementation task links its pseudocode. If only Ghidra fails after the phone replay completed, repeat the same command and output with --resume; it archives the failed queue and does not touch the phone again. A failed phone replay needs a new case after reviewing app state. Temporal hits and decompiler output still require semantic review before stating why a screen changed. After a complete investigate-app, run copyapp draft-analysis --analysis <CASE> --investigation <APP_INVESTIGATION> --out <DRAFT>. It validates the complete cross-flow chain and creates a cited fact-only report, provisional findings.json and feature-spec.json, plus review-dossier.md and a verified TASK.md/task.json linking each source script, screenshot, view tree and any available trace or pseudocode from Copy APP direct Ghidra. In an active coding-agent session, follow TASK.md yourself; from a standalone terminal, copyapp agent-run --task <DRAFT> --provider codex|claude --verify-analysis --out <RUN> gives the installed agent an exact <RUN>/reviewed-report destination and checks it with analysis-delivery after exit. Inspect <RUN>/analysis-verification.json and the verified <RUN>/analysis-delivery/ case; CLI exit alone does not prove the report. Treat review_status=needs_semantic_review as a mandatory review gate: inspect available pseudocode and data effects, replace generic expected behavior with concrete scenarios, mark unknowns, then produce and verify the final copyapp report from revised findings/spec. Do not present the generated factual draft as the requested deep report.

1. When the iOS MCP service is installed, use copyapp ui health, observe, ocr, `scr