mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-08-27 12:30:13 +03:00
docs: add roadmap docs for planned features
Close GitHub issues and document as roadmaps instead: - #2731: user preferences API - #2732: server settings REST API - #2733: injection fault tracking - packet analysis: protocol-oriented analysis architecture
This commit is contained in:
YueGuobin
parent
a408148073
commit
6596011799
64
docs/gns3-copilot/injection-fault-tracking-roadmap.md
Normal file
64
docs/gns3-copilot/injection-fault-tracking-roadmap.md
Normal file
@ -0,0 +1,64 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
|
||||
# Injection Fault Tracking — Roadmap
|
||||
|
||||
## Problem
|
||||
|
||||
When using the AI Copilot in troubleshooting injection mode across multiple chat sessions within the same project, there is no mechanism to prevent the same fault from being injected repeatedly. Each new session starts with a clean slate, unaware of what faults have already been used. This leads to:
|
||||
|
||||
- Duplicate injection scenarios across different sessions
|
||||
- No visibility for instructors into which faults have been used
|
||||
- No record of which devices were affected or whether faults were resolved
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Track injected faults per chat session and feed the history into the LLM's system prompt as context, so the model actively avoids repeating scenarios.
|
||||
|
||||
### 1. Storage
|
||||
|
||||
The existing `chat_sessions` table has `metadata` and `stats` JSON columns. After each fault injection, the agent records:
|
||||
|
||||
```json
|
||||
// stored in chat_session.metadata
|
||||
{
|
||||
"injected_fault": {
|
||||
"fault_type": "injection_ospf",
|
||||
"issue_key": "ospf_hello_dead_mismatch",
|
||||
"issue_name": "OSPF Hello/Dead Interval Mismatch",
|
||||
"device": "R1",
|
||||
"severity": "major",
|
||||
"injected_at": "2026-05-11T23:00:00Z",
|
||||
"resolved": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Context Injection
|
||||
|
||||
When starting a new troubleshooting session, query all previous sessions for the project, filter by `copilot_mode = "troubleshooting_injection"`, extract `injected_fault` data, and inject a summary into the system prompt via a placeholder (similar to the existing `{{topology_info}}` mechanism):
|
||||
|
||||
```
|
||||
Previously injected faults in this project:
|
||||
1. OSPF Hello/Dead Interval Mismatch on R1 (2026-05-11) — resolved
|
||||
2. BGP Route Reflector misconfiguration on R3 (2026-05-10) — resolved
|
||||
|
||||
Select a fault that has NOT been used before.
|
||||
```
|
||||
|
||||
### 3. Prompt Update
|
||||
|
||||
The `troubleshooting_injection.md` prompt in the GNS3-Skills repository gains an `{{injection_history}}` placeholder, and the agent is instructed to choose a fault not in the history list.
|
||||
|
||||
## Status
|
||||
|
||||
- [ ] GNS3-Skills: add `{{injection_history}}` placeholder to `troubleshooting_injection.md`
|
||||
- [ ] gns3-server: implement injection fault recording in agent chat session flow
|
||||
- [ ] gns3-server: implement injection history query across sessions per project
|
||||
- [ ] gns3-server: inject history into system prompt via `context_manager.py`
|
||||
- [ ] gns3-server: add `exclude` parameter to `InjectionSkillsTool` for filtering used faults
|
||||
92
docs/gns3-copilot/packet-analysis-roadmap.md
Normal file
92
docs/gns3-copilot/packet-analysis-roadmap.md
Normal file
@ -0,0 +1,92 @@
|
||||
<!--
|
||||
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`
|
||||
67
docs/gns3-copilot/server-settings-api-roadmap.md
Normal file
67
docs/gns3-copilot/server-settings-api-roadmap.md
Normal file
@ -0,0 +1,67 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
|
||||
# Server Settings REST API — Roadmap
|
||||
|
||||
## Problem
|
||||
|
||||
Currently, `gns3_server.conf` can only be modified by directly editing the file on disk. There is no REST API endpoint to read or write server configuration, which prevents the Web UI from offering a settings page for server parameters.
|
||||
|
||||
## Proposed API
|
||||
|
||||
```
|
||||
GET /v3/settings → Return all current server settings
|
||||
PUT /v3/settings → Update and persist server settings
|
||||
```
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
**1. Add `save_config()` to `Config` class** (`gns3server/config.py`)
|
||||
|
||||
The `Config` class currently only reads configuration (via `read_config()` / `reload()`). A `save_config()` method is needed to serialize the in-memory `ServerConfig` pydantic model back to INI format and write it to disk.
|
||||
|
||||
Serialization details:
|
||||
- `bool` → `"True"` / `"False"` (configparser convention)
|
||||
- `SecretStr` → `get_secret_value()`
|
||||
- `Enum` → `.value`
|
||||
- `List[str]` → semi-colon for `additional_images_paths`, comma for `allowed_interfaces`
|
||||
- `None` → skip
|
||||
|
||||
**2. Add a settings getter/setter** to `Config` to allow programmatic updates to the in-memory settings.
|
||||
|
||||
**3. New route file** (`gns3server/api/routes/controller/settings.py`):
|
||||
|
||||
- `GET /v3/settings` — returns the full `ServerConfig` as JSON (pydantic automatically masks `SecretStr` fields as `"********"`)
|
||||
- `PUT /v3/settings` — accepts `ServerConfig`, merges existing secrets when placeholder values (`"********"`) are submitted, calls `save_config()`, and triggers runtime config update callbacks
|
||||
|
||||
Both endpoints require `get_current_active_user` for authentication.
|
||||
|
||||
**4. Register the new router** in `gns3server/api/routes/controller/__init__.py` under the `/settings` prefix.
|
||||
|
||||
### Security
|
||||
|
||||
- All settings endpoints require admin authentication (`get_current_active_user`)
|
||||
- `SecretStr` fields (`compute_password`, `default_admin_password`, `jwt_secret_key`) are masked in responses
|
||||
- On write, unchanged secrets are preserved via placeholder detection
|
||||
|
||||
### Related Files
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `gns3server/config.py` | Config singleton with `read_config()` / `reload()` |
|
||||
| `gns3server/schemas/config.py` | `ServerConfig` pydantic model with all 9 sub-models |
|
||||
| `gns3server/api/routes/controller/__init__.py` | Controller router mounting |
|
||||
| `gns3server/controller/__init__.py` | `Controller._update_config()` for runtime credential sync |
|
||||
|
||||
## Status
|
||||
|
||||
- [ ] gns3server/config.py: add `save_config()` method
|
||||
- [ ] gns3server/config.py: add settings getter/setter
|
||||
- [ ] gns3server/api/routes/controller/settings.py: new route file with GET and PUT endpoints
|
||||
- [ ] gns3server/api/routes/controller/__init__.py: register settings router under `/settings`
|
||||
- [ ] gns3server/api/routes/controller/controller.py: add notification emission on config change
|
||||
60
docs/gns3-copilot/user-preferences-api-roadmap.md
Normal file
60
docs/gns3-copilot/user-preferences-api-roadmap.md
Normal file
@ -0,0 +1,60 @@
|
||||
<!--
|
||||
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.
|
||||
|
||||
|
||||
# User Preferences API — Roadmap
|
||||
|
||||
## Problem
|
||||
|
||||
Currently, user-specific preferences (UI theme, language, AI Copilot settings, workspace layout, etc.) can only be stored in browser `localStorage`. This has several drawbacks:
|
||||
|
||||
1. **localStorage clearing** — clearing browser data or switching devices loses all settings
|
||||
2. **No cross-device sync** — users must reconfigure preferences on each device
|
||||
3. **No API access** — CLI tools and third-party clients cannot read/write preferences
|
||||
4. **Fragile persistence** — localStorage can be cleared by browser maintenance or incognito mode
|
||||
|
||||
## Proposed API
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v3/access/users/me/preferences` | Get all preferences for current user |
|
||||
| `PUT` | `/v3/access/users/me/preferences` | Merge preferences (top-level merge, not replace) |
|
||||
| `DELETE` | `/v3/access/users/me/preferences` | Clear all preferences |
|
||||
|
||||
### Storage
|
||||
|
||||
A `preferences` JSON column on the existing `users` table:
|
||||
|
||||
- Type: `JSON`, non-nullable, default `'{}'`
|
||||
- No schema enforcement — clients can store arbitrary key-value pairs
|
||||
- Examples: `{"theme": "dark", "language": "zh-CN", "copilot_default_mode": "teaching_assistant"}`
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
1. Add `preferences` JSON column to `User` ORM model
|
||||
2. Create Alembic migration
|
||||
3. Add `UserPreferencesUpdate` Pydantic schema with `extra="allow"`
|
||||
4. Add `get_user_preferences()` and `update_user_preferences()` to `UsersRepository`
|
||||
5. Add three endpoints to `users.py` router: `GET/PUT/DELETE /me/preferences`
|
||||
|
||||
### Related Files
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `gns3server/db/models/user.py` | User ORM model |
|
||||
| `gns3server/db/repositories/users.py` | UsersRepository with database operations |
|
||||
| `gns3server/api/routes/controller/users.py` | User API router |
|
||||
| `gns3server/schemas/` | Pydantic schemas |
|
||||
| `gns3server/db/versions/` | Alembic migrations |
|
||||
|
||||
## Status
|
||||
|
||||
- [ ] Add `preferences` JSON column to User ORM model
|
||||
- [ ] Create Alembic migration
|
||||
- [ ] Add `UserPreferencesUpdate` schema
|
||||
- [ ] Add repository methods
|
||||
- [ ] Add API endpoints to users.py router
|
||||
Loading…
x
Reference in New Issue
Block a user