feat(diagnostics): add local incident capture and support bundle for TUN/DNS failures

[kovawx]

2026-09-03 合并与验收同步

本批修复提供了新的采集需求证据，尚未交付完整 incident capture。 Core #106（6d0553d）与 客户端 #40（dff6b73）已合并；本次事故定位同时依赖应用/内核日志、DHCP/NCSI/网络配置文件、WFP 过滤器与 drop 归属、第三方 VPN 时间线。

建议在本 issue 的本地、有限、脱敏 support bundle 中增加按能力声明的 OS 网络快照/事件：物理接口与地址、DHCP/Internet 检测结果、路由及 WFP 所有者、采集时间和 runtime generation。不可用的历史包或事件应明确标缺失，不能把时间相关性替代 packet/filter 归因。

本次未实现统一 incident_id、实际 DNS→路由→出口→连接关联链、开始/停止控制、大小/时间上限及完整脱敏测试。因此全部原验收项保持未完成，与 zerodenet/znet-sink#31 继续协同。

---

Problem

TUN/DNS incidents are currently hard to diagnose on the affected node. Zero exposes useful but separate diagnostics (dns_lookup, dns_cache, fakeip_lookup, trace_route, flow records, and TUN status), yet there is no bounded incident-capture workflow that correlates the actual packet/session path.

A representative failure is exmail.qq.com: it works without TUN, while enabling TUN makes it unreachable even though the configured MetaCubeX CN domain and CN IP rule sets should both select direct. After the incident, static route tracing and ordinary logs cannot determine whether the actual TUN session failed during DNS dispatch, Fake-IP reversal, hostname recovery, rule matching, target resolution, physical-egress selection, socket binding, or connect.

Related investigations: #30, #33, and PR #46.

Scope and boundary

This is a local, on-node maintenance capability:

• no remote command execution;
• no telemetry, background upload, or hosted service;
• no Connector responsibility and no second management API;
• collection is explicitly started/stopped by the local operator through the existing CLI/control-plane boundary;
• output remains on local disk until the user chooses to share it.

Proposed capability

1. Bounded incident capture

Add a local workflow such as:

zero diagnostics capture --target exmail.qq.com:443 --protocol tcp --duration 90s --output <path>

The exact CLI/API names are open to design, but the workflow should be:

1. start a bounded capture and receive an incident_id;
2. reproduce the failure locally;
3. stop automatically or explicitly;
4. write one versioned, support-ready bundle.

Capture must use bounded ring buffers and target/time filters so normal production traffic is not dumped indiscriminately.

2. Correlated authoritative timeline

Every relevant observation should carry the same incident_id and, where available, flow/session and operation IDs. The exported timeline should connect:

• intercepted DNS query and query role;
• selected DNS server/outbound, attempted endpoints, result, and failure reason;
• Fake-IP allocation and forward/reverse lookup result;
• TUN session original destination, recovered host, host_source, and fake_ip_reverse_status;
• the actual route decision, matched rule/rule-set identity, action, and resolved outbound target;
• real-resolution candidates and candidate selection;
• selected physical interface/local address, route lookup, binding reason, and egress generation;
• connect stage, OS error/category, retry/fallback, and terminal flow outcome.

This must record the live session path. It should not rely solely on the current synthetic diagnostics.trace_route, which starts from caller-provided target data and cannot reproduce TUN hostname/Fake-IP recovery.

3. Support bundle contents

Include a versioned manifest plus sanitized snapshots of:

• Zero version, git hash/build features, OS/architecture;
• core_instance_id, committed config_revision, capture time range, and clock information;
• TUN state, strict/auto-route state, DNS hijack state, selected IPv4/IPv6 physical egress, and route reconciliation health;
• DNS/Fake-IP counters and target-scoped cache/mapping observations;
• target-scoped active/recent flow records and the correlated incident timeline;
• rule-set tags, formats, entry counts/digests and load errors, without embedding full proprietary lists;
• recent structured core logs restricted to the capture window.

A sanitized configuration topology may include tags, types, references, and rule order, but never credentials or complete proxy/subscription URLs.

4. Privacy and safety

• Secret fields, auth material, UUIDs, keys, subscription URLs, headers, and proxy URLs are excluded by construction.
• Hostnames/IPs should have an explicit local privacy mode: preserve target-scoped values for debugging, or consistently pseudonymize unrelated endpoints.
• Export schema is additive/versioned and declares omissions/redactions.
• Capture has duration/record/byte limits and cannot remain enabled accidentally.
• No packet payload or TLS/application content is collected by default.

5. Local read-only probes

Optionally attach target-scoped read-only probes at capture completion, using the same runtime generation:

• DNS lookup plus recent backend attempts;
• Fake-IP forward/reverse lookup when applicable;
• route explanation for the observed domain and observed IP;
• direct/outbound connect probe that reports the same network-observation fields as a real dial.

Probe results must be labeled separately from actual traffic observations.

Acceptance criteria

• One local command/control operation starts and stops a bounded capture and produces a versioned bundle.
• A failed TUN HTTPS connection can be classified as DNS failure, Fake-IP reverse miss, hostname recovery loss, rule miss, target-resolution failure, physical-egress selection/binding failure, or TCP connect failure without enabling an ad-hoc debug build.
• The bundle contains the actual route decision and direct-dial network observations for the failed flow.
• Flow/session/operation observations are correlated across DNS, route, and connect stages.
• Capture and export are safe under concurrent traffic and have deterministic size/time bounds.
• Automated tests prove credentials, keys, UUIDs, headers, and proxy/subscription URLs cannot enter the bundle.
• Older readers can ignore additive fields; the manifest reports schema and capability versions.
• The feature works without a GUI; clients may wrap the same local capability.

Non-goals

• Remote node orchestration or remote shell/control.
• Automatic issue creation or upload.
• Full packet capture.
• Reimplementing routing/DNS decisions in the client.
• Replacing the existing focused diagnostics APIs.

[kovawx]

Client-side local capture, preview, redaction, and export workflow is tracked in zerodenet/znet-sink#31.