# sonic-net-debugger

An MCP (Model Context Protocol) server for debugging and interacting with SONiC (Software for Open Networking in the Cloud) network devices (DUTs).

## Features

- **CLI Command Execution**: Execute SONiC utility commands (like `show pfc wd stats`, `show interfaces status`, etc.) directly on the device via SSH.
- **Redis Querying**: Access the SONiC Redis databases (APPL_DB, ASIC_DB, STATE_DB, etc.) to inspect internal switch states.
- **Documentation Retrieval**: Built-in access to the SONiC Command Reference, allowing AI to lookup exact syntaxes for complex commands. The server will **automatically download** the documentation from the official GitHub repository on its first run.
- **Dynamic Device Targeting & Smart Authentication**: 
  - Supports passing target IP, username, and password dynamically per request.
  - **Auto-Fallback Credential Testing**: If no credentials are provided during the request, the server will automatically cycle through a list of default lab passwords (loaded from `config.json`) using a Cartesian product (matching every username with every password) until it successfully connects.
  - **Smart Credential Caching**: Successfully authenticated IP, Username, and Password combinations are temporarily cached locally (`.ssh_cache.json`). Subsequent commands to the same device will instantly use the cached credentials, bypassing the credential permutations to significantly speed up execution.

## Requirements

- Python 3.10+
- `fastmcp`
- `paramiko`

## Installation

```bash
pip install -r requirements.txt
```

## Configuration

This MCP server communicates over standard input/output (stdio) and uses SSH to connect to the SONiC switch. 

### 1. Environment Variables (Primary Device)
You can provide default environment variables. These will be attempted *first* before falling back to common default passwords.

- `SONIC_HOST`: The default IP address or hostname of the switch (e.g., `10.110.199.18`).
- `SONIC_USER`: Your specific SSH username.
- `SONIC_PASS`: Your specific SSH password.

### 2. Credential Permutations (`config.json`)
To avoid hardcoding lab passwords into the script, the tool will automatically generate a `config.json` file in its root directory upon first execution. You can populate this file with common usernames and passwords used in your network lab:

```json
{
    "usernames": [
        "admin",
        "root"
    ],
    "passwords": [
        "YourPassword",
        "admin",
        "password",
        "123456",
        "root"
    ]
}
```
*Note: `config.json`, `.ssh_cache.json` and downloaded `.md` files are added to `.gitignore` to prevent accidental credential leaks.*

### Example configuration for Claude Desktop or Cursor:

```json
{
  "mcpServers": {
    "sonic-net-debugger": {
      "command": "python",
      "args": ["/path/to/sonic-net-debugger/sonic_net_debugger.py"],
      "env": {
        "SONIC_HOST": "10.110.199.18"
      }
    }
  }
}
```

## Available Tools

- `sonic_exec_cmd(command, host, username, password)`: Execute a CLI command on the device via SSH.
- `sonic_lookup_doc(keyword)`: Search the local SONiC command reference markdown file.
- `sonic_query_redis(db_index, pattern, host, username, password)`: Query Redis keys using `redis-cli KEYS`.
- `sonic_get_redis_hash(db_index, key, host, username, password)`: Get all fields and values of a specific Redis HASH key.

*(Note: `host`, `username`, and `password` are optional parameters. If omitted, the server handles connection and authentication automatically using environment variables, cache, and `config.json`.)*