Add bundled Wireshark traffic analysis skill

Author: bx33661

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-03-14
+
+### Added
+- Added a bundled Codex skill at `skills/wireshark-traffic-analysis/` for structured packet triage, security hunting, incident response, troubleshooting, and CTF workflows.
+- Added focused skill references for playbooks, evidence grading, reporting, and official Wireshark behavior notes.
+
+### Changed
+- Strengthened the bundled traffic-analysis skill with guidance grounded in official Wireshark documentation for protocol hierarchy, endpoints, conversations, expert info, display filters, and follow-stream behavior.
+- Wheel builds now include the repository `skills/` directory under the installed `wireshark_mcp` package, so the bundled skill ships with release artifacts instead of only the Git repository.
+
 ## [0.6.1] - 2026-03-14
 
 ### Fixed
@@ -69,7 +79,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Decoding: `wireshark_decode_payload` with auto-detection (Base64, Hex, URL, Gzip, Deflate, Rot13)
 - Visualization: ASCII traffic plot, ASCII protocol hierarchy tree
 
-[Unreleased]: https://github.com/bx33661/Wireshark-MCP/compare/v0.6.1...HEAD
+[Unreleased]: https://github.com/bx33661/Wireshark-MCP/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/bx33661/Wireshark-MCP/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/bx33661/Wireshark-MCP/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/bx33661/Wireshark-MCP/compare/v0.4.0...v0.6.0
 [0.4.0]: https://github.com/bx33661/Wireshark-MCP/compare/v0.2.1...v0.4.0

README.md

@@ -289,6 +289,29 @@ Analyze <path/to/file.pcap> using the Wireshark MCP tools.
 
 ---
 
+## Bundled Codex Skill
+
+This repo also includes a Codex skill at `skills/wireshark-traffic-analysis/`.
+It is designed for disciplined packet analysis: start with capture-wide context, choose the right workflow, validate with packet evidence, and finish with actionable next steps.
+The latest revision is also grounded in official Wireshark documentation for protocol hierarchy, endpoints, conversations, expert info, display filters, and stream-follow behavior.
+
+The skill supports these modes:
+
+- `triage`
+- `security`
+- `incident-response`
+- `troubleshoot`
+- `ctf`
+
+Example invocation:
+
+```text
+Use $wireshark-traffic-analysis to investigate <file.pcap>.
+Start in triage mode, escalate if you find suspicious behavior, and produce a concise report with exact filters, streams, frames, confidence, and next steps.
+```
+
+---
+
 ## Prompt Engineering
 
 LLMs perform best with specific, structured prompts. Below are refined prompts for common scenarios:

README_zh.md

@@ -288,6 +288,29 @@ wireshark-mcp --config
 
 ---
 
+## 内置 Codex Skill
+
+这个仓库现在也自带一个 Codex skill，位置在 `skills/wireshark-traffic-analysis/`。
+它不是简单的提示词集合，而是一套更稳的流量分析工作流：先建立全局画像，再选择分析模式，用数据包证据确认结论，最后给出可执行的下一步。
+这次也补进了基于 Wireshark 官方文档整理的关键规则，包括 Protocol Hierarchy、Endpoints、Conversations、Expert Info、Display Filters 和 Follow Stream 的使用边界。
+
+支持的模式：
+
+- `triage`
+- `security`
+- `incident-response`
+- `troubleshoot`
+- `ctf`
+
+示例调用：
+
+```text
+Use $wireshark-traffic-analysis to investigate <file.pcap>.
+Start in triage mode, escalate if you find suspicious behavior, and produce a concise report with exact filters, streams, frames, confidence, and next steps.
+```
+
+---
+
 ## Prompt Engineering（提示词工程）
 
 LLM 在有结构化、具体的提示词时表现最好。以下是针对常见场景的推荐提示词：

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wireshark-mcp"
-version = "0.6.1"
+version = "0.6.2"
 description = "A production-grade Model Context Protocol (MCP) server for Wireshark"
 readme = "README.md"
 keywords = ["mcp", "wireshark", "tshark", "packet-analysis", "network", "pcap", "model-context-protocol", "llm", "security"]
@@ -49,6 +49,9 @@ Changelog = "https://github.com/bx33661/Wireshark-MCP/blob/main/CHANGELOG.md"
 [project.scripts]
 wireshark-mcp = "wireshark_mcp.server:main"
 
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "wireshark_mcp/skills"
+
 [tool.ruff]
 target-version = "py310"
 line-length = 120

skills/wireshark-traffic-analysis/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: "wireshark-traffic-analysis"
+description: "Use when analyzing packet captures or live network traffic with Wireshark MCP; choose the right workflow for triage, security hunting, incident response, troubleshooting, or CTF work, then produce evidence-backed findings with exact filters, streams, frames, and next steps."
+---
+
+# Wireshark Traffic Analysis
+
+Use this skill to turn raw packet captures into a disciplined investigation. The goal is not to list packets. The goal is to build a defensible answer from capture-wide context, protocol-level evidence, and clearly labeled inferences.
+
+## When to use
+
+- `pcap` or `pcapng` analysis
+- live traffic review after capture
+- security triage, threat hunting, or incident response
+- network and protocol troubleshooting
+- CTF and forensics-style packet challenges
+- any task where packet evidence matters more than intuition
+
+## Required inputs
+
+- capture path
+- primary goal: `triage`, `security`, `incident-response`, `troubleshoot`, or `ctf`
+- any known scope: suspicious host, port, domain, time window, protocol, or symptom
+
+If the user does not name a goal, default to `triage`.
+
+## Core workflow
+
+1. Open the capture first.
+   - Use `wireshark_open_file` before protocol-specific tools. It activates contextual tools and gives an initial protocol summary.
+2. Build a global picture before drilling down.
+   - Prefer `wireshark_quick_analysis`, `wireshark_stats_protocol_hierarchy`, `wireshark_stats_endpoints`, and `wireshark_stats_conversations`.
+3. Choose one mode and follow its playbook.
+   - Read [references/playbooks.md](references/playbooks.md) and use the matching section.
+4. Confirm interesting leads with packet-level evidence.
+   - Use `wireshark_follow_stream`, `wireshark_get_packet_details`, `wireshark_get_packet_context`, `wireshark_extract_fields`, and `wireshark_search_packets`.
+5. Separate observation from interpretation.
+   - Facts come from tool output.
+   - Inferences must be labeled `confirmed`, `likely`, `possible`, or `unresolved`.
+6. End with next actions.
+   - Suggest exact display filters, stream indexes, frame numbers, fields, or follow-up questions.
+
+## Analysis rules
+
+- Start broad, then narrow.
+- Prefer Wireshark MCP tools over freehand `tshark` syntax.
+- Never guess display filter syntax. Use `wireshark://reference/display-filters`.
+- Use `wireshark://reference/protocol-fields` when you need field names for extraction or filters.
+- Never decode payloads manually when `wireshark_decode_payload` can verify the result.
+- Treat `wireshark_stats_expert_info` as a lead generator, not a final verdict.
+- When a finding depends on context, follow the full stream before concluding.
+- For large captures, paginate instead of treating the first page as representative.
+- If the capture vantage point could distort interpretation, say so explicitly.
+- If evidence is incomplete, say exactly what is missing.
+
+## Statistics notes
+
+- `wireshark_stats_protocol_hierarchy` is for structure, not naive percentage math. A single packet can contribute to multiple protocol rows across layers.
+- `wireshark_stats_endpoints` is the fastest host inventory view. Use it to identify broadcast, multicast, and heavy talkers before drilling into conversations.
+- `wireshark_stats_conversations` is usually the best place to prioritize long-lived, high-volume, or asymmetric exchanges.
+- Stream indexes are tool evidence too. When `wireshark_follow_stream` explains the finding, include the exact stream index in the report.
+
+For official Wireshark behavior notes and source links, see [references/official-wireshark-notes.md](references/official-wireshark-notes.md).
+
+## Evidence standard
+
+For any non-trivial finding, include at least two of the following:
+
+- the tool call that surfaced it
+- exact host, port, protocol, or field names
+- a stream index or frame number
+- a display filter or field extraction query
+- a short explanation of why the signal matters
+
+When a pattern looks suspicious but could still be normal, read [references/evidence-rubric.md](references/evidence-rubric.md) before concluding.
+
+## Output shape
+
+Use the structure in [references/report-template.md](references/report-template.md). Keep reports concise, evidence-backed, and action-oriented.
+
+## Mode selection
+
+Use the matching playbook in [references/playbooks.md](references/playbooks.md):
+
+- `triage`: unknown capture, fast situational awareness
+- `security`: suspicious traffic, exfiltration, credential exposure, malware behavior
+- `incident-response`: reconstruct the timeline, scope, and affected systems
+- `troubleshoot`: retransmissions, latency, resets, failed handshakes, unstable services
+- `ctf`: flags, hidden payloads, staged transfers, encoded streams
+
+## Built-in prompts and references
+
+If the user mainly needs a starting workflow rather than a full investigation, the MCP prompts in this repo can help:
+
+- `traffic_overview`
+- `security_audit`
+- `performance_analysis`
+- `incident_response`
+- `ctf_solve`
+
+Use `wireshark://guide/usage` when you need the repo's built-in MCP workflow reference.
+
+## Common mistakes to avoid
+
+- calling something malicious because it is uncommon
+- calling something benign because it is encrypted
+- over-trusting a single heuristic such as long DNS queries or one retransmission
+- skipping endpoints and conversations, then missing the real top talker
+- reporting a hypothesis as a confirmed root cause

skills/wireshark-traffic-analysis/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Wireshark Traffic Analysis"
+  short_description: "Triage, hunt, and debug packet captures"
+  default_prompt: "Use $wireshark-traffic-analysis to investigate this capture, choose the right workflow, and produce an evidence-backed packet analysis report."
+
+policy:
+  allow_implicit_invocation: true

skills/wireshark-traffic-analysis/references/evidence-rubric.md

@@ -0,0 +1,165 @@
+# Evidence Rubric
+
+Use this rubric when a pattern looks suspicious but the capture alone may not be enough to prove intent or root cause.
+
+## Contents
+
+- [Confidence labels](#confidence-labels)
+- [Vantage point checks](#vantage-point-checks)
+- [Common signals](#common-signals)
+
+## Confidence labels
+
+Use these labels consistently:
+
+- `confirmed`: directly supported by packet evidence with little ambiguity
+- `likely`: multiple signals support the conclusion, but another explanation is still plausible
+- `possible`: one or two weak indicators exist, but the conclusion is not stable
+- `unresolved`: the capture suggests a question, not an answer
+
+## Vantage point checks
+
+Before concluding, ask:
+
+- Is this capture from the client, server, gateway, mirror port, or only one side of the path?
+- Could packet loss in the capture itself create fake retransmissions or gaps?
+- Are missing packets making application behavior look incomplete?
+- Is TLS decryption unavailable, limiting what can be claimed about payloads?
+
+If vantage point uncertainty affects the conclusion, mention it explicitly.
+
+## Common signals
+
+### DNS tunneling
+
+Treat DNS as suspicious only when several indicators align:
+
+- unusually long query names
+- many unique subdomains under one base domain
+- repetitive TXT or NULL queries
+- regular beacon-like cadence
+- high-entropy labels
+- weak or failed response patterns
+
+Counterexamples:
+
+- CDN hostnames
+- telemetry platforms
+- service discovery
+- anti-malware lookups
+
+Good confirmation tools:
+
+- `wireshark_detect_dns_tunnel`
+- `wireshark_extract_dns_queries`
+- `wireshark_extract_fields` with `dns.qry.name`, `dns.qry.type`, `ip.src`, `ip.dst`
+
+### Port scanning
+
+Treat scanning as stronger when you see:
+
+- one source probing many ports or many hosts
+- many SYN-only attempts with little follow-through
+- short-lived connections with consistent fan-out
+
+Counterexamples:
+
+- vulnerability scanners you already own
+- health checks
+- inventory tooling
+- load balancer probes
+
+Good confirmation tools:
+
+- `wireshark_detect_port_scan`
+- `wireshark_extract_fields` with `ip.src`, `ip.dst`, `tcp.dstport`, `tcp.flags.syn`
+- `wireshark_stats_conversations`
+
+### Credential exposure
+
+Only call credentials exposed when the capture actually contains the secret or credential-bearing field.
+
+Examples:
+
+- `http.authbasic`
+- FTP `PASS`
+- Telnet plaintext login flows
+
+Good confirmation tools:
+
+- `wireshark_extract_credentials`
+- `wireshark_follow_stream`
+- `wireshark_get_packet_details`
+
+### Exfiltration or suspicious data transfer
+
+Treat exfiltration as stronger when you see:
+
+- sustained asymmetric upload volume
+- repetitive uploads to a narrow destination set
+- encoded or staged payloads
+- suspicious destinations plus meaningful payload movement
+
+Counterexamples:
+
+- backups
+- software updates
+- sync clients
+- log shipping
+
+Good confirmation tools:
+
+- `wireshark_stats_conversations`
+- `wireshark_follow_stream`
+- `wireshark_extract_http_requests`
+- `wireshark_export_objects`
+
+### TLS suspicion
+
+TLS alone is not suspicious. Treat it as more interesting when it overlaps with:
+
+- failed or unusual handshakes
+- uncommon SNI targets
+- self-signed or mismatched certificates
+- suspicious destinations found elsewhere in the capture
+
+Counterexamples:
+
+- internal PKI
+- TLS interception
+- test environments
+
+Good confirmation tools:
+
+- `wireshark_extract_tls_handshakes`
+- `wireshark_check_threats`
+- `wireshark_follow_stream`
+
+### TCP health problems
+
+One retransmission rarely proves a network issue. Stronger cases include:
+
+- repeated retransmissions in the same conversation
+- duplicate ACK bursts
+- zero-window events
+- resets aligned with user-visible failures
+
+Counterexamples:
+
+- capture loss
+- transient congestion
+- intentionally closed connections
+
+Good confirmation tools:
+
+- `wireshark_analyze_tcp_health`
+- `wireshark_stats_expert_info`
+- `wireshark_follow_stream`
+
+## Reporting rule
+
+Whenever a claim could be disputed, include:
+
+- the signal
+- the counter-interpretation
+- why your conclusion still holds, or why it remains unresolved