SILVER
/
NODEDC_MISSION_CORE
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_MISSION_CORE/plugins/xgrids-k1/lab/iphone-capture/README.md

2.6 KiB
Raw Blame History

iPhone / LixelGO capture lab

This is an isolated evidence tool for the XGRIDS K1 plugin. It is not a Mission Core runtime dependency and must not be bundled without a separate GPL license review.

Install without Xcode

From the repository root:

uv sync --project plugins/xgrids-k1/lab/iphone-capture --frozen

The environment is created under the lab directory. It pins pymobiledevice3==9.36.0; it does not modify the system Python, Homebrew, the Mission Core .venv, or the root lockfile.

USB preflight

Connect exactly one iPhone with a data-capable USB cable, unlock it, confirm the Mac accessory prompt, and tap Trust This Computer on the iPhone. Then run:

uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
  python plugins/xgrids-k1/lab/iphone-capture/preflight.py

The preflight prints only a device count. It never prints or stores the iPhone UDID or serial number.

Bounded network capture

Run this only after the post-refactor exact-profile K1 regression in ADR 0004:

uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
  python plugins/xgrids-k1/lab/iphone-capture/capture.py \
  --duration 120

The capture uses the iPhone pcapd service over USB, suppresses packet hex on stdout, and writes private artifacts under ignored sessions/iphone-k1-observation/. It is intentionally bounded to 5–600 seconds. Each successful run retains the original metadata-bearing PCAPNG and creates a classic Ethernet PCAP that the macOS bundled tcpdump can read. The redacted manifest records the validated packet count and hashes both artifacts. The default refuses a dirty repository; --allow-dirty records a source-tree fingerprint when an explicitly approved lab run cannot wait for a commit.

Operator events may be recorded while the capture is active and can finish after the bounded network process exits. Preserve the original capture manifest and create a separate integrity inventory after the operator timeline is closed:

uv run python plugins/xgrids-k1/lab/iphone-capture/session_integrity.py \
  sessions/iphone-k1-observation/<session>

The sealer re-hashes every manifest artifact, adds the manifest and optional operator-events.private.jsonl, and writes an ignored mode-0600 integrity.private.json. It never edits the original manifest or raw capture.

Do not add --bluetooth unless Apple's Bluetooth diagnostic logging profile is already installed on the iPhone and the operator explicitly approved that configuration change. The script never installs the profile.

Wireshark is optional and is not required to record PCAP/PCAPNG. Full Xcode is also not required for this path.