magicnet-device-debugging

name	magicnet-device-debugging
description	Debug and verify MagicNet on a real Android root device. Use when working on MagicNet MCP usage, adb/root validation, TUN/eBPF transparent status, DNS leak diagnosis, sing-box behavior, certificate-less packet capture, eCapture/tcpdump checks, support bundles, device logs, or module runtime issues under /data/adb/modules/MagicNet.

MagicNet Device Debugging

Use the connected Android device as the source of truth. MagicNet is a root module; local config checks cannot prove vendor networking, KernelSU/Magisk behavior, TUN state, DNS routing, or real packet capture.

Execution Environment

This skill may run in either of two environments:

• Android Termux (the current device): commands execute on the Android device itself. Do not use adb; inspect /data/adb/modules/MagicNet directly and use su -M -c '...' for root-only operations.
• Computer/host shell: commands execute on a separate computer. Use adb shell/adb pull only when a connected device is actually needed, and first select the reported device serial.

Determine the environment before collecting evidence: uname -a, getprop ro.build.version.sdk 2>/dev/null, and command -v adb. The presence of adb alone does not mean the shell is a host; Android Termux may have adb installed while still being the device shell. Prefer direct local access when /data/adb/modules/MagicNet exists.

Ground Rules

• Never print or commit secrets from .env, subscriptions, MCP secrets, device tokens, or raw logs containing private traffic.
• Read .env only when a task needs local private defaults; do not copy its values into docs, patches, issues, commits, or replies.
• Use /sdcard/Download/MagicNet/ for device-side temporary transfer files. Do not use /data/local/tmp.
• Use su -M -c on KernelSU devices unless the current device proves another root invocation is required.
• Keep packet capture diagnostic-only. Do not restore the removed proxy MITM/TProxy capture path, cli capture, capture config files, or lib/magicnet/capture_*.
• Do not reintroduce Android CA injection. system/etc/security/cacerts, cli cert, and generated MagicNet local CA support were removed; use tcpdump or eCapture for no-certificate diagnostics.
• Do not add module-level post-fs-data.sh or placeholder uninstall.sh just for compatibility. MagicNet uses service.sh and boot-completed.sh; uninstall hooks belong in kamfw only when real cleanup exists.
• Current MagicNet mainline explicitly supports sing-box tun|ebpf, with tun as the default. Do not add auto or restore TProxy, Redirect, or netd ALLOW_MULTI; use cli transparent status and cli health, not cli ebpf status.

Baseline Snapshot

Start with read-only evidence:

adb devices -l
adb shell 'getprop ro.product.model; getprop ro.build.version.release; getprop ro.build.version.sdk'
adb shell 'su -M -c "id"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli service status"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli health"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli transparent status"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli ecapture status || true"'

For network work, capture routes and listeners before changing anything:

adb shell 'su -M -c "ip addr; ip route; ip rule"'
adb shell 'su -M -c "ss -lntup 2>/dev/null | grep -E \"sing-box|magicnet|789|909|876\" || true"'

MCP Usage

MagicNet exposes a Streamable HTTP MCP server from the device module. Enable it explicitly, read the actual bind/port from cli mcp status, forward that port to localhost, then call it with the device-generated secret.

adb shell 'su -M -c "/data/adb/modules/MagicNet/cli mcp enable 127.0.0.1 8766"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli mcp status"'
adb forward tcp:8766 tcp:8766

If cli mcp status reports a different port, use that port in adb forward and in any local .mcp.json endpoint. Do not assume stale docs or client config are correct.

Read the secret into a local shell variable without echoing it:

MCP_SECRET="$(adb shell 'su -M -c "/data/adb/modules/MagicNet/cli mcp secret"' | tr -d '\r')"
curl -fsS -X POST http://127.0.0.1:8766/mcp \
  -H "Authorization: Bearer ${MCP_SECRET}" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
unset MCP_SECRET

If the local MCP client reads .mcp.json, verify it points at http://127.0.0.1:8766/mcp unless cli mcp status reports a different port. If calls fail, inspect /data/adb/modules/MagicNet/.log/mcp-server.log with redaction.

Transparent Dataplane Status

Use cli transparent status and cli health as the first-line status view. Never infer effective mode from magicnet0 alone and never treat the capability probe as attachment proof.

adb shell 'su -M -c "/data/adb/modules/MagicNet/cli transparent status"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli health"'
adb shell 'su -M -c "ip -o link show magicnet0 2>/dev/null || true"'
adb shell 'su -M -c "test -f /sys/fs/cgroup/cgroup.controllers && cat /sys/fs/cgroup/cgroup.controllers || true"'
adb shell 'su -M -c "ip rule; ip route; tc qdisc show 2>/dev/null || true"'

Interpret status conservatively:

• Configured/effective tun, a healthy Dataplane check, and a present magicnet0 are the expected TUN state.
• Configured ebpf must not require magicnet0. Verify local cgroup backend state; for hybrid, verify that every reported shared interface is an actual current downstream interface and that TC attachment is reported. shared=pending is valid when no confirmed downstream interface exists.
• Capability/probe success means the kernel can load the requested programs; it does not prove the current sing-box process owns active cgroup/TC attachments. Preserve that distinction in reports.
• A mode mismatch, rollback/pending state, missing expected attachment, or health warning can be a startup, routing, kernel, or vendor-network issue; collect surrounding health, process, cgroup, TC, and route evidence before changing anything.
• cli ebpf status remains intentionally unavailable. Do not report its absence as a device fault or add an eBPF/netd fallback path. The internal sing-box tools ebpf status command is a non-destructive capability probe only.

AI Website Routing Acceptance

Do not accept an AI routing fix from config inspection alone. On the installed device, verify all four public websites through MagicNet's local HTTP proxy at 127.0.0.1:7892:

adb shell 'su -M -c '\''for url in https://chatgpt.com/ https://gemini.google.com/ https://grok.com/ https://claude.ai/; do curl -sS -o /dev/null -w "%{http_code} $url\n" --max-time 30 -x http://127.0.0.1:7892 "$url"; done'\'''

• Require an HTTP response from every site. A redirect, authentication response, or application response proves reachability; timeout, DNS failure, TLS failure, or proxy failure does not.
• For each request, collect sing-box logs proving traffic selected its dedicated outbound: ai-chatgpt, ai-gemini, ai-grok, or ai-claude. Reject any missing outbound, outbound not found, or equivalent error.
• Follow command-line probes with a real browser visit when the user's acceptance criterion is website usability. Confirm the page loads through MagicNet rather than only proving TCP/TLS reachability.
• If testing temporarily changes a selector through the Clash API or WebUI, record its original selection and restore it before finishing.
• Redact subscription URLs, node credentials, tokens, cookies, authorization headers, and private browsing data from commands, logs, screenshots, and reports.

Certificate-Less Packet Capture

Use these methods when the user wants packet evidence without installing a CA certificate.

Metadata Capture With tcpdump

tcpdump needs no certificate and can prove whether traffic leaves a given interface, port, or DNS path. It does not decrypt HTTPS payloads.

adb shell 'su -M -c "timeout 15 tcpdump -i any -nn -c 40 '\''tcp port 443 or udp port 53 or tcp port 53 or tcp port 853 or udp port 853'\''"'

Trigger traffic in parallel from another shell:

adb shell 'am start -a android.intent.action.VIEW -d "https://www.cloudflare.com/cdn-cgi/trace?magicnet_probe=1"'

For DNS leak checks, capture on the physical egress interface when known, such as wlan0 or rmnet_data0, and verify no plain DNS/DoT leaves unexpectedly:

adb shell 'su -M -c "timeout 12 tcpdump -ni wlan0 '\''port 53 or port 853'\''"'

If the interface is unclear, list candidates:

adb shell 'su -M -c "ip -o link show | cut -d: -f2 | tr -d \" \""'

eCapture Packet Or TLS Diagnostics

Use the bundled eCapture wrapper when cli ecapture status says the binary is installed and executable. Treat a successful process exit as "probe started"; verify capture success by checking the output file is non-empty.

adb shell 'su -M -c "/data/adb/modules/MagicNet/cli ecapture status"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli ecapture pcap 15 wlan0 tcp port 443"'
adb shell 'su -M -c "/data/adb/modules/MagicNet/cli ecapture tls 15 all all"'

Expected outputs are under /data/adb/modules/MagicNet/.log/, such as ecapture.pcapng, ecapture-pcap.log, ecapture-tls.log, and ecapture-tls-events.log. Confirm file content:

adb shell 'su -M -c "ls -lh /data/adb/modules/MagicNet/.log/ecapture.pcapng; wc -c /data/adb/modules/MagicNet/.log/ecapture.pcapng"'

Boundaries:

• cli ecapture pcap can write packet captures, not decrypted application payloads. If the file is 0 bytes, report pcap output as not validated even if probes started.
• cli ecapture tls can expose TLS plaintext events without installing a CA, but only when the kernel, eBPF probes, architecture, and target TLS library are compatible.
• Browser/app HTTPS plaintext is not guaranteed. If TLS mode is silent, fall back to packet metadata and routing/DNS evidence.

Legacy Cleanup Checks

When auditing stale MagicNet files, treat these paths as removed mainline features:

find /data/adb/modules/MagicNet -maxdepth 4 \( \
  -path '*/system/etc/security/cacerts*' \
  -o -name 'post-fs-data.sh' \
  -o -name 'sepolice.rule' \
  -o -name 'capture_common.sh' \
  -o -name 'capture_singbox.sh' \
  -o -name 'capture.conf' \
\) -print

Expected result for a current install is no output. If old files appear on a device, they are migration residue; do not build new behavior around them.

For kamfw uninstall behavior, check the framework, not MagicNet module root:

adb shell 'su -M -c "test -f /data/adb/modules/MagicNet/uninstall.sh && sed -n '\''1,120p'\'' /data/adb/modules/MagicNet/uninstall.sh || true"'

An uninstall script is only meaningful if it contains real rollback commands or calls kamfw run uninstall -- "$@".

To pull a capture for local inspection, copy through the approved transfer directory and clean it after use:

adb shell 'mkdir -p /sdcard/Download/MagicNet'
adb shell 'su -M -c "cp /data/adb/modules/MagicNet/.log/ecapture.pcapng /sdcard/Download/MagicNet/ecapture.pcapng"'
adb pull /sdcard/Download/MagicNet/ecapture.pcapng .
adb shell 'rm -f /sdcard/Download/MagicNet/ecapture.pcapng'

Reporting

Report only concise evidence:

• Device model, Android version, and root availability.
• MagicNet service, health, configured/effective transparent dataplane, MCP, and capture status.
• Whether tcpdump or eCapture captured packets.
• Whether HTTPS plaintext was expected, observed, or unavailable.
• Any DNS leak evidence by interface and port, without exposing private domains beyond what the user asked to test.