Interactive protocol visualization for network engineers, students, and anyone curious about what happens on the wire.
Live: https://provandal.github.io/protoviz/
ProtoViz is an open-source, browser-based platform that turns protocol exchanges into interactive, step-by-step visualizations. Each scenario is a YAML file describing a complete protocol interaction — from physical link establishment through application-layer operations — with every frame field annotated with spec references and Linux kernel source cross-links.
- 14 Languages — Full internationalization: English, Spanish, French, German, Portuguese (BR), Russian, Ukrainian, Mandarin, Japanese, Korean, Hindi, Hebrew, Lebanese Arabic, and Haitian Creole — with RTL support and CJK font stacks
- GeoLingua Integration — Interactive globe language selector with dropdown fallback
- Animated Sequence Diagrams — Phase-grouped timeline with play/pause/step and scrubbing
- OSI Stack Visualization — Live 7-layer state for each actor, updated per step
- Wireshark-style Packet Inspector — Drill into every header field with expandable details, spec references, and kernel source links
- AI Chat — Protocol Q&A with full context awareness (bring your own API key)
- PCAP Troubleshooter — Upload a capture file for client-side parsing, rule-based compliance checking, and AI-assisted analysis (nothing leaves your browser unless you opt in to chat)
- tshark JSON Import — Full protocol dissection via Wireshark's 3000+ dissectors without GPL entanglement
- Annotations — Add personal notes to any step, export/import as JSON
- Pop-out Detail Panel — Detach the bottom pane to a separate window for multi-monitor setups
- Mobile-Responsive UI — Tab-based navigation on small screens, touch-friendly controls, adaptive layout
- Keyboard Navigation — Arrow keys, Space (play/pause), Home/End, 1-4 (tab switch)
- Deep Links — Shareable URLs pointing to a specific scenario and step
- Scenario Gallery — Browse, filter, and search available scenarios
- MCP Server — Protocol knowledge tools for AI agents via Model Context Protocol
The library spans 6 protocol families across 3 difficulty levels (5 beginner, 6 intermediate, 12 advanced).
| Scenario | Protocol | Difficulty |
|---|---|---|
| TCP: 3-Way Handshake → Data Transfer → FIN Teardown | TCP | Beginner |
| ARP & NDP: IPv4 Address Resolution and IPv6 Neighbor Discovery | ARP / NDP | Beginner |
| Checking Your Email: What Really Happens When You Click Inbox | DNS, TCP, TLS 1.3, HTTP/2 | Beginner |
| TLS 1.3: Full Handshake → Encrypted Application Data → Alert Close | TLS 1.3 | Intermediate |
| Scenario | Protocol | Difficulty |
|---|---|---|
| IPv6 SLAAC: Router Advertisement → DAD → Address Autoconfiguration | ICMPv6 / NDP | Beginner |
| IPv6 vs IPv4 Header: Why IPv6 Is Faster on the Wire | IPv6 / IPv4 | Beginner |
| Happy Eyeballs: How Your Browser Chooses IPv4 vs IPv6 | TCP / DNS / IPv6 / IPv4 | Beginner |
| DHCPv6: Stateful vs Stateless — When RA Isn't Enough | DHCPv6 / ICMPv6 | Intermediate |
| NAT64/DNS64: IPv6-Only Client Talking to an IPv4-Only Server | NAT64 / DNS64 | Intermediate |
| IPv6 Path MTU Discovery: No More Router Fragmentation | ICMPv6 / IPv6 | Intermediate |
| Scenario | Protocol | Difficulty |
|---|---|---|
| PFC Pause → ECN Marking → DCQCN Rate Control | RoCEv2 Congestion Control | Intermediate |
| RoCEv2 RC: Link Training → QP Connection → RDMA WRITE → RDMA READ | RoCEv2 | Advanced |
| SMB Direct: Negotiate → RDMA Channel → File Read & Write over RoCEv2 | SMB Direct (SMB 3.x over RDMA) | Advanced |
| S3/RDMA: Object PUT and GET over RoCEv2 | S3/RDMA | Advanced |
| Scenario | Protocol | Difficulty |
|---|---|---|
| iSCSI: Login → Discovery → SCSI INQUIRY → WRITE(10) → READ(10) | iSCSI | Intermediate |
| FC Fabric: FLOGI → Name Server → PLOGI → PRLI → SCSI I/O | Fibre Channel | Advanced |
| NVMe-oF/RDMA: Discovery → Fabrics Connect → NVMe Write & Read over RoCEv2 | NVMe-oF/RDMA | Advanced |
| NVMe/TCP: mDNS → CDC Discovery → DIM → Subsystem Connect → I/O | NVMe-oF/TCP | Advanced |
| Scenario | Protocol | Difficulty |
|---|---|---|
| GPUDirect RDMA: RoCEv2 WRITE Direct to GPU Memory | RoCEv2 + GPUDirect | Advanced |
| GPUDirect Storage: NVMe Read Direct to GPU Memory (Local PCIe) | NVMe + GPUDirect Storage | Advanced |
| GPUDirect Storage: Remote NVMe-oF Read/Write to GPU Memory over RoCEv2 | NVMe-oF/RDMA + GPUDirect Storage | Advanced |
| GPU-to-GPU RDMA: Tensor Transfer across Nodes via RoCEv2 | RoCEv2 + GPUDirect RDMA | Advanced |
| NCCL AllReduce: Ring Algorithm over RoCEv2 (4 GPUs) | NCCL / RoCEv2 | Advanced |
git clone https://github.com/provandal/protoviz.git
cd protoviz
npm install
npm run devOpen http://localhost:5173 in your browser.
npm run build # outputs to dist/
npm run preview # preview the production build locallypip install scapy pyyaml anthropic
python tools/converter.py my_capture.pcap --out public/scenarios/my_protocol/my_scenario.yamlThe Troubleshooter analyzes packet captures for protocol compliance — entirely in your browser. No data leaves your machine unless you opt in to the AI chat feature.
The Troubleshooter accepts two input formats:
Drag and drop or select a standard PCAP file. ProtoViz parses it client-side using built-in JavaScript dissectors.
Built-in dissectors: Ethernet, IPv4, ARP, TCP, UDP, RoCEv2 (BTH, RETH, AETH)
This is the simplest path — no tools needed beyond a browser. Ideal for RoCEv2 and basic TCP/UDP analysis.
For full protocol dissection (FC, iSCSI, NVMe-oF, QUIC, TLS, and 3000+ other protocols), pre-process your capture with Wireshark's tshark command-line tool and upload the JSON output:
# Basic: full dissection as JSON
tshark -r capture.pcap -T json > capture.json
# With display filter (e.g., only RoCEv2 traffic)
tshark -r capture.pcap -T json -Y "infiniband" > roce_only.json
# First 500 packets only
tshark -r capture.pcap -T json -c 500 > first500.jsonThen upload capture.json to the Troubleshooter. ProtoViz maps tshark's protocol layers to its internal format, giving you the same packet list, findings panel, and chat experience with far deeper dissection.
Why tshark JSON? Wireshark is GPL-licensed. By using tshark as a separate pre-processing step (rather than linking against libwireshark), ProtoViz remains MIT-licensed while giving you access to the full Wireshark dissector ecosystem. This is the same approach used by most commercial tools that integrate with Wireshark.
Installing tshark: tshark ships with Wireshark. Install Wireshark from wireshark.org — tshark is included automatically. On Linux: apt install tshark or yum install wireshark-cli.
The Troubleshooter runs declarative compliance rules against parsed packets:
| Rule | Type | Severity | What it checks |
|---|---|---|---|
| TCP RST detection | tcp_flag_present |
Error | Flags connection resets |
| PSN continuity | psn_sequence |
Error | Detects gaps in RoCEv2 Packet Sequence Numbers per QP |
| RDMA Write → ACK | sequence_pattern |
Warning | Verifies RDMA Write is followed by an Acknowledge |
| RDMA Read → Response | sequence_pattern |
Warning | Verifies RDMA Read Request is followed by a Read Response |
| UDP port 4791 | field_value |
Info | Confirms RoCEv2 traffic uses the correct well-known port |
Rules are defined in public/rules/roce-v2.json. Adding new rules requires no code changes — just add entries to the JSON file.
Each finding in the right panel is clickable. Clicking a finding scrolls to and highlights the corresponding packet in the packet list, expanding its dissection detail.
Click the Chat button in the toolbar to open an AI assistant panel. The assistant receives full context about your trace — protocol breakdown, IP endpoints, all findings, and the currently selected packet's dissection — so it can help you understand what went wrong.
Requires an Anthropic API key (stored in localStorage, sent only to api.anthropic.com).
ProtoViz includes an MCP (Model Context Protocol) server that exposes protocol knowledge to AI agents.
cd mcp
npm install
npm start| Tool | Description |
|---|---|
list_protocols |
List all available scenarios |
get_scenario_timeline |
Get the full event timeline |
lookup_field |
Look up a field by abbreviation (e.g., bth.opcode) |
get_spec_reference |
Get spec references for a header |
get_state_machine |
Get state transitions for an actor |
get_expected_sequence |
Get expected packet sequence for an operation |
protoviz/
├── src/
│ ├── components/
│ │ ├── viewer/ # Sequence diagram, OSI stacks, packet inspector
│ │ ├── gallery/ # Landing page, scenario cards, filters
│ │ ├── layout/ # Split layout, bottom pane, popout view
│ │ ├── chat/ # AI chat panel (scenario viewer)
│ │ ├── troubleshooter/ # PCAP upload, packet list, findings, trace chat
│ │ ├── common/ # Language selector (GeoLingua + dropdown)
│ │ └── about/ # About panel
│ ├── hooks/ # useScenario, usePlayback, useKeyboardNav, usePopout, useAnnotations, useDirection
│ ├── i18n/ # i18next configuration (14 languages)
│ ├── pcap/ # PCAP parser, tshark JSON reader, dissectors, rule engine
│ ├── store/ # Zustand state management
│ ├── utils/ # Constants, state engine, normalizer, translation overlays
│ └── styles/ # Global CSS with RTL overrides and CJK font stacks
├── public/
│ ├── scenarios/ # YAML scenario files + index.json manifest (23 scenarios)
│ ├── locales/ # UI chrome translations (14 languages × 193+ keys)
│ ├── gallery-i18n/ # Gallery card translations (title, description per scenario)
│ ├── scenario-i18n/ # Scenario content overlays (timeline, walkthroughs, meta)
│ │ ├── ar-LB/ # Lebanese Arabic (23 scenarios)
│ │ ├── ht/ # Haitian Creole (23 scenarios)
│ │ ├── zh-CN/ # Mandarin Simplified (23 scenarios)
│ │ ├── he/ # Hebrew (23 scenarios)
│ │ ├── ... # + 9 more languages (es, fr, de, hi, pt-BR, ja, ru, ko, uk)
│ │ └── README.md
│ └── rules/ # Declarative compliance rules (JSON)
├── mcp/ # MCP server for AI agents
├── tools/ # Python PCAP converter, translation extraction
├── .github/workflows/ # GitHub Pages deployment
├── scenario.schema.json # JSON Schema for scenario validation
└── index.html # Vite entry point
Scenarios are YAML files conforming to scenario.schema.json. Key sections:
topology— Actors (hosts, switches) and physical linksosi_layers— Per-actor layer definitions with state schemasframes— Frame library with header trees and annotated fieldstimeline— Ordered events referencing frames and state deltasglossary— Protocol terms with definitions
Each field can carry spec_refs (IBTA, RFC, IEEE, T11/INCITS), kernel_ref (Linux kernel source), and description.
See any scenario directory under public/scenarios/ for complete examples.
The viewer is grounded in Linux kernel source. Kernel references are cited at the field level:
| Scenario Element | Kernel Source |
|---|---|
| QP state machine transitions | drivers/infiniband/core/verbs.c → ib_modify_qp() |
| QP creation, WQE posting | drivers/infiniband/hw/mlx5/qp.c → mlx5_ib_create_qp() |
| Memory Region registration | drivers/infiniband/hw/mlx5/mr.c → mlx5_ib_reg_user_mr() |
| Connection Manager REQ/REP/RTU | drivers/infiniband/core/cm.c → ib_send_cm_req() |
| FC ELS (FLOGI/PLOGI/PRLI) | drivers/scsi/lpfc/lpfc_els.c → lpfc_issue_els_flogi() |
| FC Name Server queries | drivers/scsi/lpfc/lpfc_ct.c → lpfc_ns_cmd() |
| SCSI target discovery | drivers/scsi/scsi_scan.c → scsi_scan_host() |
See CONTRIBUTING.md for guidelines. We welcome new scenarios, dissectors, compliance rules, and viewer improvements.
Created by: Erik Smith Distinguished Engineer - Dell Technologies
AI Contributors: Built with Claude.AI and Claude Code by Anthropic
- Linux RDMA community (
rdma-core,drivers/infiniband/) - InfiniBand Trade Association — IBTA specifications
- T11 Technical Committee — Fibre Channel specifications (FC-FS, FC-LS, FC-GS, FCP)
- Wireshark project — tshark JSON integration for full protocol dissection
Protocol descriptions in ProtoViz scenarios are based on open-source implementations (Linux kernel, rdma-core, Wireshark) and public RFCs. No proprietary specification text has been reproduced. IBTA, IEEE, T11/INCITS, and other specification references are provided as citations for further reading — the explanatory content is original. If you believe any content inadvertently reproduces copyrighted material, please open an issue.