net

Net Debug Skill

Embedded network communication debugging tool, uniformly encapsulating interface discovery, packet capture, offline analysis, connectivity testing, port scanning, and traffic statistics capabilities.

Script and configuration paths

• Script directory: <skill-dir>/scripts/
• Environment-level configuration: <skill-dir>/config.json(tool paths only)
• Project-level configuration: <workspace>/.embeddedskills/config.json(network parameters)
• Protocol reference: <skill-dir>/references/common_protocols.json

Dependencies

• tshark (installed with Wireshark, must be added to PATH)
• dumpcap (installed with Wireshark)
• Optional: capinfos
• Built into Windows: ipconfig、ping、tracert、netstat、arp、nslookup
• Python 3.x (standard library only)
• Packet capture requires the Npcap driver; some environments require administrator privileges

Configuration

Environment-level configuration (skill/config.json)

Only environment-level configuration related to tool paths is retained:

{
  "tshark_exe": "tshark",
  "capinfos_exe": "capinfos"
}

Project-level configuration (.embeddedskills/config.json)

Under the workspace, .embeddedskills/config.json stores project-level network configuration:

{
  "net": {
    "interface": "",
    "target": "",
    "capture_filter": "",
    "display_filter": "",
    "duration": 30,
    "timeout_ms": 1000,
    "scan_ports": "",
    "capture_format": "pcapng",
    "log_dir": ".embeddedskills/logs/net"
  }
}

Parameter resolution priority

1. CLI parameters (--interface, --target , etc.) - highest priority
2. Project-level configuration (.embeddedskills/config.json in net section)
3. State file (.embeddedskills/state.json history in )
4. Default values - lowest priority

Connection and collection parameters are resolved by priority; the script receives override values via CLI parameters. If the configuration lacks required items or the connection fails, ask the user and guide them to modify the configuration.

Execution flow

1. Check whether tshark is available; if not, prompt the user to install Wireshark (including tshark) and confirm it has been added to PATH; if packet capture is needed, also prompt to install the Npcap driver; if dependencies are missing, terminate execution and output status: error and installation guidance
2. Resolve parameters by priority: CLI > project-level configuration > state file > default values; if multiple sources have values for the same parameter, the higher-priority source takes precedence, and note the overridden source in the output summary
3. If there is no subcommand, execute by default iface(list network interfaces)
4. After successful execution, write the confirmed parameters back to the project configuration
5. Run the corresponding script and output structured JSON results
6. On failure, prioritize prompting about issues such as permissions, Npcap, filters, and interface selection

Subcommands

iface — list network interfaces

python <skill-dir>/scripts/net_iface.py [--filter <关键词>] [--tshark] [--json]

• --tshark: also display the tshark capture interface index mapping
• --filter: filter interfaces by keyword
• No side effects, can be executed directly

capture — capture packets

python <skill-dir>/scripts/net_capture.py [--interface <接口>] [--duration <秒>] [--capture-filter <过滤器>] [--display-filter <过滤器>] [--output <文件路径>] [--format <pcapng|pcap>] [--decode-as <规则>] [--json]

• Interface, filter, and duration are resolved by priority
• --interface: capture interface (overrides configuration)
• --duration: capture duration (overrides configuration)
• --capture-filter: BPF capture filter (overrides configuration)
• --display-filter: Wireshark display filter (overrides configuration)
• --output: path to save the capture file
• --json: output in JSON Lines format (based on tshark -T ek)
• --decode-as: custom decoding rules
• Default format is pcapng; execute directly once parameters are complete

analyze — analyze pcap files

python <skill-dir>/scripts/net_analyze.py <pcap_file> [--mode <summary|protocols|conversations|endpoints|io|anomalies|all>] [--filter <显示过滤器>] [--top <数量>] [--decode-as <规则>] [--export-fields <字段列表>] [--output <CSV路径>] [--json]

• Offline analysis based on tshark and capinfos
• --mode all Output all analysis dimensions
• No side effects, can be executed directly

ping — connectivity test

python <skill-dir>/scripts/net_ping.py [--target <目标>] [--tcp <端口>] [--count <次数>] [--traceroute] [--concurrent <线程数>] [--timeout <毫秒>] [--json]

• Target resolved by priority
• --target: target address (overrides configuration)
• --tcp: TCP connectivity test (specify port)
• --traceroute: perform route tracing
• --timeout: timeout in milliseconds (overrides configuration)
• Execute directly once parameters are complete

scan — port scan

python <skill-dir>/scripts/net_scan.py [--target <目标>] [--ports <端口范围>] [--timeout <毫秒>] [--banner] [--concurrent <线程数>] [--json]

• Target and port range resolved by priority
• --target: target address (overrides configuration)
• --ports: port range, e.g. '80,443,8000-8100' (overrides configuration)
• --banner: attempt to retrieve service Banner
• By default converges to the common embedded port set
• Execute directly once parameters are complete

stats — traffic statistics

python <skill-dir>/scripts/net_stats.py [--interface <接口>] [--duration <秒>] [--display-filter <过滤器>] [--interval <秒>] [--mode <overview|protocol|endpoint|port>] [--json]

• Interface and duration resolved by priority
• --interface: capture interface (overrides configuration)
• --duration: statistics duration (overrides configuration)
• --display-filter: Wireshark display filter (overrides configuration)
• By default outputs JSON summarized by time period
• No side effects, can be executed directly

Output format

All scripts output a unified JSON structure:

{
  "status": "ok",
  "action": "<子命令名>",
  "summary": "<简要描述>",
  "details": { ... }
}

On error:

{
  "status": "error",
  "action": "<子命令名>",
  "error": {
    "code": "<错误码>",
    "message": "<错误描述>"
  }
}

capture --json Outputs JSON Lines, progress information is written to stderr.

Interaction strategy

• Resolve parameters by priority: CLI > project-level configuration > state file > default values
• Prefer to execute directly with the resolved parameters, without additional prompting
• On connection failure, ask the user and guide them to modify the configuration
• After successful execution, confirmed parameters are automatically written back to .embeddedskills/config.json
• When no scan range is given, by default converges to a single host and a small port range
• Results explicitly echo the target range, filter, and duration
• Capture results prioritize summarizing abnormal protocols, retransmissions, RST, etc.
• On capture failure, prioritize prompting about permissions and Npcap issues

Protocol reference

When you need to look up common embedded ports and protocol mappings, read references/common_protocols.json。