traceveil 0.1.0__py3-none-any.whl

traceveil/__init__.py

@@ -0,0 +1,12 @@
+"""Traceveil developer CLI: drives an iQOO/Android device over adb and reports network-environment signals."""
+
+__version__ = "0.1.0"
+
+# Process exit codes, also reported in the JSON verdict.
+EXIT_PASS = 0
+EXIT_FINDINGS = 1
+EXIT_INCONCLUSIVE = 2
+EXIT_DEVICE = 3
+EXIT_USAGE = 4
+EXIT_POLICY = 5
+EXIT_TIMEOUT = 6

traceveil/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

traceveil/adb.py

@@ -0,0 +1,142 @@
+"""adb discovery and a thin device wrapper. WSL2 cannot see USB phones, so the Windows adb.exe is a first-class target."""
+
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+
+class AdbError(Exception):
+    """Raised for problems the user can fix (no adb, no device, unauthorized)."""
+
+
+class AdbDisconnected(AdbError):
+    """The phone dropped off adb mid-command (cable, sleep, adb restart). Usually recoverable by reconnecting."""
+
+
+_GONE_MARKERS = ("device offline", "no devices/emulators", "not found", "closed", "protocol fault", "unauthorized")
+
+
+def candidates(explicit: str | None = None, env: dict | None = None, which=shutil.which, globber=glob.glob) -> list[tuple[str, bool]]:
+    """(adb path, pinned) in preference order. Pinned entries (--adb / $ADB) are never replaced by a fallback."""
+    env = os.environ if env is None else env
+    for pinned in (explicit, env.get("ADB")):
+        if pinned:
+            return [(pinned, True)]
+    found = []
+    path_adb = which("adb")
+    if path_adb:
+        found.append((path_adb, False))
+    found += [(w, False) for w in sorted(globber("/mnt/c/Users/*/AppData/Local/Android/Sdk/platform-tools/adb.exe"))]
+    return found
+
+
+def find_adb(explicit: str | None = None, env: dict | None = None, which=shutil.which, globber=glob.glob) -> str:
+    env = os.environ if env is None else env
+    for candidate in (explicit, env.get("ADB")):
+        if candidate:
+            return candidate
+    found = which("adb")
+    if found:
+        return found
+    wsl = sorted(globber("/mnt/c/Users/*/AppData/Local/Android/Sdk/platform-tools/adb.exe"))
+    if wsl:
+        return wsl[0]
+    raise AdbError("adb not found: pass --adb, set $ADB, or install Android platform-tools")
+
+
+@dataclass(frozen=True)
+class DeviceEntry:
+    serial: str
+    state: str
+    model: str = ""
+
+
+def parse_devices(text: str) -> list[DeviceEntry]:
+    out = []
+    for raw in text.replace("\r", "").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("List of devices") or line.startswith("*"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        model = next((p.split(":", 1)[1] for p in parts[2:] if p.startswith("model:")), "")
+        out.append(DeviceEntry(parts[0], parts[1], model))
+    return out
+
+
+def select_device(entries: list[DeviceEntry], serial: str | None) -> DeviceEntry:
+    if serial:
+        match = [e for e in entries if e.serial == serial]
+        if not match:
+            raise AdbError(f"device {serial} not found; attached: {[e.serial for e in entries] or 'none'}")
+        entry = match[0]
+    else:
+        ready = [e for e in entries if e.state == "device"]
+        if len(entries) > 1 and len(ready) != 1:
+            raise AdbError("several devices attached; choose one with --serial")
+        if not entries:
+            raise AdbError("no device attached: connect the phone and enable USB debugging")
+        entry = ready[0] if ready else entries[0]
+    if entry.state == "unauthorized":
+        raise AdbError("device is unauthorized: unlock the phone and tap Allow on the USB debugging prompt")
+    if entry.state != "device":
+        raise AdbError(f"device {entry.serial} is {entry.state}; reconnect the cable or restart adb")
+    return entry
+
+
+class Device:
+    def __init__(self, adb: str, serial: str, timeout: float = 20.0, runner=subprocess.run):
+        self.adb, self.serial, self.timeout, self._run = adb, serial, timeout, runner
+
+    def _cmd(self, *args: str) -> list[str]:
+        return [self.adb, "-s", self.serial, *args]
+
+    def shell(self, command: str) -> str:
+        try:
+            proc = self._run(self._cmd("shell", command), capture_output=True, text=True, timeout=self.timeout)
+        except subprocess.TimeoutExpired as e:
+            raise AdbError(f"adb timed out running: {command}") from e
+        return proc.stdout.replace("\r", "")
+
+    def shell_checked(self, command: str) -> str:
+        """Like [shell] but raises [AdbDisconnected] when adb says the device is gone. Remote command failures
+        (for example `cat` of a missing file) are returned as text, not raised."""
+        try:
+            proc = self._run(self._cmd("shell", command), capture_output=True, text=True, timeout=self.timeout)
+        except subprocess.TimeoutExpired as e:
+            raise AdbDisconnected(f"adb timed out running: {command}") from e
+        err = (proc.stderr or "").lower()
+        if proc.returncode != 0 and err.startswith("error:") and any(m in err for m in _GONE_MARKERS):
+            raise AdbDisconnected((proc.stderr or "").strip())
+        return (proc.stdout + ("" if proc.returncode == 0 else proc.stderr or "")).replace("\r", "")
+
+    def getprop(self, key: str) -> str:
+        return self.shell(f"getprop {key}").strip()
+
+    def setting(self, namespace: str, key: str) -> str | None:
+        value = self.shell(f"settings get {namespace} {key}").strip()
+        return None if value in ("", "null") else value
+
+
+def connect(explicit_adb: str | None, serial: str | None, timeout: float = 20.0, runner=subprocess.run,
+            cands: list[tuple[str, bool]] | None = None) -> Device:
+    """Tries each adb candidate until one lists a device. Under WSL2 the Linux adb on PATH sees no USB phones, so the
+    Windows adb.exe is tried next."""
+    cands = cands if cands is not None else candidates(explicit_adb)
+    if not cands:
+        raise AdbError("adb not found: pass --adb, set $ADB, or install Android platform-tools")
+    last = None
+    for adb, _pinned in cands:
+        proc = runner([adb, "devices", "-l"], capture_output=True, text=True, timeout=timeout)
+        entries = parse_devices(proc.stdout)
+        if entries:
+            entry = select_device(entries, serial or os.environ.get("SERIAL"))
+            return Device(adb, entry.serial, timeout, runner)
+        last = adb
+    raise AdbError(f"no device attached (tried {', '.join(a for a, _ in cands)}): connect the phone and enable USB debugging; "
+                   "under WSL2 use the Windows adb.exe via --adb")

traceveil/audit.py

@@ -0,0 +1,212 @@
+"""`traceveil audit`: trigger a debug-build audit on the phone over adb, wait, fetch and validate its JSON report."""
+
+from __future__ import annotations
+
+import json
+import re
+import secrets
+import shlex
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+from . import EXIT_DEVICE, EXIT_FINDINGS, EXIT_INCONCLUSIVE, EXIT_PASS, EXIT_TIMEOUT, EXIT_USAGE, adb
+from .netenv import OWN_PACKAGE
+
+ACTION = "com.dpdpxray.app.debug.RUN_AUDIT"
+RECEIVER = f"{OWN_PACKAGE}/.cli.DebugAuditReceiver"
+REMOTE_REPORTS = f"/sdcard/Android/data/{OWN_PACKAGE}/files/reports"
+SCHEMA_VERSION = 1
+SEVERITY_ORDER = ["info", "low", "medium", "high", "critical"]
+REQUIRED_KEYS = ("schemaVersion", "requestId", "auditId", "target", "score", "band", "findings", "sessions")
+
+
+@dataclass
+class Io:
+    sleep: Callable[[float], None] = time.sleep
+    clock: Callable[[], float] = time.monotonic
+    out: object = None
+    err: object = None
+    interactive: bool = False
+    color: bool = False
+    prompt: Callable[[str], str] = input
+    poll_s: float = 2.0
+
+    def __post_init__(self):
+        self.out = self.out or sys.stdout
+        self.err = self.err or sys.stderr
+
+
+def paint(text: str, code: str, enabled: bool) -> str:
+    return f"\x1b[{code}m{text}\x1b[0m" if enabled else text
+
+
+def new_request_id() -> str:
+    return f"cli-{datetime.now(timezone.utc):%Y%m%dT%H%M%SZ}-{secrets.token_hex(4)}"
+
+
+def _remote(request_id: str, name: str) -> str:
+    return f"{REMOTE_REPORTS}/{request_id}/{name}"
+
+
+def _fail(io: Io, msg: str, code: int) -> int:
+    print(paint(f"error: {msg}", "1;31", io.color), file=io.err)
+    return code
+
+
+def _json_or_none(text: str):
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def trigger(dev, request_id: str, package: str, plans: str | None, auto_drive: bool, reset: bool) -> tuple[bool, str]:
+    """Sends the debug broadcast. Returns (accepted, reason)."""
+    extras = f"--es request_id {shlex.quote(request_id)} --es package {shlex.quote(package)}"
+    if plans:
+        extras += f" --es plans {shlex.quote(plans)}"
+    if auto_drive:
+        extras += " --es auto_drive true"
+    if reset:
+        extras += " --es reset true"
+    out = dev.shell_checked(f"am broadcast -a {ACTION} -n {RECEIVER} {extras}")
+    m = re.search(r"result=(\d+)", out)
+    code = int(m.group(1)) if m else 0
+    if code == 1:
+        return True, "accepted"
+    if code == 2:
+        d = re.search(r'data="([^"]*)"', out)
+        return False, d.group(1) if d else "the app rejected the request"
+    return False, ("no debug trigger answered: install a debug build of Traceveil and open it once (a never-opened or "
+                   "force-stopped app does not receive broadcasts); release builds have no trigger by design")
+
+
+def validate_report(text: str, request_id: str) -> tuple[dict | None, str]:
+    rep = _json_or_none(text)
+    if not isinstance(rep, dict):
+        return None, "report.json is not valid JSON"
+    missing = [k for k in REQUIRED_KEYS if k not in rep]
+    if missing:
+        return None, f"report.json is missing {', '.join(missing)}"
+    if rep["schemaVersion"] != SCHEMA_VERSION:
+        return None, f"report.json schemaVersion {rep['schemaVersion']!r} is not supported (expected {SCHEMA_VERSION})"
+    if rep["requestId"] != request_id:
+        return None, "report.json belongs to a different request"
+    if not isinstance(rep["findings"], list) or not isinstance(rep["sessions"], list):
+        return None, "report.json findings/sessions are not lists"
+    return rep, ""
+
+
+def exit_for_report(rep: dict, fail_on: str, min_score: int) -> tuple[int, list[str]]:
+    if rep.get("score") is None or rep.get("band") == "INCONCLUSIVE":
+        return EXIT_INCONCLUSIVE, ["audit result is inconclusive (no score)"]
+    reasons = []
+    if rep["score"] < min_score:
+        reasons.append(f"score {rep['score']} is below min_score {min_score}")
+    if fail_on in SEVERITY_ORDER:
+        bar = SEVERITY_ORDER.index(fail_on)
+        hits = [f for f in rep["findings"] if isinstance(f, dict) and str(f.get("severity", "")).lower() in SEVERITY_ORDER
+                and SEVERITY_ORDER.index(str(f["severity"]).lower()) >= bar]
+        if hits:
+            reasons.append(f"{len(hits)} finding(s) at or above {fail_on}")
+    return (EXIT_FINDINGS if reasons else EXIT_PASS), reasons
+
+
+def summary(rep: dict, reasons: list[str], saved: Path) -> str:
+    t = rep["target"]
+    lines = [f"Traceveil audit  {t.get('label', '?')} ({t.get('package', '?')})  score {rep['score']} / {rep['band']}  findings {len(rep['findings'])}"]
+    for f in rep["findings"]:
+        lines.append(f"  {f.get('check', '?'):<4} {f.get('severity', '?'):<8} {f.get('title', '')}")
+    for r in reasons:
+        lines.append(f"  policy: {r}")
+    lines.append(f"  report saved: {saved}")
+    return "\n".join(lines)
+
+
+def _wait_for_device(dev, io: Io, deadline: list[float], request_id: str) -> bool:
+    """Called after adb dropped. Tells the user to reconnect; True once adb answers again, False to give up."""
+    print(paint(f"Device disconnected. Reconnect the cable, unlock the phone and accept USB debugging if asked. The audit keeps "
+                f"running on the phone; resume later with: traceveil audit --resume {request_id}", "1;33", io.color), file=io.err)
+    while True:
+        if io.interactive:
+            started = io.clock()
+            answer = io.prompt(paint("Press Enter to retry, or type q to quit: ", "1;36", io.color)).strip().lower()
+            deadline[0] += io.clock() - started  # time the user spent at the prompt does not count against --wait
+            if answer == "q":
+                return False
+        else:
+            if io.clock() >= deadline[0]:
+                return False
+            io.sleep(io.poll_s)
+        try:
+            dev.shell_checked("echo ok")
+            print(paint("Device reconnected, continuing.", "1;32", io.color), file=io.err)
+            return True
+        except adb.AdbDisconnected:
+            if not io.interactive and io.clock() >= deadline[0]:
+                return False
+
+
+def run_audit(dev, cfg: dict, io: Io, *, package: str, plans: str | None, auto_drive: bool, reset: bool, wait_s: float,
+              resume: str | None, as_json: bool, out_file: str | None, request_id: str | None = None,
+              fail_on_override: str | None = None) -> int:
+    request_id = resume or request_id or new_request_id()
+    package = package or cfg["target"]["package"]
+    if not resume and not package:
+        return _fail(io, "no target app: pass --package or set target.package in traceveil.toml", EXIT_USAGE)
+    try:
+        if not resume:
+            if f"package:{OWN_PACKAGE}" not in dev.shell_checked(f"pm list packages {OWN_PACKAGE}").split():
+                return _fail(io, f"{OWN_PACKAGE} is not installed on the device (install the debug APK)", EXIT_DEVICE)
+            ok, reason = trigger(dev, request_id, package, plans, auto_drive, reset)
+            if not ok:
+                return _fail(io, f"audit was not started: {reason}", EXIT_DEVICE)
+            print(f"audit started: {request_id}", file=io.err)
+    except adb.AdbDisconnected as e:
+        return _fail(io, f"device disconnected before the audit started ({e}); reconnect and run again", EXIT_DEVICE)
+
+    deadline = [io.clock() + wait_s]
+    last_step = ""
+    while True:
+        try:
+            raw = dev.shell_checked(f"cat {shlex.quote(_remote(request_id, 'status.json'))}")
+            state = _json_or_none(raw)
+            if isinstance(state, dict):
+                last_step = state.get("step") or last_step
+                if state.get("state") == "failed":
+                    return _fail(io, f"audit failed on the device: {state.get('error') or 'no reason given'}", EXIT_INCONCLUSIVE)
+                if state.get("state") == "done":
+                    break
+        except adb.AdbDisconnected:
+            if not _wait_for_device(dev, io, deadline, request_id):
+                return _fail(io, f"device not reachable; audit may still be running. Resume with: traceveil audit --resume {request_id}", EXIT_DEVICE)
+            continue
+        if io.clock() >= deadline[0]:
+            return _fail(io, f"timed out after {wait_s:.0f}s (last step: {last_step or 'unknown'}). The audit was not cancelled; "
+                             f"fetch it later with: traceveil audit --resume {request_id}", EXIT_TIMEOUT)
+        io.sleep(io.poll_s)
+
+    try:
+        text = dev.shell_checked(f"cat {shlex.quote(_remote(request_id, 'report.json'))}")
+    except adb.AdbDisconnected as e:
+        return _fail(io, f"device disconnected while fetching the report ({e}); resume with: traceveil audit --resume {request_id}", EXIT_DEVICE)
+    if "No such file" in text:
+        return _fail(io, "audit finished but report.json is missing on the device", EXIT_INCONCLUSIVE)
+    rep, problem = validate_report(text, request_id)
+    if rep is None:
+        return _fail(io, problem, EXIT_INCONCLUSIVE)
+
+    out_dir = Path(cfg["output"]["dir"])
+    out_dir.mkdir(parents=True, exist_ok=True)
+    saved = out_dir / f"{request_id}.json"
+    saved.write_text(json.dumps(rep, indent=2), encoding="utf-8")
+    if out_file:
+        Path(out_file).parent.mkdir(parents=True, exist_ok=True)
+        Path(out_file).write_text(json.dumps(rep, indent=2), encoding="utf-8")
+    code, reasons = exit_for_report(rep, fail_on_override or cfg["audit"]["fail_on"], int(cfg["audit"]["min_score"]))
+    print(json.dumps(rep, indent=2) if as_json else summary(rep, reasons, saved), file=io.out)
+    return code

traceveil/cli.py

@@ -0,0 +1,139 @@
+"""traceveil command line: doctor, env, init, audit."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import (audit, EXIT_DEVICE, EXIT_PASS, EXIT_POLICY, EXIT_USAGE, __version__, adb, config, egress, netenv, report, shizuku)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="traceveil", description="Traceveil developer CLI (iQOO/Android over adb).")
+    p.add_argument("--version", action="version", version=f"traceveil {__version__}")
+    p.add_argument("--config", help="path to traceveil.toml / traceveil.json")
+    p.add_argument("--serial", help="device serial (default: the only attached device, or $SERIAL)")
+    p.add_argument("--adb", help="adb binary (default: $ADB, PATH, then Windows adb.exe under WSL)")
+    p.add_argument("--timeout", type=float, default=20.0, help="seconds per adb command")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    d = sub.add_parser("doctor", help="check adb, device and Traceveil readiness (starts Shizuku over adb if it is down)")
+    d.add_argument("--no-start-shizuku", action="store_true", help="only report the Shizuku server state; do not start it")
+    sub.add_parser("init", help="write a traceveil.toml with defaults").add_argument("--force", action="store_true")
+
+    a = sub.add_parser("audit", help="run an audit on the phone (debug build), wait, and save its JSON report")
+    a.add_argument("--package", help="app to audit (default: target.package)")
+    a.add_argument("--plans", help="comma list of silent,reject,accept (default: all three)")
+    a.add_argument("--auto-drive", action="store_true", help="let Traceveil tap Accept/Reject itself (default: you tap on the phone)")
+    a.add_argument("--reset", action="store_true", help="clear the app's data first; only for developer-owned test apps; needs Shizuku")
+    a.add_argument("--wait", type=float, default=900.0, help="seconds to wait for the audit (default 900)")
+    a.add_argument("--resume", metavar="REQUEST_ID", help="fetch the result of an earlier request instead of starting a new audit")
+    a.add_argument("--json", action="store_true", help="print the JSON report instead of the summary")
+    a.add_argument("--out", help="also write the JSON report to this file")
+
+    e = sub.add_parser("env", help="network-environment snapshot (VPN/proxy/geography signals)")
+    e.add_argument("--check-vpn", choices=config.CHECK_VPN_MODES, help="off | warn | fail (exit 5 on a likely VPN/proxy)")
+    e.add_argument("--online-ip", action="store_true", help="one cached lookup to network.endpoint; sends the public IP to that service")
+    e.add_argument("--egress-from", choices=("phone", "host"), default="phone",
+                   help="where the lookup runs: phone (device curl, default) or host (this machine's network)")
+    e.add_argument("--keep-ip", action="store_true", help="store the full public IP instead of a redacted prefix")
+    e.add_argument("--include-own-vpn", action="store_true", help="count Traceveil's own capture VPN (debugging aid)")
+    e.add_argument("--json", action="store_true", help="print the JSON report instead of the summary")
+    e.add_argument("--out", help="also write the JSON report to this file")
+    return p
+
+
+def _device_info(dev: adb.Device) -> dict:
+    return {"model": dev.getprop("ro.product.model"), "androidVersion": dev.getprop("ro.build.version.release"),
+            "serialHash": report.serial_hash(dev.serial)}
+
+
+def cmd_doctor(args, cfg, dev: adb.Device) -> int:
+    pkgs = dev.shell("pm list packages").replace("package:", "")
+    installed = lambda name: f"\n{name}\n" in f"\n{pkgs}\n"  # noqa: E731
+    rows = [("adb", True, dev.adb), ("device", True, f"{dev.getprop('ro.product.brand')} {dev.getprop('ro.product.model')}, Android {dev.getprop('ro.build.version.release')}"),
+            ("Traceveil installed", installed(netenv.OWN_PACKAGE), netenv.OWN_PACKAGE),
+            ("Shizuku installed", installed(shizuku.PACKAGE), "needed for fresh-install resets"),
+            ("USB install allowed", (dev.setting("secure", "install_non_market_apps") or "") == "1", "Developer options > Install via USB")]
+    if installed(shizuku.PACKAGE):
+        if args.no_start_shizuku:
+            running, note = shizuku.is_running(dev), "not started (--no-start-shizuku)"
+        else:
+            running, note = shizuku.start(dev)
+        rows.append(("Shizuku server running", running, note))
+    pdns = dev.setting("global", "private_dns_mode")
+    # An unset mode is Android's "Automatic": encrypted DNS can be used, which hides lookups from capture.
+    rows.append(("Private DNS off", pdns == "off", f"mode={pdns or 'unset (Automatic)'}; set Private DNS to Off so lookups stay visible"))
+    bad = 0
+    for name, ok, note in rows:
+        bad += 0 if ok else 1
+        print(f"  [{'ok' if ok else '!!'}] {name:<22} {note}")
+    print("  note: VPN permission, accessibility service and Shizuku grant are app-side and are checked from the Traceveil home screen.")
+    return EXIT_PASS if bad == 0 else EXIT_DEVICE
+
+
+def cmd_env(args, cfg, dev: adb.Device) -> int:
+    net = cfg["network"]
+    mode = args.check_vpn or net["check_vpn"]
+    snap = netenv.collect(dev)
+    signals = netenv.derive_signals(snap, exclude_own_vpn=not args.include_own_vpn)
+    vpn = netenv.check_vpn_proxy(snap, signals)
+    eg = None
+    if args.online_ip or net["online_ip"]:
+        if not net["endpoint"]:
+            print("error: --online-ip needs network.endpoint in traceveil.toml (no default service is baked in)", file=sys.stderr)
+            return EXIT_USAGE
+        redact = net["redact_ip"] and not args.keep_ip
+        fetch = (lambda url, t: egress.phone_fetch(dev, url, t)) if args.egress_from == "phone" else None
+        eg = egress.lookup(net["endpoint"], Path(".traceveil/cache.json"), net["cache_ttl_hours"], redact,
+                           fetch=fetch, vantage=args.egress_from)
+    geo = netenv.check_geo(snap, eg["country"] if eg else None, vpn, args.egress_from)
+    policy_hit = mode == "fail" and vpn.status == "likely"
+    verdict = {"status": "fail" if policy_hit else "pass",
+               "reasons": ["VPN/proxy signal present and --check-vpn=fail"] if policy_hit else [],
+               "exitCode": EXIT_POLICY if policy_hit else EXIT_PASS}
+    rep = report.build_env_report(_device_info(dev), snap, signals, [vpn, geo], eg, verdict)
+    print(report.dumps(rep) if args.json else report.summary(rep))
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(report.dumps(rep), encoding="utf-8")
+    return verdict["exitCode"]
+
+
+def cmd_audit(args, cfg, dev: adb.Device) -> int:
+    io = audit.Io(interactive=sys.stdin.isatty() and sys.stdout.isatty(), color=sys.stderr.isatty() and not os.environ.get("NO_COLOR"))
+    plans = args.plans or None
+    return audit.run_audit(dev, cfg, io, package=args.package or "", plans=plans, auto_drive=args.auto_drive, reset=args.reset,
+                           wait_s=args.wait, resume=args.resume, as_json=args.json, out_file=args.out)
+
+
+def cmd_init(args, cfg, dev=None) -> int:
+    target = Path("traceveil.toml")
+    if target.exists() and not args.force:
+        print("traceveil.toml already exists; use --force to overwrite", file=sys.stderr)
+        return EXIT_USAGE
+    target.write_text(config.TEMPLATE, encoding="utf-8")
+    gi = Path(".gitignore")
+    existing = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    if ".traceveil/" not in existing.splitlines():
+        gi.write_text(existing + ("" if existing.endswith("\n") or not existing else "\n") + ".traceveil/\n", encoding="utf-8")
+    print("wrote traceveil.toml and ignored .traceveil/")
+    return EXIT_PASS
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        cfg = config.load(args.config)
+        if args.command == "init":
+            return cmd_init(args, cfg)
+        dev = adb.connect(args.adb or cfg["device"]["adb"] or None, args.serial or cfg["device"]["serial"] or None, args.timeout)
+        return {"doctor": cmd_doctor, "env": cmd_env, "audit": cmd_audit}[args.command](args, cfg, dev)
+    except config.ConfigError as e:
+        print(f"config error: {e}", file=sys.stderr)
+        return EXIT_USAGE
+    except adb.AdbError as e:
+        print(f"device error: {e}", file=sys.stderr)
+        return EXIT_DEVICE

traceveil/config.py

@@ -0,0 +1,94 @@
+"""traceveil.toml loading. Precedence: flags > config file > defaults."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    tomllib = None
+
+DEFAULTS = {
+    "device": {"serial": "", "adb": ""},
+    "target": {"package": "", "apk_glob": "app/build/outputs/apk/debug/*.apk"},
+    "audit": {"plans": ["silent", "reject", "accept"], "min_score": 0, "fail_on": "high"},
+    "network": {"check_vpn": "warn", "online_ip": False, "endpoint": "", "cache_ttl_hours": 24, "redact_ip": True},
+    "output": {"dir": ".traceveil/reports", "formats": ["json", "summary"]},
+}
+CHECK_VPN_MODES = ("off", "warn", "fail")
+
+TEMPLATE = """# Traceveil CLI configuration. Command-line flags override these values.
+[device]
+serial = ""   # leave empty when one phone is attached
+adb = ""      # leave empty to auto-detect (WSL: Windows adb.exe)
+
+[target]
+package = ""
+apk_glob = "app/build/outputs/apk/debug/*.apk"
+
+[audit]
+plans = ["silent", "reject", "accept"]
+min_score = 0
+fail_on = "high"
+
+[network]
+check_vpn = "warn"       # off | warn | fail
+online_ip = false        # true makes one cached lookup to `endpoint`; that service sees the public IP of the phone (or laptop with --egress-from host)
+endpoint = ""            # https URL returning JSON with a 2-letter "country"/"country_code" (and optionally "ip"), e.g. https://ipapi.co/json/
+cache_ttl_hours = 24
+redact_ip = true
+
+[output]
+dir = ".traceveil/reports"
+formats = ["json", "summary"]
+"""
+
+
+class ConfigError(Exception):
+    pass
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = {k: dict(v) if isinstance(v, dict) else v for k, v in base.items()}
+    for key, val in over.items():
+        if isinstance(val, dict) and isinstance(out.get(key), dict):
+            out[key].update(val)
+        else:
+            out[key] = val
+    return out
+
+
+def load(path: str | None = None, cwd: Path | None = None) -> dict:
+    cwd = cwd or Path.cwd()
+    candidates = [Path(path)] if path else [cwd / "traceveil.toml", cwd / "traceveil.json"]
+    for p in candidates:
+        if not p.is_file():
+            if path:
+                raise ConfigError(f"config file not found: {p}")
+            continue
+        try:
+            if p.suffix == ".toml":
+                if tomllib is None:
+                    raise ConfigError("traceveil.toml needs Python 3.11+; use traceveil.json instead")
+                data = tomllib.loads(p.read_text(encoding="utf-8"))
+            else:
+                data = json.loads(p.read_text(encoding="utf-8"))
+        except (ValueError, OSError) as e:
+            raise ConfigError(f"cannot read {p}: {e}") from e
+        cfg = _merge(DEFAULTS, data)
+        validate(cfg)
+        return cfg
+    return _merge(DEFAULTS, {})
+
+
+def validate(cfg: dict) -> None:
+    mode = cfg["network"].get("check_vpn")
+    if mode not in CHECK_VPN_MODES:
+        raise ConfigError(f"network.check_vpn must be one of {CHECK_VPN_MODES}, got {mode!r}")
+    if cfg["network"].get("online_ip") and not cfg["network"].get("endpoint"):
+        raise ConfigError("network.online_ip is true but network.endpoint is empty (no default vendor is baked in)")
+    endpoint = cfg["network"].get("endpoint")
+    if endpoint and not str(endpoint).lower().startswith("https://"):
+        raise ConfigError("network.endpoint must be an https:// URL")

traceveil/egress.py

@@ -0,0 +1,92 @@
+"""Opt-in egress-country lookup. Never runs unless the caller passes an explicit https endpoint; results are cached.
+
+Expected response: a JSON object with a 2-letter ISO country in `country`, `country_code` or `countryCode` (first
+valid one wins; full country names are ignored) and optionally the caller's address in `ip` or `query`. A body with a
+truthy `error` is a provider failure. The public IP is redacted before anything is cached or returned.
+
+Vantage matters: `phone` runs curl on the device under audit (what the audit actually sees); `host` runs on this
+machine and only describes the laptop's network.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import shlex
+import time
+import urllib.request
+from pathlib import Path
+
+COUNTRY_KEYS = ("country", "country_code", "countryCode")
+IP_KEYS = ("ip", "query")
+
+
+def redact_ip(ip: str | None) -> str | None:
+    """IPv4 -> /24, IPv6 -> /48. Returns None for anything unparsable."""
+    if not ip:
+        return None
+    try:
+        addr = ipaddress.ip_address(ip.strip())
+    except ValueError:
+        return None
+    prefix = 24 if addr.version == 4 else 48
+    return str(ipaddress.ip_network(f"{addr}/{prefix}", strict=False))
+
+
+def _load(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def host_fetch(endpoint: str, timeout: float, opener=urllib.request.urlopen) -> str:
+    with opener(endpoint, timeout=timeout) as resp:
+        return resp.read().decode("utf-8", "replace")
+
+
+def phone_fetch(device, endpoint: str, timeout: float) -> str:
+    """Runs the device's own curl. The endpoint is shell-quoted; only https URLs reach this point."""
+    return device.shell(f"curl -sS --max-time {int(timeout)} {shlex.quote(endpoint)}")
+
+
+def parse_response(body: str) -> tuple[str | None, str | None]:
+    """Returns (country, ip). Raises ValueError for malformed or error responses."""
+    data = json.loads(body)
+    if not isinstance(data, dict):
+        raise ValueError("response is not a JSON object")
+    if data.get("error"):
+        raise ValueError("provider reported an error")
+    country = next((v.strip().upper() for k in COUNTRY_KEYS
+                    if isinstance(v := data.get(k), str) and len(v.strip()) == 2 and v.strip().isalpha()), None)
+    ip = next((v for k in IP_KEYS if isinstance(v := data.get(k), str)), None)
+    return country, ip
+
+
+def lookup(endpoint: str, cache_path: Path, ttl_hours: float, redact: bool = True, now=time.time,
+           opener=urllib.request.urlopen, timeout: float = 8.0, fetch=None, vantage: str = "host") -> dict:
+    """Returns {country, network, cached, error, vantage}. `network` is the redacted IP prefix (or None)."""
+    base = {"vantage": vantage}
+    if not endpoint.lower().startswith("https://"):
+        return {**base, "country": None, "network": None, "cached": False, "error": "EndpointMustBeHttps"}
+    key = hashlib.sha256(f"{vantage}|{endpoint}".encode()).hexdigest()[:16]
+    cache = _load(cache_path)
+    hit = cache.get(key)
+    if hit and now() - hit.get("at", 0) < ttl_hours * 3600:
+        return {**base, **hit["value"], "cached": True, "error": None}
+    try:
+        body = fetch(endpoint, timeout) if fetch else host_fetch(endpoint, timeout, opener)
+        country, ip = parse_response(body)
+    except Exception as e:  # network, TLS, adb and JSON errors all mean "unknown", never a guess
+        return {**base, "country": None, "network": None, "cached": False, "error": type(e).__name__}
+    value = {"country": country, "network": redact_ip(ip) if redact else (ip if isinstance(ip, str) else None)}
+    if country is None:  # a response without a usable country is not cached as a success
+        return {**base, **value, "cached": False, "error": "NoCountryInResponse"}
+    cache[key] = {"at": now(), "value": value}
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(json.dumps(cache), encoding="utf-8")
+    except OSError:
+        pass
+    return {**base, **value, "cached": False, "error": None}

traceveil/netenv.py

@@ -0,0 +1,229 @@
+"""Network-environment signals: VPN, proxy and geography hints. Signals only, never proof.
+
+Parsing rule learned from a real iQOO dump: `dumpsys connectivity` contains hundreds of NetworkRequest lines that
+mention VPN (`NOT_VPN`, `Transports: ...|VPN`). Only NetworkAgentInfo lines under "Current Networks:" describe real
+networks, so everything else is ignored. Raw lines are never stored because they carry SSID/BSSID/MAC.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+LIMITATIONS = (
+    "IP geolocation is approximate and not proof of physical location. "
+    "VPN/proxy detection can miss split-tunnel, per-app and in-app proxies, and can false-positive on carrier or enterprise networks."
+)
+TUNNEL_PREFIXES = ("tun", "wg", "ppp", "ipsec", "tap")
+OWN_PACKAGE = "com.dpdpxray.app"
+
+
+@dataclass
+class Network:
+    network_id: str
+    kind: str
+    transports: list[str]
+    interface: str
+    owner_uid: int | None
+    proxy: str | None
+    is_default: bool
+
+
+def parse_networks(dump: str) -> list[Network]:
+    default = re.search(r"Active default network:\s*(\d+)", dump)
+    default_id = default.group(1) if default else None
+    out, inside = [], False
+    for line in dump.replace("\r", "").splitlines():
+        if line.startswith("Current Networks:"):
+            inside = True
+            continue
+        if inside and line and not line.startswith(" "):
+            break
+        if not (inside and "NetworkAgentInfo{" in line):
+            continue
+        nid = re.search(r"network\{(\d+)\}", line)
+        kind = re.search(r"ni\{(\w+)", line)
+        transports = re.search(r"Transports:\s*([A-Z_|]+)", line)
+        iface = re.search(r"InterfaceName:\s*(\S+)", line)
+        owner = re.search(r"OwnerUid:\s*(-?\d+)", line)
+        proxy = re.search(r"HttpProxy:\s*(\[[^\]]*\]\s*\d+|\S+://\S+)", line)
+        out.append(Network(
+            network_id=nid.group(1) if nid else "?",
+            kind=kind.group(1) if kind else "?",
+            transports=transports.group(1).split("|") if transports else [],
+            interface=iface.group(1) if iface else "",
+            owner_uid=int(owner.group(1)) if owner else None,
+            proxy=proxy.group(1) if proxy else None,
+            is_default=bool(nid) and nid.group(1) == default_id,
+        ))
+    return out
+
+
+@dataclass
+class Signal:
+    name: str
+    strength: str  # strong | medium | weak
+    detail: str
+
+
+@dataclass
+class Snapshot:
+    """What the device reported. A None field means unknown, which is never treated as 'absent'."""
+    networks: list[Network] | None = None
+    own_uid: int | None = None
+    global_proxy: str | None = None
+    always_on_vpn: str | None = None
+    always_on_lockdown: str | None = None
+    private_dns_mode: str | None = None
+    interfaces: list[str] | None = None
+    sim_country: str | None = None
+    network_country: str | None = None
+    timezone: str | None = None
+    locale: str | None = None
+
+
+def _country(value: str | None) -> str | None:
+    if not value:
+        return None
+    first = value.split(",")[0].strip().upper()
+    return first if len(first) == 2 and first.isalpha() else None
+
+
+def parse_interfaces(ip_addr: str) -> list[str]:
+    names = []
+    for line in ip_addr.replace("\r", "").splitlines():
+        m = re.match(r"\s*\d+:\s+([^\s:@]+)", line)
+        if m and m.group(1) not in names:
+            names.append(m.group(1))
+    return names
+
+
+def collect(device) -> Snapshot:
+    """Gather a snapshot through adb; every field degrades to None on failure."""
+    def safe(fn):
+        try:
+            return fn()
+        except Exception:
+            return None
+
+    snap = Snapshot()
+    dump = safe(lambda: device.shell("dumpsys connectivity"))
+    if dump and "Current Networks:" in dump:
+        snap.networks = parse_networks(dump)
+    uid_line = safe(lambda: device.shell(f"pm list packages -U {OWN_PACKAGE}"))
+    m = re.search(r"uid:(\d+)", uid_line or "")
+    snap.own_uid = int(m.group(1)) if m else None
+    snap.global_proxy = safe(lambda: device.setting("global", "http_proxy"))
+    snap.always_on_vpn = safe(lambda: device.setting("secure", "always_on_vpn_app"))
+    snap.always_on_lockdown = safe(lambda: device.setting("secure", "always_on_vpn_lockdown"))
+    snap.private_dns_mode = safe(lambda: device.setting("global", "private_dns_mode"))
+    ip = safe(lambda: device.shell("ip -o addr"))
+    snap.interfaces = parse_interfaces(ip) if ip else None
+    snap.sim_country = _country(safe(lambda: device.getprop("gsm.sim.operator.iso-country")))
+    snap.network_country = _country(safe(lambda: device.getprop("gsm.operator.iso-country")))
+    snap.timezone = safe(lambda: device.getprop("persist.sys.timezone")) or None
+    snap.locale = safe(lambda: device.getprop("persist.sys.locale")) or None
+    return snap
+
+
+def derive_signals(snap: Snapshot, exclude_own_vpn: bool = True) -> list[Signal]:
+    signals: list[Signal] = []
+    for net in snap.networks or []:
+        is_vpn = "VPN" in net.transports or net.kind == "VPN"
+        own = exclude_own_vpn and snap.own_uid is not None and net.owner_uid == snap.own_uid
+        if is_vpn and not own:
+            signals.append(Signal("vpn_transport", "strong", f"network {net.network_id} has VPN transport"
+                                  + (" (active default)" if net.is_default else "")))
+        if net.proxy:
+            signals.append(Signal("link_proxy", "strong", f"network {net.network_id} carries an HTTP proxy"))
+    if snap.global_proxy:
+        signals.append(Signal("global_proxy", "strong", "global HTTP proxy is configured"))
+    if snap.always_on_vpn:
+        signals.append(Signal("always_on_vpn", "strong", "an always-on VPN app is configured"))
+    tunnels = [i for i in snap.interfaces or [] if i.startswith(TUNNEL_PREFIXES)]
+    if tunnels and not _tunnels_explained_by_own_vpn(snap, tunnels):
+        signals.append(Signal("tunnel_interface", "medium", f"tunnel-like interface present: {', '.join(tunnels)}"))
+    if snap.private_dns_mode != "off":
+        mode = snap.private_dns_mode or "unset (Automatic)"
+        signals.append(Signal("private_dns", "weak", f"Private DNS mode is {mode}: encrypted DNS can limit capture (not a VPN)"))
+    return signals
+
+
+def _tunnels_explained_by_own_vpn(snap: Snapshot, tunnels: list[str]) -> bool:
+    """Our own capture VPN shows up as tun0. If an own-uid VPN network exists and is the only VPN, don't flag it."""
+    nets = snap.networks or []
+    own_vpn = [n for n in nets if ("VPN" in n.transports) and n.owner_uid == snap.own_uid and snap.own_uid is not None]
+    other_vpn = [n for n in nets if ("VPN" in n.transports) and n not in own_vpn]
+    return bool(own_vpn) and not other_vpn and len(tunnels) <= len(own_vpn)
+
+
+# Minimal timezone->country map for the zones that matter in practice; unknown zones stay unknown.
+TZ_COUNTRY = {"Asia/Kolkata": "IN", "Asia/Calcutta": "IN", "America/New_York": "US", "America/Chicago": "US",
+              "America/Denver": "US", "America/Los_Angeles": "US", "Europe/London": "GB", "Europe/Berlin": "DE",
+              "Europe/Paris": "FR", "Asia/Singapore": "SG", "Asia/Dubai": "AE", "Asia/Tokyo": "JP",
+              "Australia/Sydney": "AU", "Asia/Dhaka": "BD", "Asia/Karachi": "PK", "Asia/Colombo": "LK",
+              "Asia/Kathmandu": "NP"}
+
+
+@dataclass
+class Check:
+    id: str
+    status: str       # none | possible | likely | unknown
+    confidence: str   # low | medium | high
+    signals: list[str] = field(default_factory=list)
+    reasons: list[str] = field(default_factory=list)
+
+
+def check_vpn_proxy(snap: Snapshot, signals: list[Signal]) -> Check:
+    relevant = [s for s in signals if s.name != "private_dns"]
+    strong = [s for s in relevant if s.strength == "strong"]
+    if strong:
+        return Check("vpn_proxy", "likely", "high" if len(strong) > 1 or snap.networks else "medium",
+                     [s.detail for s in relevant], ["a strong signal was reported by Android itself"])
+    if relevant:
+        return Check("vpn_proxy", "possible", "low", [s.detail for s in relevant], ["only indirect signals"])
+    if snap.networks is None and snap.interfaces is None:
+        return Check("vpn_proxy", "unknown", "low", [], ["connectivity data could not be read"])
+    return Check("vpn_proxy", "none", "medium" if snap.networks is not None else "low", [],
+                 ["no VPN/proxy signal seen; this does not rule out split-tunnel or in-app proxies"])
+
+
+def device_countries(snap: Snapshot) -> dict[str, str]:
+    out = {}
+    if snap.sim_country:
+        out["sim"] = snap.sim_country
+    if snap.network_country:
+        out["network"] = snap.network_country
+    tz = TZ_COUNTRY.get(snap.timezone or "")
+    if tz:
+        out["timezone"] = tz
+    return out
+
+
+def check_geo(snap: Snapshot, egress_country: str | None, vpn: Check, vantage: str = "phone") -> Check:
+    check = _check_geo(snap, egress_country, vpn)
+    if vantage == "host" and check.status in ("none", "possible", "likely"):
+        # The laptop's egress says nothing certain about the phone (it may be on cellular or a VPN).
+        check.status = "possible" if check.status != "none" else "none"
+        check.confidence = "low"
+        check.reasons.append("egress was measured from the host machine, not the phone")
+    return check
+
+
+def _check_geo(snap: Snapshot, egress_country: str | None, vpn: Check) -> Check:
+    ctx = device_countries(snap)
+    if egress_country is None:
+        return Check("geo_mismatch", "unknown", "low", [],
+                     ["no egress country (offline by default; use --online-ip to enable one lookup)"])
+    if not ctx:
+        return Check("geo_mismatch", "unknown", "low", [], ["no SIM/network/timezone country available to compare"])
+    egress = egress_country.upper()
+    disagree = {k: v for k, v in ctx.items() if v != egress}
+    if not disagree:
+        return Check("geo_mismatch", "none", "medium", [f"egress {egress} agrees with {', '.join(ctx)}"], [])
+    sigs = [f"egress {egress} differs from {k} {v}" for k, v in disagree.items()]
+    if len(disagree) == len(ctx) and len(ctx) >= 2 and vpn.status == "likely":
+        return Check("geo_mismatch", "likely", "medium", sigs, ["VPN signal plus multiple device-context countries disagree with egress"])
+    conf = "medium" if vpn.status in ("likely", "possible") else "low"
+    return Check("geo_mismatch", "possible", conf, sigs,
+                 ["travel, roaming, corporate networks and CDNs can also explain this"])

traceveil/report.py

@@ -0,0 +1,61 @@
+"""JSON envelope and terminal summary for the network-environment check."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict
+
+from . import __version__
+from .netenv import LIMITATIONS, Check, Signal, Snapshot, device_countries
+
+SCHEMA_VERSION = 1
+
+
+def serial_hash(serial: str) -> str:
+    return hashlib.sha256(serial.encode()).hexdigest()[:12]
+
+
+def build_env_report(device_info: dict, snap: Snapshot, signals: list[Signal], checks: list[Check],
+                     egress: dict | None, verdict: dict) -> dict:
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "tool": {"name": "traceveil", "version": __version__},
+        "device": device_info,
+        "networkEnvironment": {
+            "checks": [asdict(c) for c in checks],
+            "signals": [asdict(s) for s in signals],
+            "deviceCountries": device_countries(snap),
+            "egress": egress,
+            "privateDnsMode": snap.private_dns_mode,
+            "limitations": LIMITATIONS,
+        },
+        "verdict": verdict,
+    }
+
+
+def dumps(report: dict) -> str:
+    return json.dumps(report, indent=2, sort_keys=False)
+
+
+def summary(report: dict) -> str:
+    env = report["networkEnvironment"]
+    dev = report["device"]
+    lines = [f"Traceveil network environment  ({dev.get('model', '?')}, Android {dev.get('androidVersion', '?')})"]
+    for c in env["checks"]:
+        lines.append(f"  {c['id']:<13} {c['status']:<9} confidence {c['confidence']}")
+        for s in c["signals"]:
+            lines.append(f"      - {s}")
+        for r in c["reasons"]:
+            lines.append(f"      · {r}")
+    if env["deviceCountries"]:
+        lines.append("  device context: " + ", ".join(f"{k}={v}" for k, v in env["deviceCountries"].items()))
+    eg = env["egress"]
+    if eg:
+        lines.append(f"  egress ({eg.get('vantage', '?')}): {eg.get('country') or 'unknown'}"
+                     + (f" ({eg['network']})" if eg.get("network") else "")
+                     + (f" [lookup failed: {eg['error']}]" if eg.get("error") else ""))
+    v = report["verdict"]
+    lines.append(f"  verdict: {v['status']}" + (f" - {'; '.join(v['reasons'])}" if v["reasons"] else ""))
+    lines.append(f"  note: {env['limitations']}")
+    return "\n".join(lines)

traceveil/shizuku.py

@@ -0,0 +1,42 @@
+"""Shizuku server detection and adb start. The manager app process is NOT the server: the server runs as
+`shell` (or root) with the process name `shizuku_server`, which is what we look for."""
+
+from __future__ import annotations
+
+import re
+import time
+
+PACKAGE = "moe.shizuku.privileged.api"
+SERVER_NAME = "shizuku_server"
+ABI_DIR = {"arm64-v8a": "arm64", "armeabi-v7a": "arm", "armeabi": "arm", "x86_64": "x86_64", "x86": "x86"}
+
+
+def is_running(device) -> bool:
+    out = device.shell("ps -A -o USER,NAME")
+    return any(len(p) >= 2 and p[0] in ("shell", "root") and p[-1] == SERVER_NAME
+               for p in (line.split() for line in out.splitlines()))
+
+
+def starter_path(device) -> str | None:
+    """Path of Shizuku's own starter binary inside its install dir, or None if Shizuku isn't installed."""
+    m = re.search(r"package:(/\S+)/base\.apk", device.shell(f"pm path {PACKAGE}"))
+    if not m:
+        return None
+    abi = ABI_DIR.get(device.getprop("ro.product.cpu.abi"), "arm64")
+    return f"{m.group(1)}/lib/{abi}/libshizuku.so"
+
+
+def start(device, wait: float = 6.0, sleep=time.sleep) -> tuple[bool, str]:
+    """Starts the server over adb if needed. Returns (running, message). Never raises for 'not installed'."""
+    if is_running(device):
+        return True, "already running"
+    path = starter_path(device)
+    if path is None:
+        return False, f"{PACKAGE} is not installed"
+    device.shell(path)
+    deadline = max(1, int(wait / 0.5))
+    for _ in range(deadline):
+        sleep(0.5)
+        if is_running(device):
+            return True, "started over adb"
+    return False, f"ran {path} but no {SERVER_NAME} process appeared; open Shizuku and use its adb start, or check USB debugging (Security settings)"

traceveil-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: traceveil
+Version: 0.1.0
+Summary: Developer CLI that runs Traceveil privacy/consent audits on an Android phone over adb and saves JSON reports.
+Author: Traceveil contributors
+License: MIT
+Project-URL: Repository, https://github.com/agrimsri/IQOO-Kernel-Panic
+Keywords: android,adb,privacy,consent,dpdp,audit
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Traceveil CLI
+
+Run a Traceveil privacy audit on your Android phone from your laptop, and get a JSON report back. Everything goes over USB (adb); nothing is uploaded.
+
+```
+laptop                                   phone (debug build of Traceveil)
+  traceveil audit  --adb broadcast-->    DebugAuditReceiver -> runs the normal audit
+        ^                                          |
+        |  adb shell cat                           v
+        +-------- report.json  <--- /sdcard/Android/data/com.dpdpxray.app/files/reports/<id>/
+  saves .traceveil/reports/<id>.json
+```
+
+The trigger exists **only in debug builds**. Release builds have no way to start an audit from adb.
+
+## 1. One-time setup
+
+You need: Python 3.11+, JDK 17, Android platform-tools (adb), a phone with USB debugging on.
+
+Install the CLI (from PyPI once published, or from a checkout):
+
+```bash
+pipx install traceveil          # or: pip install traceveil
+pip install -e .                # from a checkout; `python3 -m traceveil` also works
+```
+
+The examples below use `python3 -m traceveil`; the installed `traceveil` command is identical.
+
+```bash
+# 1. Build and install the debug app (run from the repo root)
+bash ./gradlew :app:assembleDebug :leakyshop:assembleLeakyDebug
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+adb install -r leakyshop/build/outputs/apk/leaky/debug/leakyshop-leaky-debug.apk   # demo app to audit
+
+# 2. Check the phone is ready
+python3 -m traceveil doctor
+```
+
+Under **WSL2** the Linux `adb` cannot see USB phones. Use the Windows one for every command:
+`--adb /mnt/c/Users/<you>/AppData/Local/Android/Sdk/platform-tools/adb.exe` (or `export ADB=...`).
+Install the APK with that adb too, from a Windows path.
+
+On the phone, once:
+1. **Open Traceveil** and allow the **VPN** permission (Android only delivers the trigger to an app that has been opened).
+2. Turn on the **Traceveil accessibility service** (Settings > Accessibility).
+3. Set **Private DNS = Off** (otherwise lookups are hidden from the audit).
+
+## 2. Run an audit
+
+```bash
+python3 -m traceveil audit --package com.leakyshop.demo
+```
+
+With several phones attached add `--serial <serial>` (`adb devices` lists them).
+
+What happens, step by step:
+
+1. The CLI checks Traceveil is installed and sends the trigger. You see `audit started: cli-<time>-<id>`.
+2. The phone runs the audit (about 1 to 3 minutes for three plans). By default **you tap Accept / Reject on the phone** when asked. Add `--auto-drive` to let Traceveil tap.
+3. The CLI waits (default 15 min, change with `--wait <seconds>`), then reads `report.json` from the phone and checks it is valid.
+4. It saves the report to `.traceveil/reports/<request_id>.json` and prints a summary:
+
+```
+Traceveil audit  LeakyShop (com.leakyshop.demo)  score 21 / AT_RISK  findings 5
+  C1   HIGH     Trackers contacted before consent
+  ...
+  policy: 3 finding(s) at or above high
+  report saved: .traceveil/reports/cli-20261010T071219Z-0f9239c5.json
+```
+
+Useful options:
+
+| Option | What it does |
+|---|---|
+| `--plans silent,reject,accept` | Pick plans (default all three; one plan is quick but often gives an inconclusive score) |
+| `--json` | Print the full JSON instead of the summary |
+| `--out report.json` | Also write the JSON to a file you choose |
+| `--auto-drive` | Traceveil taps Accept/Reject itself |
+| `--reset` | Clear the app's data first. **Only for your own test apps**; needs Shizuku |
+| `--resume <request_id>` | Fetch the result of an earlier run (after a timeout or unplug) |
+
+Settings you use often can live in `traceveil.toml` (`python3 -m traceveil init` creates it): `target.package`, `audit.fail_on`, `audit.min_score`, `output.dir`.
+
+## 3. The report
+
+```json
+{
+  "schemaVersion": 1,
+  "requestId": "cli-20261010T071219Z-0f9239c5",
+  "auditId": "audit-1791616339835",
+  "target": { "package": "com.leakyshop.demo", "label": "LeakyShop" },
+  "device": { "model": "vivo I2501", "androidVersion": "16" },
+  "score": 21,
+  "band": "AT_RISK",
+  "findingCount": 5,
+  "findings": [
+    { "check": "C1", "severity": "HIGH", "title": "Trackers contacted before consent", "confidence": 1.0 }
+  ],
+  "sessions": [ { "plan": "REJECT", "netEvents": 12, "consentChoice": "REJECT", "notes": [] } ]
+}
+```
+
+`score` is `null` (never 0) when the result is inconclusive. The report is a technical assessment, not legal advice.
+
+## 4. Exit codes (for scripts and CI)
+
+| Code | Meaning |
+|---|---|
+| 0 | Finished, policy passed |
+| 1 | Policy failed (score below `min_score`, or a finding at/above `fail_on`) |
+| 2 | Inconclusive, app-reported failure, or missing/malformed report |
+| 3 | Device or trigger problem (no phone, app missing, VPN/accessibility off, another audit running) |
+| 4 | Bad arguments |
+| 6 | Timed out (the audit keeps running; use `--resume`) |
+
+## 5. If something goes wrong
+
+- **Phone unplugged mid-audit**: the CLI prints a yellow message. Reconnect, unlock the phone, press Enter to retry (or `q` to quit). The audit keeps running on the phone; `--resume <request_id>` picks it up later.
+- **"no debug trigger answered"**: install the *debug* APK and open Traceveil once. A force-stopped app does not receive the trigger.
+- **"VPN permission not granted" / "accessibility service is off"**: do steps 1 and 2 of the phone setup.
+- **Timeout**: raise `--wait`, or run again with `--resume <id>`.
+- **Device "unauthorized"**: unlock the phone and tap Allow on the USB debugging prompt.
+
+Safety: audit only your own test apps (like the LeakyShop demos). The CLI never force-stops anything and never uploads data.
+
+## 6. Tests
+
+```bash
+pip install -e . && python3 -m unittest tools.tests.test_traceveil_audit tools.tests.test_traceveil_cli   # CLI, no phone needed
+bash ./gradlew :core:test :app:testDebugUnitTest                                       # Android side
+```
+
+More detail (design, limits, device evidence): `docs/CLI_AUDIT.md`.

traceveil-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+traceveil/__init__.py,sha256=8tYaJ8lYY0iaXJVOGrgpIfmS2nSeifFy6Hu9UkA-bY8,310
+traceveil/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+traceveil/adb.py,sha256=xfDBwjE10GsRRKxonQKYc08BVctWaC6NrV_ivL1g0Ig,6152
+traceveil/audit.py,sha256=H57DsEt2-PmC11liLduawyGKlryL_hKKfJzz-Vc7ryg,9680
+traceveil/cli.py,sha256=fZxnZfiJcGJyMnYCpDa1ORjb8CqpFWe6JYQ2n7j31WA,8450
+traceveil/config.py,sha256=R47Doi84LDwciBm2UOuW_bqpv2MIxd6c6drs6mVLAq8,3380
+traceveil/egress.py,sha256=V9v8BzbeGEHZ4O81UHzi3zqtzvECEilXEleA_RWQkXg,4135
+traceveil/netenv.py,sha256=5b6NoScfjiwvFLMD-stzze2Bjd_Rro7zNOgnbEFNg1M,10498
+traceveil/report.py,sha256=5ExCKKrsGvr7e8WY7Ziy65GpFKlfXkXxL2fZ8LUG91Y,2279
+traceveil/shizuku.py,sha256=BZ_99ln1XQ_RqKbHr_Ed3IiNKMHyd2ngjyT2wYJZLO8,1741
+traceveil-0.1.0.dist-info/licenses/LICENSE,sha256=SdN9vt9m2LFCGvu6EYCKAKmu4sYkbdp1kkqHVSxiaBo,1082
+traceveil-0.1.0.dist-info/METADATA,sha256=v4CCJADHmSUeYWTG4tx60T7DUsSGVx0lIzKje34GcKg,6790
+traceveil-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+traceveil-0.1.0.dist-info/entry_points.txt,sha256=q41iIPTV5MIFhsPf173xeKw8uJEOBdJQAj3InDNXQ5I,49
+traceveil-0.1.0.dist-info/top_level.txt,sha256=8VfIrQXukOZOLgcMB1RG9CGajpLEjNpDQ82hLaLUBEY,10
+traceveil-0.1.0.dist-info/RECORD,,

traceveil-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

traceveil-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+traceveil = traceveil.cli:main

traceveil-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nitya-prakash-pandey-2005
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

traceveil-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+traceveil