gns3-server/docs/gns3-copilot/command-security.md

Command Security Configuration

Overview

GNS3-Copilot includes a command filtering system to prevent execution of commands that may cause timeout or console availability issues in the lab environment. This helps:

• Prevent tool timeouts: Commands like traceroute may run longer than the tool timeout
• Maintain console availability: Long-running commands can leave the device console unavailable for subsequent commands
• Ensure reliable execution: Filtering problematic commands ensures the remaining commands can execute properly

Implementation Status

Status: ✅ Implemented and Verified

The command filtering system is fully implemented and has been tested in a live GNS3 environment with actual network devices. Key features:

• ✅ Simple text-based configuration file
• ✅ Substring matching (case-insensitive)
• ✅ Non-blocking filtering (allowed commands execute normally)
• ✅ Detailed blocking feedback in tool results
• ✅ Multi-device support
• ✅ Verified with real Cisco IOS devices

See the Implementation Verification section for actual test results.

Problem Context

Why Filter Commands?

When GNS3-Copilot tools execute commands on network devices using Nornir/Netmiko, there is a timeout limit (typically 30-60 seconds). If a command exceeds this timeout:

1. The tool stops waiting and returns a timeout error
2. The device console may still be executing the command
3. Subsequent commands sent to the device fail or produce incorrect results
4. The user may need to manually interrupt the command on the device console

Example Scenario

Time    Agent Action                    Device Console Status
t0      Execute: traceroute 8.8.8.8     [Command starts]
t1      ...waiting...                   [Tracing...]
t2      ...waiting...                   [Tracing...]
t30     Timeout! Proceed to next tool   [Still tracing!]
t31     Execute: show ip route           [Ignored or corrupted]
t32     ❌ Command fails                [Console still busy]

Current Implementation

Forbidden Commands List

Commands are listed in a simple text file at:

gns3server/agent/gns3_copilot/config/forbidden_commands.txt

Format:

• One command pattern per line
• Simple substring matching (case-insensitive)
• Empty lines and lines starting with # are ignored
• Match is performed on the beginning of each command

Example:

# Network diagnostic commands that may timeout
traceroute
tracepath
tracert

# Debug commands that may destabilize devices
debug

# Test commands that may affect device stability
test

Filter Behavior

1. Input Commands: ["show version", "traceroute 8.8.8.8", "show ip int brief"]
2. Filtering: traceroute 8.8.8.8 is removed (matches traceroute)
3. Executed: ["show version", "show ip int brief"]
4. Result: Returns successful output with blocked command information

Result Format

When commands are filtered, the result includes additional fields:

{
    "device_name": "R-1",
    "status": "partial_success",
    "output": "R-1#show version\nCisco IOS Software...\nR-1#show ip int brief\nInterface...",
    "diagnostic_commands": ["show version", "show ip int brief"],
    "blocked_commands": ["traceroute 8.8.8.8"],
    "blocked_info": {
        "traceroute 8.8.8.8": "Command 'traceroute 8.8.8.8' is not allowed because it matches the forbidden pattern 'traceroute'. This command may run longer than the tool timeout or leave the device console unavailable for subsequent commands."
    }
}

Status values:

• "success": All commands executed successfully
• "partial_success": Some commands were blocked, but remaining commands executed successfully
• "failed": Command execution failed (device not found, connection error, etc.)

Module Structure

Command Filter Module

File: gns3server/agent/gns3_copilot/utils/command_filter.py

Functions:

• filter_forbidden_commands(commands: list[str]) -> tuple[list[str], dict[str, str]]
  • Returns allowed commands and blocked command information
• is_command_forbidden(command: str) -> bool
  • Check if a single command is forbidden
• get_forbidden_commands() -> list[str]
  • Get the current list of forbidden patterns
• reload_forbidden_commands() -> None
  • Reload the forbidden commands list (useful after editing the file)

Integration Points

The filter is integrated into:

• Display Tools (display_tools_nornir.py): ExecuteMultipleDeviceCommands
• Configuration Tools (config_tools_nornir.py): ExecuteMultipleDeviceConfigCommands

Both tools use the same filtering logic and return format.

Configuration

Default Forbidden Commands

If the configuration file is not found, these defaults are used:

• traceroute
• tracepath
• tracert
• ping -f
• debug
• test

Customizing the List

To add or remove forbidden commands:

1. Edit the configuration file:

   nano gns3server/agent/gns3_copilot/config/forbidden_commands.txt
   

2. Add your command patterns (one per line):

   # My custom blocked commands
   my_dangerous_command
   another_pattern
   

3. Restart GNS3 server to apply changes

Reloading Without Restart

To reload the forbidden commands list without restarting the server:

from gns3server.agent.gns3_copilot.utils.command_filter import reload_forbidden_commands
reload_forbidden_commands()

Usage Examples

Example 1: All Commands Allowed

Input:

{
    "project_id": "abc-123-def",
    "device_configs": [
        {
            "device_name": "R-1",
            "commands": ["show version", "show ip route"]
        }
    ]
}

Output:

{
    "device_name": "R-1",
    "status": "success",
    "output": "...",
    "diagnostic_commands": ["show version", "show ip route"]
}

Example 2: Some Commands Blocked

Input:

{
    "project_id": "abc-123-def",
    "device_configs": [
        {
            "device_name": "R-1",
            "commands": ["show version", "traceroute 8.8.8.8", "show ip route"]
        }
    ]
}

Output:

{
    "device_name": "R-1",
    "status": "partial_success",
    "output": "...",
    "diagnostic_commands": ["show version", "show ip route"],
    "blocked_commands": ["traceroute 8.8.8.8"],
    "blocked_info": {
        "traceroute 8.8.8.8": "Command 'traceroute 8.8.8.8' is not allowed because it matches the forbidden pattern 'traceroute'. This command may run longer than the tool timeout or leave the device console unavailable for subsequent commands."
    }
}

Example 3: All Commands Blocked

Input:

{
    "project_id": "abc-123-def",
    "device_configs": [
        {
            "device_name": "R-1",
            "commands": ["traceroute 8.8.8.8", "debug ip routing"]
        }
    ]
}

Output:

{
    "device_name": "R-1",
    "status": "success",
    "output": "",
    "diagnostic_commands": [],
    "blocked_commands": ["traceroute 8.8.8.8", "debug ip routing"],
    "blocked_info": {
        "traceroute 8.8.8.8": "Command 'traceroute 8.8.8.8' is not allowed because it matches the forbidden pattern 'traceroute'. This command may run longer than the tool timeout or leave the device console unavailable for subsequent commands.",
        "debug ip routing": "Command 'debug ip routing' is not allowed because it matches the forbidden pattern 'debug'. This command may run longer than the tool timeout or leave the device console unavailable for subsequent commands."
    }
}

Implementation Verification

Real-World Test Results

The command filtering system has been tested in a live GNS3 environment with actual network devices. Below are actual execution results:

Test Scenario:

• Devices: IOU-L2-1, IOU-L2-2 (Cisco IOS Layer 3 switches)
• Commands: Mixed allowed and forbidden commands
• Forbidden pattern: traceroute

Actual Output:

{
  "device_name": "IOU-L2-1",
  "status": "partial_success",
  "diagnostic_commands": [
    "show ip route",
    "show ip interface brief",
    "ping 10.0.0.1",
    "ping 10.0.0.2",
    "ping 10.0.0.4"
  ],
  "blocked_commands": ["traceroute 10.0.0.2"],
  "blocked_info": {
    "traceroute 10.0.0.2": "Command 'traceroute 10.0.0.2' is not allowed because it matches the forbidden pattern 'traceroute'. This command may run longer than the tool timeout or leave the device console unavailable for subsequent commands."
  }
}

Key Observations:

1. ✅ traceroute command was successfully filtered
2. ✅ All other commands (show, ping) executed normally
3. ✅ Status correctly set to partial_success
4. ✅ Both diagnostic_commands (executed) and blocked_commands (filtered) are clearly listed
5. ✅ Detailed blocking reason provided in blocked_info
6. ✅ Tool execution continued without timeout or console lockup issues

Functionality Verification Matrix

Feature	Status	Notes
Command filtering (substring match)	✅ Verified	traceroute correctly matched and blocked
Partial execution	✅ Verified	Other commands executed successfully
Return format consistency	✅ Verified	Contains all expected fields
Multi-device support	✅ Verified	Each device filtered independently
Error messages	✅ Verified	Clear, informative blocking reasons
Status field accuracy	✅ Verified	partial_success set correctly
Non-blocking behavior	✅ Verified	No tool timeouts or console issues

Benefits Confirmed

1. Timeout Prevention: The traceroute command that could have taken 30+ seconds was filtered, preventing tool timeout
2. Console Availability: Since traceroute was not executed, the device console remained available for subsequent commands
3. Clear Feedback: The LLM receives clear information about which commands were blocked and why
4. Partial Execution: Useful commands (show, ping) still executed, providing valuable diagnostic information

Future Enhancements (TODO)

Planned Improvements

1. Regex Support: Allow more sophisticated pattern matching

   # Current: simple substring match
   "traceroute"
   
   # Future: regex patterns
   "^traceroute\\s+"
   "ping\\s+.*\\s+-f"
   

2. User Override File: Allow per-project or user-specific overrides

   /etc/gns3-server/forbidden_commands_override.txt
   <project_dir>/forbidden_commands_override.txt
   

3. Web UI Configuration: Manage forbidden commands through GNS3 web interface

4. Audit Logging: Log blocked commands for security analysis

5. Per-Command Timeouts: Configure timeouts for specific commands instead of blocking

   "command_timeouts": {
       "traceroute.*": 120,
       "debug.*": 5
   }
   

6. Interrupt Mechanism: Send Ctrl+C to interrupt long-running commands instead of blocking

   def execute_with_timeout(cmd, timeout=30):
       try:
           return device.execute(cmd, timeout=timeout)
       except Timeout:
           device.send_break()  # Ctrl+C
           return f"Command interrupted after {timeout}s"
   

7. Command State Tracking: Track device console state to ensure availability

   device_state = {
       "console_available": True,
       "current_command": None,
       "last_prompt_seen": timestamp
   }
   

Advanced Features (Long-term)

• Per-Device Filtering: Different rules for different device types
• Time-Based Restrictions: Block certain commands during specific hours
• Severity Levels: Classify commands by severity (warn, block, allow)
• ML-Based Detection: Learn which commands cause problems and auto-block them

Troubleshooting

Commands Are Being Blocked Unexpectedly

Problem: A command you want to use is being blocked.

Solution:

1. Check the blocked command list in the result output
2. Identify which pattern is matching your command
3. Edit forbidden_commands.txt to remove or modify the pattern
4. Restart GNS3 server

Forbidden Commands File Not Found

Problem: The system logs "Forbidden commands file not found. Using default list."

Solution:

1. Verify the file exists at the expected location
2. Check file permissions (should be readable by the GNS3 server process)
3. Ensure the file is not empty

Changes Not Taking Effect

Problem: You edited the file but commands are still being blocked.

Solution:

1. Restart the GNS3 server (required to reload the configuration)
2. Or use the reload_forbidden_commands() function if available in your context

Security Considerations

Why These Commands Are Blocked

Command	Reason
traceroute	Can run for 30+ seconds, exceeds typical tool timeout
tracepath	Similar to traceroute, long execution time
tracert	Windows traceroute, same timeout issues
ping -f	Flood ping can overwhelm lab devices
debug	Debug commands can produce overwhelming output and destabilize devices
test	Test commands may affect device stability

Best Practices

1. Education Environment: Use the default filtering for safety
2. Personal Lab: Consider which commands you actually need
3. Production-like Environment: Keep restrictions enabled
4. Always Understand: Before allowing a command, understand why it was blocked

Related Documentation

• Tool Implementation
• GNS3-Copilot Documentation
• Contributing Guide

Feedback and Issues

If you:

• Find commands that should be blocked by default
• Need to allow commands for legitimate use cases
• Have suggestions for improving the filtering system

Please submit an issue: https://github.com/yueguobin/gns3-copilot/issues

---

License

Copyright © 2025 Yue Guobin (岳国宾)

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).

Summary

You are free to:

• Share — Copy and redistribute the material in any medium or format
• Adapt — Remix, transform, and build upon the material for any purpose

Under the following terms:

• Attribution — You must give appropriate credit to Yue Guobin (岳国宾), provide a link to the license, and indicate if changes were made.
• ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license (CC BY-SA 4.0).

Full license text: DESIGN_DOCS_LICENSE