mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-08-27 12:30:13 +03:00
docs: move packet analysis from roadmap to implemented
Rewrite the packet-analysis document based on actual code: protocol-oriented analysis with tshark, 40+ supported protocols, two-tool architecture (skills query + capture analysis), field validation, and hot reload support. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
YueGuobin
parent
fd08885d94
commit
c5a59acc40
182
docs/gns3-copilot/implemented/packet-analysis.md
Normal file
182
docs/gns3-copilot/implemented/packet-analysis.md
Normal file
@ -0,0 +1,182 @@
|
||||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
See LICENSE file for licensing information.
|
||||
-->
|
||||
|
||||
> This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
|
||||
|
||||
|
||||
# Protocol-Oriented Packet Analysis
|
||||
|
||||
## Overview
|
||||
|
||||
GNS3 Copilot provides protocol-oriented packet analysis that allows the AI assistant to diagnose network issues from live GNS3 captures. Protocol definitions (tshark fields, display filters, check rules) are stored as YAML files in the external GNS3-Skills repository and loaded into memory at startup.
|
||||
|
||||
The system exposes two LangChain tools: `PacketAnalysisSkillsTool` queries protocol definitions, and `PacketAnalysisTool` runs tshark against downloaded pcap files using the LLM-constructed arguments.
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "GNS3-Skills Repository"
|
||||
YAML[packet_analysis/*.yaml<br/>40+ protocol files]
|
||||
end
|
||||
|
||||
subgraph "GNS3 Server"
|
||||
SM[SkillsManager]
|
||||
SL[SkillsLoader]
|
||||
REG[PACKET_ANALYSIS_REGISTRY<br/>in-memory dict]
|
||||
SKILL[PacketAnalysisSkillsTool<br/>query protocol definitions]
|
||||
TOOL[PacketAnalysisTool<br/>run tshark on captures]
|
||||
end
|
||||
|
||||
subgraph "tshark"
|
||||
FIELDS["tshark -G fields"<br/>live field registry]
|
||||
CAP["tshark -r pcap"<br/>packet capture analysis]
|
||||
end
|
||||
|
||||
YAML -->|load at startup / reload| SL
|
||||
SL --> REG
|
||||
SM --> SL
|
||||
|
||||
SKILL -->|read protocol fields/filters| REG
|
||||
TOOL -->|validate -e fields| FIELDS
|
||||
TOOL -->|download pcap + run tshark| CAP
|
||||
```
|
||||
|
||||
## Supported Protocols
|
||||
|
||||
Definitions are loaded from `GNS3-Skills/packet_analysis/*.yaml`. The following protocol families are covered:
|
||||
|
||||
| Category | Protocols |
|
||||
|----------|-----------|
|
||||
| Network Layer | ip, ipv6, arp, icmp, icmpv6 |
|
||||
| Transport Layer | tcp, udp |
|
||||
| Data Link | ethernet, ppp, hdlc, frame_relay, vlan, isl, llc |
|
||||
| Routing | ospf, eigrp, rip, bgp, isis, pim, dvmrp |
|
||||
| Link Protocols | l2tp, lacp, pagp, udld |
|
||||
| Infrastructure | cdp, lldp, stp, vtp, dtp |
|
||||
| Management | snmp, telnet, ssh, radius, tacacs |
|
||||
| Application | dns, http, bootp, dhcp |
|
||||
| Tunneling / Security | gre, esp, ah, mpls, eapol, ssl, isakmp |
|
||||
| Miscellaneous | nbns, slarp, ocsp, wccp, auto_rp, loop |
|
||||
|
||||
Each protocol YAML contains:
|
||||
|
||||
```yaml
|
||||
name: "OSPF Packet Analysis"
|
||||
description: "Analyze OSPF routing protocol packets"
|
||||
protocol_key: "ospf"
|
||||
display_filter: "ospf"
|
||||
fields:
|
||||
- label: "Source IP"
|
||||
tshark_field: "ip.src"
|
||||
description: "Source IPv4 address"
|
||||
- label: "OSPF Message Type"
|
||||
tshark_field: "ospf.msg"
|
||||
description: "1=Hello, 2=DBD, 3=LSR, 4=LSU, 5=LSAck"
|
||||
filter_examples:
|
||||
- description: "Show OSPF Hello packets"
|
||||
filter: "ospf.msg == 1"
|
||||
checks:
|
||||
- name: hello_dead_mismatch
|
||||
severity: critical
|
||||
message: "Hello/Dead Interval mismatch between neighbors"
|
||||
```
|
||||
|
||||
## Analysis Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant LLM as LLM Agent
|
||||
participant SKILL as PacketAnalysisSkillsTool
|
||||
participant TOOL as PacketAnalysisTool
|
||||
participant tshark as tshark
|
||||
participant GNS3 as GNS3 Server
|
||||
|
||||
LLM->>SKILL: {"action": "list"}
|
||||
SKILL-->>LLM: Available protocols
|
||||
|
||||
LLM->>SKILL: {"action": "get", "protocol": "ospf"}
|
||||
SKILL-->>LLM: Fields, filters, check rules
|
||||
|
||||
Note over LLM: LLM constructs tshark_args<br/>using protocol knowledge
|
||||
|
||||
LLM->>TOOL: {project_id, link_id,<br/>tshark_args: "-Y ospf -T fields -e ip.src -e ospf.msg"}
|
||||
TOOL->>TOOL: Validate -e field names<br/>against tshark -G fields
|
||||
TOOL->>GNS3: Download pcap for link_id
|
||||
GNS3-->>TOOL: Capture file
|
||||
TOOL->>tshark: tshark -r pcap -Y ospf -T fields -e ip.src -e ospf.msg
|
||||
tshark-->>TOOL: Tab-separated output
|
||||
TOOL-->>LLM: Raw tshark output
|
||||
```
|
||||
|
||||
## Tool Registration
|
||||
|
||||
The packet analysis tools are available in two copilot modes:
|
||||
|
||||
| Tool | Teaching Assistant | Lab Automation | Troubleshooting Injection |
|
||||
|------|:------------------:|:--------------:|:-------------------------:|
|
||||
| `PacketAnalysisTool` | Yes | Yes | No |
|
||||
| `PacketAnalysisSkillsTool` | Yes | Yes | No |
|
||||
|
||||
## Tool Interface
|
||||
|
||||
### PacketAnalysisSkillsTool (`packet_analysis_skills`)
|
||||
|
||||
Queries protocol definitions from the `PACKET_ANALYSIS_REGISTRY`. Used before running tshark to look up valid field names, display filters, and anomaly checks.
|
||||
|
||||
| Action | Input | Output |
|
||||
|--------|-------|--------|
|
||||
| List protocols | `{"action": "list"}` | `{count, protocols: [{protocol, name, description}]}` |
|
||||
| Get protocol | `{"action": "get", "protocol": "ospf"}` | Protocol definition with fields, filters, checks |
|
||||
|
||||
### PacketAnalysisTool (`packet_analysis`)
|
||||
|
||||
Runs tshark against a downloaded GNS3 capture file. Supports two modes:
|
||||
|
||||
**Capture analysis mode:**
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `project_id` | Yes | UUID of the GNS3 project |
|
||||
| `link_id` | Yes | UUID of the link to analyze |
|
||||
| `tshark_args` | Yes | tshark arguments (after `-r <pcap>`) |
|
||||
|
||||
**Field search mode:**
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `action` | Yes | `"search_fields"` |
|
||||
| `query` | Yes | Single keyword (e.g., `"ospf.lsa"`, `"bgp.open"`) |
|
||||
|
||||
### Validation and Error Handling
|
||||
|
||||
Before downloading the capture, the tool validates `-e` field names against the live tshark field registry (`tshark -G fields`). Invalid field names are rejected early with a hint to use `search_fields`.
|
||||
|
||||
| Scenario | Response |
|
||||
|----------|----------|
|
||||
| Invalid `-e` field name | `{error, hint, invalid_fields}` |
|
||||
| tshark filter/field error | `{error: "tshark argument error", hints}` |
|
||||
| Empty capture file | `{error: "Capture file is empty"}` |
|
||||
| No matching packets | `{result: "No matching packets found", hints}` |
|
||||
| tshark timeout (30s) | `{error: "tshark timeout after 30 seconds"}` |
|
||||
| tshark not installed | `{error: "tshark not installed"}` |
|
||||
|
||||
When `-c` is used and no results are found, the tool hints that `-c` limits total packets read (not matched count), and suggests removing it or piping to `head`.
|
||||
|
||||
## Hot Reload
|
||||
|
||||
Packet analysis protocols can be reloaded without restarting the server via the existing reload API:
|
||||
|
||||
```
|
||||
POST /v3/copilot/reload/skills
|
||||
```
|
||||
|
||||
This triggers `SkillsManager.reload_packet_analysis_protocols()`, which re-reads all YAML files from the `packet_analysis/` directory and updates `PACKET_ANALYSIS_REGISTRY` in place.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [External Skills Repository](skills-repository.md)
|
||||
- [Fault Injection](fault-injection.md)
|
||||
- [Chat API](chat-api.md)
|
||||
@ -1,92 +0,0 @@
|
||||
<!--
|
||||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
See LICENSE file for licensing information.
|
||||
-->
|
||||
|
||||
> This document is a roadmap/planning document. The described features have not been implemented yet.
|
||||
|
||||
|
||||
# Protocol-Oriented Packet Analysis — Roadmap
|
||||
|
||||
## Problem
|
||||
|
||||
The current `PacketCaptureTool` (`analyze_packets`) only accepts a single `packet_number` parameter and runs `tshark -V` on that one frame. This approach:
|
||||
|
||||
- Forces the LLM to guess packet numbers without any visibility into the capture
|
||||
- Returns raw verbose output instead of structured data
|
||||
- Has no protocol awareness — every protocol looks the same to the tool
|
||||
- Provides no built-in anomaly detection; the LLM must infer issues from raw output each time
|
||||
- Downloads the same pcap from the server on every call (no caching)
|
||||
|
||||
## Proposed Architecture
|
||||
|
||||
Move from number-based to **protocol-oriented** packet analysis. Protocol definitions (fields, display filters, anomaly checks) are stored as YAML files in the GNS3-Skills repository. The tool only needs `link_id` + `protocol` — no complex parameters for the LLM to get wrong.
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
GNS3-Skills/packet_analysis/<protocol>.yaml
|
||||
│
|
||||
▼ loaded at startup / reload
|
||||
PACKET_ANALYSIS_REGISTRY (in-memory dict)
|
||||
│
|
||||
▼
|
||||
PacketAnalysisTool(link_id, protocol)
|
||||
│
|
||||
├── download pcap (with link_id caching)
|
||||
├── tshark -T fields -e <predefined fields>
|
||||
├── run anomaly checks from YAML
|
||||
└── return structured JSON + check results
|
||||
│
|
||||
▼
|
||||
LLM produces natural language explanation
|
||||
```
|
||||
|
||||
### YAML Format
|
||||
|
||||
```yaml
|
||||
name: "OSPF Packet Analysis"
|
||||
protocol: "ospf"
|
||||
display_filter: "ospf"
|
||||
fields:
|
||||
- label: "Source IP"
|
||||
field: "ip.src"
|
||||
description: "Source IPv4 address"
|
||||
- label: "OSPF Message Type"
|
||||
field: "ospf.msg"
|
||||
description: "1=Hello, 2=DBD, 3=LSR, 4=LSU, 5=LSAck"
|
||||
checks:
|
||||
- name: hello_dead_mismatch
|
||||
severity: critical
|
||||
message: "Hello/Dead Interval mismatch between {src} and {dst}"
|
||||
condition: "Same broadcast domain has inconsistent hello/dead intervals"
|
||||
```
|
||||
|
||||
### Planned Protocols
|
||||
|
||||
| File | Protocols | Key Checks |
|
||||
|------|-----------|------------|
|
||||
| `arp.yaml` | ARP, NDP (ICMPv6 NS/NA) | Duplicate IP, no ARP reply, ARP flooding |
|
||||
| `icmp.yaml` | ICMPv4, ICMPv6 | Unreachable classification, ping loss, PMTUD issues |
|
||||
| `ospf.yaml` | OSPFv2, OSPFv3 | Hello/Dead mismatch, Area ID mismatch, Router ID conflict |
|
||||
| `bgp.yaml` | BGPv4, BGP+ | Hold timer mismatch, Notification analysis, AS_PATH loop |
|
||||
|
||||
### Tool Interface
|
||||
|
||||
```json
|
||||
{
|
||||
"link_id": "uuid (required)",
|
||||
"protocol": "arp | icmp | ospf | bgp (required)",
|
||||
"summary_only": "bool (optional, default: false)"
|
||||
}
|
||||
```
|
||||
|
||||
## Status
|
||||
|
||||
- [ ] GNS3-Skills: create `packet_analysis/` directory and YAML definitions
|
||||
- [ ] gns3-server: add `PACKET_ANALYSIS_REGISTRY` loading from skills repo
|
||||
- [ ] gns3-server: implement `PacketAnalysisTool` with tshark field extraction
|
||||
- [ ] gns3-server: implement protocol-specific anomaly checks
|
||||
- [ ] gns3-server: add pcap caching by `link_id`
|
||||
- [ ] gns3-server: register tool in teaching assistant and lab automation modes
|
||||
- [ ] gns3-server: deprecate and remove old `PacketCaptureTool`
|
||||
Loading…
x
Reference in New Issue
Block a user