Back to Details

net

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Net Debug Skill

Net Debug Skill

嵌入式网络通信调试工具，统一封装接口发现、抓包、离线分析、连通性测试、端口扫描和流量统计能力。
Embedded network communication debugging tool that encapsulates capabilities including interface discovery, packet capture, offline analysis, connectivity testing, port scanning, and traffic statistics in a unified manner.

脚本与配置路径

Script and Configuration Paths

  • 脚本目录: 
    <skill-dir>/scripts/
  • 环境级配置: 
    <skill-dir>/config.json
    （仅工具路径）
  • 工程级配置: 
    <workspace>/.embeddedskills/config.json
    （网络参数）
  • 协议参考: 
    <skill-dir>/references/common_protocols.json
  • 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
    (随 Wireshark 安装，需加入 PATH)
  • dumpcap
    (随 Wireshark 安装)
  • 可选: 
    capinfos
  • Windows 自带: 
    ipconfig
    、
    ping
    、
    tracert
    、
    netstat
    、
    arp
    、
    nslookup
  • Python 3.x (仅标准库)
  • 抓包需要 Npcap 驱动，部分环境需管理员权限
  • tshark
    (installed with Wireshark, needs to be added to PATH)
  • dumpcap
    (installed with Wireshark)
  • Optional: 
    capinfos
  • Windows built-in tools: 
    ipconfig
    , 
    ping
    , 
    tracert
    , 
    netstat
    , 
    arp
    , 
    nslookup
  • Python 3.x (standard library only)
  • Packet capture requires Npcap driver; administrator privileges may be required in some environments

配置

Configuration

环境级配置 (
skill/config.json
)

Environment-level Configuration (
skill/config.json
)

仅保留工具路径相关的环境级配置：
json
{
  "tshark_exe": "tshark",
  "capinfos_exe": "capinfos"
}
Only keep environment-level configuration related to tool paths:
json
{
  "tshark_exe": "tshark",
  "capinfos_exe": "capinfos"
}

工程级配置 (
.embeddedskills/config.json
)

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

工作区下的 
.embeddedskills/config.json
存放工程级网络配置：
json
{
  "net": {
    "interface": "",
    "target": "",
    "capture_filter": "",
    "display_filter": "",
    "duration": 30,
    "timeout_ms": 1000,
    "scan_ports": "",
    "capture_format": "pcapng",
    "log_dir": ".embeddedskills/logs/net"
  }
}
The 
.embeddedskills/config.json
under the workspace stores project-level network configurations:
json
{
  "net": {
    "interface": "",
    "target": "",
    "capture_filter": "",
    "display_filter": "",
    "duration": 30,
    "timeout_ms": 1000,
    "scan_ports": "",
    "capture_format": "pcapng",
    "log_dir": ".embeddedskills/logs/net"
  }
}

参数解析优先级

Parameter Parsing Priority

  1. CLI 参数 (
    --interface
    , 
    --target
    等) - 最高优先级
  2. 工程级配置 (
    .embeddedskills/config.json
    中的 
    net
    部分)
  3. 状态文件 (
    .embeddedskills/state.json
    中的历史记录)
  4. 默认值 - 最低优先级
连接和采集参数按优先级解析，脚本通过 CLI 参数接收覆盖值。若配置缺少必要项或连接失败，询问用户并引导修改配置。
  1. CLI parameters (
    --interface
    , 
    --target
    etc.) - Highest priority
  2. Project-level configuration (the 
    net
    section in 
    .embeddedskills/config.json
    )
  3. State file (historical records in 
    .embeddedskills/state.json
    )
  4. Default values - Lowest priority
Connection and collection parameters are parsed according to priority, and scripts receive override values via CLI parameters. If necessary items are missing from the configuration or connection fails, ask the user and guide them to modify the configuration.

执行流程

Execution Flow

  1. 检查 
    tshark
    是否可用
  2. 按优先级解析参数：CLI > 工程级配置 > 状态文件 > 默认值
  3. 若无子命令，默认执行 
    iface
    （列出网络接口）
  4. 成功执行后，将确认的参数写回工程配置
  5. 运行对应脚本并输出结构化 JSON 结果
  6. 失败时优先提示权限、Npcap、过滤器、接口选择等问题
  1. Check if 
    tshark
    is available
  2. Parse parameters by priority: CLI > Project-level configuration > State file > Default values
  3. If no subcommand is provided, execute 
    iface
    (list network interfaces) by default
  4. After successful execution, write the confirmed parameters back to the project configuration
  5. Run the corresponding script and output structured JSON results
  6. When failed, prioritize prompting issues such as permissions, Npcap, filters, interface selection, etc.

子命令

Subcommands

iface — 列出网络接口

iface — List Network Interfaces

bash
python <skill-dir>/scripts/net_iface.py [--filter <关键词>] [--tshark] [--json]
  • --tshark
    : 同时显示 tshark 抓包接口索引映射
  • --filter
    : 按关键词筛选接口
  • 无副作用，可直接执行
bash
python <skill-dir>/scripts/net_iface.py [--filter <keyword>] [--tshark] [--json]
  • --tshark
    : Display tshark packet capture interface index mapping at the same time
  • --filter
    : Filter interfaces by keyword
  • No side effects, can be executed directly

capture — 抓包

capture — Packet Capture

bash
python <skill-dir>/scripts/net_capture.py [--interface <接口>] [--duration <秒>] [--capture-filter <过滤器>] [--display-filter <过滤器>] [--output <文件路径>] [--format <pcapng|pcap>] [--decode-as <规则>] [--json]
  • 接口、过滤器、时长按优先级解析
  • --interface
    : 抓包接口（覆盖配置）
  • --duration
    : 抓包时长（覆盖配置）
  • --capture-filter
    : BPF 抓包过滤器（覆盖配置）
  • --display-filter
    : Wireshark 显示过滤器（覆盖配置）
  • --output
    : 保存抓包文件路径
  • --json
    : 输出 JSON Lines 格式（基于 tshark -T ek）
  • --decode-as
    : 自定义解码规则
  • 默认格式 pcapng，参数完整后直接执行
bash
python <skill-dir>/scripts/net_capture.py [--interface <interface>] [--duration <seconds>] [--capture-filter <filter>] [--display-filter <filter>] [--output <file path>] [--format <pcapng|pcap>] [--decode-as <rule>] [--json]
  • Interface, filter, and duration are parsed according to priority
  • --interface
    : Packet capture interface (overrides configuration)
  • --duration
    : Packet capture duration (overrides configuration)
  • --capture-filter
    : BPF packet capture filter (overrides configuration)
  • --display-filter
    : Wireshark display filter (overrides configuration)
  • --output
    : Path to save the captured packet file
  • --json
    : Output in JSON Lines format (based on tshark -T ek)
  • --decode-as
    : Custom decoding rules
  • Default format is pcapng; execute directly after parameters are complete

analyze — 分析 pcap 文件

analyze — Analyze pcap Files

bash
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]
  • 基于 tshark 和 capinfos 进行离线分析
  • --mode all
    输出全部分析维度
  • 无副作用，可直接执行
bash
python <skill-dir>/scripts/net_analyze.py <pcap_file> [--mode <summary|protocols|conversations|endpoints|io|anomalies|all>] [--filter <display filter>] [--top <number>] [--decode-as <rule>] [--export-fields <field list>] [--output <CSV path>] [--json]
  • Offline analysis based on tshark and capinfos
  • --mode all
    outputs all analysis dimensions
  • No side effects, can be executed directly

ping — 连通性测试

ping — Connectivity Testing

bash
python <skill-dir>/scripts/net_ping.py [--target <目标>] [--tcp <端口>] [--count <次数>] [--traceroute] [--concurrent <线程数>] [--timeout <毫秒>] [--json]
  • 目标按优先级解析
  • --target
    : 目标地址（覆盖配置）
  • --tcp
    : TCP 连通性测试（指定端口）
  • --traceroute
    : 执行路由追踪
  • --timeout
    : 超时毫秒数（覆盖配置）
  • 参数完整后直接执行
bash
python <skill-dir>/scripts/net_ping.py [--target <target>] [--tcp <port>] [--count <times>] [--traceroute] [--concurrent <thread count>] [--timeout <milliseconds>] [--json]
  • Target is parsed according to priority
  • --target
    : Target address (overrides configuration)
  • --tcp
    : TCP connectivity test (specify port)
  • --traceroute
    : Execute traceroute
  • --timeout
    : Timeout in milliseconds (overrides configuration)
  • Execute directly after parameters are complete

scan — 端口扫描

scan — Port Scanning

bash
python <skill-dir>/scripts/net_scan.py [--target <目标>] [--ports <端口范围>] [--timeout <毫秒>] [--banner] [--concurrent <线程数>] [--json]
  • 目标和端口范围按优先级解析
  • --target
    : 目标地址（覆盖配置）
  • --ports
    : 端口范围，如 '80,443,8000-8100'（覆盖配置）
  • --banner
    : 尝试获取服务 Banner
  • 默认收敛到嵌入式常用端口集
  • 参数完整后直接执行
bash
python <skill-dir>/scripts/net_scan.py [--target <target>] [--ports <port range>] [--timeout <milliseconds>] [--banner] [--concurrent <thread count>] [--json]
  • Target and port range are parsed according to priority
  • --target
    : Target address (overrides configuration)
  • --ports
    : Port range, e.g., '80,443,8000-8100' (overrides configuration)
  • --banner
    : Attempt to obtain service banner
  • Default converges to port sets commonly used in embedded systems
  • Execute directly after parameters are complete

stats — 流量统计

stats — Traffic Statistics

bash
python <skill-dir>/scripts/net_stats.py [--interface <接口>] [--duration <秒>] [--display-filter <过滤器>] [--interval <秒>] [--mode <overview|protocol|endpoint|port>] [--json]
  • 接口和时长按优先级解析
  • --interface
    : 抓包接口（覆盖配置）
  • --duration
    : 统计时长（覆盖配置）
  • --display-filter
    : Wireshark 显示过滤器（覆盖配置）
  • 默认输出按时段汇总的 JSON
  • 无副作用，可直接执行
bash
python <skill-dir>/scripts/net_stats.py [--interface <interface>] [--duration <seconds>] [--display-filter <filter>] [--interval <seconds>] [--mode <overview|protocol|endpoint|port>] [--json]
  • Interface and duration are parsed according to priority
  • --interface
    : Packet capture interface (overrides configuration)
  • --duration
    : Statistics duration (overrides configuration)
  • --display-filter
    : Wireshark display filter (overrides configuration)
  • Default outputs JSON summarized by time period
  • No side effects, can be executed directly

输出格式

Output Format

所有脚本输出统一的 JSON 结构:
json
{
  "status": "ok",
  "action": "<子命令名>",
  "summary": "<简要描述>",
  "details": { ... }
}
错误时:
json
{
  "status": "error",
  "action": "<子命令名>",
  "error": {
    "code": "<错误码>",
    "message": "<错误描述>"
  }
}
capture --json
输出 JSON Lines，进度信息写入 stderr。
All scripts output a unified JSON structure:
json
{
  "status": "ok",
  "action": "<subcommand name>",
  "summary": "<brief description>",
  "details": { ... }
}
In case of error:
json
{
  "status": "error",
  "action": "<subcommand name>",
  "error": {
    "code": "<error code>",
    "message": "<error description>"
  }
}
capture --json
outputs JSON Lines, and progress information is written to stderr.

交互策略

Interaction Strategy

  • 按优先级解析参数：CLI > 工程级配置 > 状态文件 > 默认值
  • 优先用解析后的参数直接执行，不额外询问
  • 连接失败时再询问用户并引导修改配置
  • 成功执行后，确认的参数自动写回 
    .embeddedskills/config.json
  • 未给扫描范围时默认收敛到单主机、小范围端口
  • 结果中明确回显目标范围、过滤器和持续时间
  • 抓包结果优先总结异常协议、重传、RST 等
  • 抓包失败优先提示权限和 Npcap 问题
  • Parse parameters by priority: CLI > Project-level configuration > State file > Default values
  • Prioritize direct execution with parsed parameters without additional inquiries
  • Ask the user and guide configuration modification only when connection fails
  • After successful execution, automatically write confirmed parameters back to 
    .embeddedskills/config.json
  • Default converges to single host and small port range when no scanning range is specified
  • Clearly echo target range, filters, and duration in results
  • Prioritize summarizing abnormal protocols, retransmissions, RST, etc. in packet capture results
  • Prioritize prompting permission and Npcap issues when packet capture fails

协议参考

Protocol Reference

需要查询嵌入式常用端口和协议映射时，读取 
references/common_protocols.json
。
When querying port and protocol mappings commonly used in embedded systems, read 
references/common_protocols.json
.