gns3-server/docs/gns3-copilot/implemented/fault-injection-overview.en.md

GNS3-Copilot Fault Injection Overview

Core Flow

flowchart TB
    subgraph "① API Trigger & Mode Switch"
        A["POST /chat/inject\nUser requests fault injection"] --> B["Verify project is opened"]
        B --> C["Set copilot_mode =\ntroubleshooting_injection"]
        C --> D["Start Agent\nwith fault injection tool set"]
    end

    subgraph "② Topology Analysis & Fault Selection"
        D --> E["GNS3TopologyTool\nget topology info"]
        E --> F["ExecuteMultipleDeviceCommands\nget device configs"]
        F --> G["InjectionSkillsTool\nquery available fault types"]
        G --> H{"Injection Skills Repository\ngns3/gns3-skills"}
        H --> I["Return matching fault definitions\nwith config injection commands"]
    end

    subgraph "③ Fault Injection"
        I --> J["Choose injection method"]
        J --> K["ExecuteMultipleDeviceConfigCommands\ninject config changes"]
        J --> L["GNS3PacketFilterTool\ninject link-layer faults"]
    end

    subgraph "④ Result Confirmation"
        K --> M["Verify fault is active"]
        L --> M
        M --> N["Document fault details\nincluding restore commands"]
    end

Tool Overview

Tool	Source File	Purpose	Available Modes
InjectionSkillsTool	registry.py (skills module)	Query protocol-level fault definitions (config change commands)	troubleshooting_injection
GNS3PacketFilterTool	gns3_packet_filter.py	Link-layer fault injection (delay, loss, corruption, BPF)	troubleshooting_injection
ExecuteMultipleDeviceConfigCommands	config_tools_nornir.py	Batch device config changes	troubleshooting_injection
ExecuteMultipleDeviceCommands	display_tools_nornir.py	Read device configurations (read-only)	troubleshooting_injection
GNS3TopologyTool	gns3_client	Get project topology information	troubleshooting_injection

Fault Injection API

Endpoint	Function
POST /v3/projects/{pid}/chat/inject	Trigger fault injection, sets troubleshooting_injection mode then starts Agent

Prerequisite: Project must be in opened status, otherwise returns 403.

GNS3PacketFilterTool Link Filters

Filter Type	Function	Parameters
delay	Latency + jitter	[latency(0-32767), jitter(0-32767)]
packet_loss	Packet loss percentage	[chance(0-100)]
corrupt	Packet corruption percentage	[chance(0-100)]
frequency_drop	Drop every Nth packet	[frequency(-1~32767)]
bpf	Berkeley Packet Filter	expression text

Agent Workflow (LangGraph)

sequenceDiagram
    participant U as User
    participant API as POST /chat/inject
    participant LLM as LLM Node
    participant Topo as GNS3TopologyTool
    participant DC as ExecuteMultipleDeviceCommands
    participant CC as ExecuteMultipleDeviceConfigCommands
    participant Skill as InjectionSkillsTool
    participant Filter as GNS3PacketFilterTool

    U->>API: Inject an OSPF fault
    API->>LLM: set mode=troubleshooting_injection
    LLM->>Topo: get topology
    Topo-->>LLM: topology info
    LLM->>DC: read device configs
    DC-->>LLM: running configs
    LLM->>Skill: list context=["ospf"]
    Skill-->>LLM: matching fault types
    LLM->>Skill: get device_type=injection_ospf
    Skill-->>LLM: fault definition + injection commands
    LLM->>CC: execute config injection
    CC-->>LLM: injection result
    LLM->>Filter: set filters={delay:[200,50]}
    Filter-->>LLM: link delay injected successfully
    LLM-->>U: Fault injected, restore commands included

Key Design Points

1. Dedicated API Endpoint — POST /chat/inject is the dedicated entry point, automatically switching to troubleshooting_injection mode
2. LLM-driven Fault Selection — The LLM analyzes the topology then queries matching faults via InjectionSkillsTool; no hardcoded fault scenarios
3. Dual-Layer Injection — Device-level config changes + link-level network impairment, covering complete troubleshooting scenarios
4. Fully Reversible — Every injection includes restore commands; link filters can be cleared with action: clear
5. Safety First — BPF syntax is pre-validated via tshark; config commands are restricted by command_filter
6. Context Filtering — InjectionSkillsTool requires a context parameter, returning only faults matching the topology protocols