Magicnet Device Debugging

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.