Analyze local Wireshark pcap/pcapng packet capture files and produce a structured Markdown diagnosis report. The analyzer covers TCP transfer performance (throughput, window, RTT, retransmission), connection anomalies (FIN/RST, failed handshakes), IPsec/IKE VPN negotiation, MTU/large-packet issues, DNS resolution, TLS handshake, ICMP errors, and TCP zero-window/Keepalive behavior. Suspicious patterns are reported in dedicated dynamic sections, and the report ends with a consolidated conclusion ranking the likely root causes.
Requires Python 3 and the scapy library:
pip3 install scapy
Module Index
| Module | Purpose | File |
|---|---|---|
| Analysis Rules | Diagnosis decision rules and thresholds (rate, FIN/RST, retransmission, window, RTT, MTU modes, DNS, TLS, TCP setup, ICMP, zero window, IKE) | references/analysis-rules.md |
| Report Structure | The 16-section report layout and the trigger conditions of the dynamic sections | references/report-structure.md |
| Limitations | Usage limitations and full notes for interpreting results | references/limitations.md |
Load references on demand. Do not read all reference files unless the task requires them.
User Confirmation
- Before running any analysis, confirm the pcap file path with the user.
- If the user has not provided a pcap file, ask for the file path first. Never guess, derive, or scan for pcap files on your own.
Execution Principle
MANDATORY:
- Read-only: this skill only reads and analyzes. It MUST NOT modify, move, or delete any user file, and it requires no credentials of any kind.
- Single entry point: all analysis MUST be executed through the entry script
scripts/pcap_analyze.py. Do not hand-assemble diagnostic command chains. - User-provided files only: only analyze pcap files the user explicitly specifies. Never open or analyze files the user did not point to.
- No scanning: never search for or open pcap files beyond the one the user provided.
Capabilities
| # | Capability | Description |
|---|---|---|
| C1 | Transfer Rate Diagnosis | Per-second throughput statistics, peak/average/minimum, sudden-drop detection, and root-cause ranking |
| C2 | TCP Performance Analysis | Window shrinkage/zero-window, RTT statistics and spikes, retransmission bursts, out-of-order and duplicate ACK detection |
| C3 | Connection Anomaly Detection | Abnormal FIN/RST terminations, RST-with-payload (middlebox injection) detection, failed TCP handshakes |
| C4 | IPsec/IKE Negotiation Analysis | IKEv1/IKEv2 auto-detection, SA proposal suites, notify messages, retry patterns, NAT-T detection |
| C5 | MTU / Large-Packet Analysis | ICMP Fragmentation Needed, large-packet ratio, MSS vs. retransmission mismatch, remediation advice |
| C6 | DNS Anomaly Analysis | NXDOMAIN/SERVFAIL/REFUSED, unanswered queries, TCP fallback, slow queries |
| C7 | TLS Handshake Analysis | ClientHello/ServerHello pairing, Alert messages, outdated protocol versions, SNI extraction |
| C8 | ICMP Error Summary | Destination Unreachable / Time Exceeded / Redirect classification |
| C9 | Filtered Analysis | Focus on a specific flow with --src, --dst, --port |
| C10 | Markdown Report Output | Write the full report to a file with --output |
Detection rules and thresholds behind each capability are documented in references/analysis-rules.md.
Commands
Set the skill directory once, then run the entry script:
SKILL_DIR=~/.qoderwork/skills/alibabacloud-pcap-analyzer
Analyze a whole capture file
cd $SKILL_DIR && python3 scripts/pcap_analyze.py capture.pcap
Filter by source/destination IP and port
cd $SKILL_DIR && python3 scripts/pcap_analyze.py capture.pcap --src 10.0.0.1 --dst 10.0.0.2 --port 443
Write the report to a Markdown file
cd $SKILL_DIR && python3 scripts/pcap_analyze.py capture.pcap --output report.md
Parameters
| Parameter | Description |
|---|---|
pcap |
Path to the pcap/pcapng file (required) |
--src <IP> |
Filter by source IP |
--dst <IP> |
Filter by destination IP |
--port <PORT> |
Filter by TCP port |
--output <FILE> |
Output Markdown file path (defaults to stdout when omitted) |
Exit code contract: 0 = analysis succeeded; 1 = input/file error (missing path, not a regular file, or not readable); 2 = missing dependency (scapy not installed).
Report Overview
The analyzer outputs a Markdown report with up to 16 sections. The first eight sections are always present and cover the capture basics: file metadata, TCP session overview, transfer rate, window size, RTT, retransmission/reordering, FIN/RST behavior, and packet size distribution.
Sections 9 through 15 are dynamic and appear only when the corresponding analysis detects a suspicious pattern: DNS anomalies, TLS handshake failures, TCP connection establishment failures, ICMP error summary, MTU/large-packet issues, TCP zero-window/Keepalive events, and IPsec/IKE negotiation (the IKE section appears when UDP 500/4500 traffic is present). The final section is a consolidated diagnosis conclusion that aggregates all detected anomalies and ranks the likely causes of the observed problem. See references/report-structure.md for the full section list and trigger conditions, and references/analysis-rules.md for the detection rules behind each section.
Examples
Example 1: User: "File transfer between these two servers is very slow, here is the capture: /tmp/transfer.pcap"
cd $SKILL_DIR && python3 scripts/pcap_analyze.py /tmp/transfer.pcap --src 10.0.0.1 --dst 10.0.0.2 --output slow_transfer.md
Example 2: User: "Our site-to-site VPN keeps failing to establish, analyze this capture."
cd $SKILL_DIR && python3 scripts/pcap_analyze.py vpn_ike.pcap --output ike_report.md
Example 3: User: "DNS lookups fail intermittently, I captured the traffic."
cd $SKILL_DIR && python3 scripts/pcap_analyze.py dns_issue.pcap --port 53 --output dns_report.md
Example 4: User: "Large packets do not go through over the VPN, small ones work fine."
cd $SKILL_DIR && python3 scripts/pcap_analyze.py mtu_issue.pcap --output mtu_report.md
Important Notes
- The analysis relies on complete TCP streams. RTT calculation and accurate retransmission/out-of-order detection require captures that include the SYN/SYN-ACK handshake.
- For encrypted traffic (TLS), the analysis works at the TCP/TLS-handshake layer, not at the application layer; encrypted payloads cannot be inspected.
- Large captures (over 100 MB) may take a long time to analyze. Narrow the scope first with
--src,--dst, or--port. - When a capture contains multiple sessions, use the filter parameters to focus on the IP/port the user cares about.
- The IPsec/IKE section is generated only when the capture contains IKE traffic on UDP 500 or UDP 4500. Both IKEv1 and IKEv2 are supported.
- The DNS section is generated only when DNS traffic (UDP/TCP 53) is present; the TLS section only when TLS traffic is present.
- The MTU/large-packet section appears only when a suspicious pattern is detected (e.g. ICMP Fragmentation Needed, very low large-packet ratio). Normal traffic does not produce this section.
- For VPN/IPsec deployments, encapsulation adds roughly 50-80 bytes of overhead; consider lowering the interface MTU to 1400 or below on both VPN endpoints.
- See references/limitations.md for the complete list of limitations and interpretation caveats.