@teamnetwork-nz/sonicwall-api-mcp-server 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +40 -0
- package/README.md +239 -186
- package/dist/index.js +30 -1
- package/dist/strict-tools.js +30 -1
- package/package.json +53 -52
package/.env.example
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Sanitised template: no live credentials or identities.
|
|
2
|
+
# See README.md for requirements, defaults and .env loading behaviour.
|
|
3
|
+
# Replace required/alternative placeholders privately; uncomment optional settings only when needed.
|
|
4
|
+
|
|
5
|
+
# Private JSON device-profile array; replaces single-device credentials and settings, including per-profile read_only.
|
|
6
|
+
# SONICWALL_DEVICES_FILE=<set-privately>
|
|
7
|
+
# Local name for the single-device profile.
|
|
8
|
+
# SONICWALL_DEVICE_NAME=default
|
|
9
|
+
# Firewall hostname; required unless SONICWALL_DEVICES_FILE is set.
|
|
10
|
+
SONICWALL_HOST=<set-privately>
|
|
11
|
+
# Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener.
|
|
12
|
+
# SONICWALL_HTTP_ALLOWED_HOSTS=<set-privately>
|
|
13
|
+
# Comma-separated browser Origin allowlist; configure when browser clients need access.
|
|
14
|
+
# SONICWALL_HTTP_ALLOWED_ORIGINS=<set-privately>
|
|
15
|
+
# Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>.
|
|
16
|
+
# SONICWALL_HTTP_BEARER_TOKEN=<set-privately>
|
|
17
|
+
# Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts.
|
|
18
|
+
# SONICWALL_HTTP_HOST=127.0.0.1
|
|
19
|
+
# Maximum HTTP request body; integer 1–16777216 bytes.
|
|
20
|
+
# SONICWALL_HTTP_MAX_BODY_BYTES=1048576
|
|
21
|
+
# HTTP listener port; integer 1–65535.
|
|
22
|
+
# SONICWALL_HTTP_PORT=3000
|
|
23
|
+
# Firewall API password; required in single-device mode.
|
|
24
|
+
SONICWALL_PASSWORD=<set-privately>
|
|
25
|
+
# Firewall HTTPS port; integer 1–65535.
|
|
26
|
+
# SONICWALL_PORT=443
|
|
27
|
+
# Only true enables mutation tools; read-only is the default. Review each operation before use. Applies to single-device mode; JSON profiles use read_only.
|
|
28
|
+
# SONICWALL_READWRITE=false
|
|
29
|
+
# Compatibility alias: false enables writes only when SONICWALL_READWRITE is unset; single-device mode only.
|
|
30
|
+
# SONICWALL_READ_ONLY=<set-privately>
|
|
31
|
+
# Firewall request timeout; integer 1–300 seconds.
|
|
32
|
+
# SONICWALL_REQUEST_TIMEOUT=30
|
|
33
|
+
# Parsed compatibility setting, integer 1–65535; does not start an SSE listener. Use HTTP_PORT for Streamable HTTP.
|
|
34
|
+
# SONICWALL_SSE_PORT=8000
|
|
35
|
+
# false disables TLS verification globally if any profile disables it; retain true.
|
|
36
|
+
# SONICWALL_SSL_VERIFY=true
|
|
37
|
+
# stdio or http; HTTP serves /mcp and GET /health.
|
|
38
|
+
# SONICWALL_TRANSPORT=stdio
|
|
39
|
+
# Firewall API username; required in single-device mode.
|
|
40
|
+
SONICWALL_USERNAME=<set-privately>
|
package/README.md
CHANGED
|
@@ -1,189 +1,242 @@
|
|
|
1
|
-
# SonicWall NSA MCP Server
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
1
|
+
# SonicWall NSA MCP Server
|
|
2
|
+
|
|
3
|
+
Both TypeScript and Python tools accept optional `outputFormat: "json"` for client consistency. The TypeScript server returns valid JSON text when requested; the Python server already returns structured data that FastMCP serializes as JSON. In both implementations the option is handled locally and is never sent to the SonicWall appliance.
|
|
4
|
+
|
|
5
|
+
## Streamable HTTP
|
|
6
|
+
|
|
7
|
+
Set `SONICWALL_TRANSPORT=http` to serve stateless MCP at `/mcp`. It binds to `127.0.0.1` by default; remote binding requires `SONICWALL_HTTP_BEARER_TOKEN` and `SONICWALL_HTTP_ALLOWED_HOSTS`. Optional controls include `SONICWALL_HTTP_PORT`, `SONICWALL_HTTP_ALLOWED_ORIGINS`, and `SONICWALL_HTTP_MAX_BODY_BYTES`; `/health` is available for health checks.
|
|
8
|
+
|
|
9
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) server that provides full read/write access to SonicWall NSA series appliances via the SonicOS REST API.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
11
13
|
- **Log configuration** — inspect log categories and event-definition settings (not runtime event history)
|
|
12
|
-
- **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
|
|
13
|
-
- **Service objects & groups** — CRUD for protocol/port service definitions
|
|
14
|
-
- **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
|
|
15
|
-
- **NAT policies** — full CRUD for inbound/outbound NAT rules
|
|
16
|
-
- **Security policies** — CRUD for zone-based security policies
|
|
17
|
-
- **Network discovery** — list zones, interfaces, schedules, and route policies (read-only)
|
|
18
|
-
- **Appliance diagnostics** — network-path lookup, ARP cache, ping, traceroute, and combined IP diagnosis (read-only)
|
|
19
|
-
- **GeoIP lookup** — identify the country/botnet classification of an IP address
|
|
20
|
-
- **Config management** — view and commit (or discard) staged changes
|
|
21
|
-
|
|
14
|
+
- **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
|
|
15
|
+
- **Service objects & groups** — CRUD for protocol/port service definitions
|
|
16
|
+
- **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
|
|
17
|
+
- **NAT policies** — full CRUD for inbound/outbound NAT rules
|
|
18
|
+
- **Security policies** — CRUD for zone-based security policies
|
|
19
|
+
- **Network discovery** — list zones, interfaces, schedules, and route policies (read-only)
|
|
20
|
+
- **Appliance diagnostics** — network-path lookup, ARP cache, ping, traceroute, and combined IP diagnosis (read-only)
|
|
21
|
+
- **GeoIP lookup** — identify the country/botnet classification of an IP address
|
|
22
|
+
- **Config management** — view and commit (or discard) staged changes
|
|
23
|
+
|
|
22
24
|
> The SonicOS REST API is configuration-focused. Runtime event/threat/connection logs and GeoIP *policy* objects are not exposed as REST endpoints and therefore have no tools. `get_log_categories` and `list_log_event_definitions` inspect logging configuration only.
|
|
23
|
-
|
|
24
|
-
### Diagnosing an unreachable IP
|
|
25
|
-
|
|
26
|
-
Use `diagnose_ip` for a combined report containing the appliance's selected network path, configured interfaces and route policies, matching ARP entry, ping result, and traceroute. Set `interface` to force the live tests through an interface such as `X1`, or set `include_traceroute=false` for a faster check. The focused tools `find_network_path`, `lookup_arp`, `ping_from_appliance`, and `traceroute_from_appliance` are also available. Diagnostic POST actions are read-only and work without enabling `SONICWALL_READWRITE`.
|
|
27
|
-
|
|
28
|
-
Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
|
|
29
|
-
|
|
30
|
-
## Quick Start
|
|
31
|
-
|
|
32
|
-
### Prerequisites
|
|
33
|
-
|
|
34
|
-
- A SonicWall NSA appliance running SonicOS 6.5, 7.x, or 8.x
|
|
35
|
-
- SonicOS API enabled: **Device › Settings › Administration › SonicOS API** — toggle **SonicOS API** on, and ensure **RFC-2617 HTTP Basic Access authentication** is also enabled (the MCP server uses Basic auth to obtain a session token, falling back to RFC-7616 Digest if Basic is disabled)
|
|
36
|
-
- For npm install: [Node.js ≥ 18](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/)
|
|
37
|
-
- For Python install: Python ≥ 3.11
|
|
38
|
-
|
|
39
|
-
### Install
|
|
40
|
-
|
|
41
|
-
**Via npx (recommended — no Python setup required):**
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
npx @teamnetwork-nz/sonicwall-api-mcp-server
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
> The npm package is a thin launcher that calls `uvx sonicwall-mcp-server` under the hood. Only [uv](https://docs.astral.sh/uv/) needs to be installed — no Python environment setup required.
|
|
48
|
-
|
|
49
|
-
**Via pip / uv (Python):**
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
pip install sonicwall-mcp-server
|
|
53
|
-
# or
|
|
54
|
-
uv pip install sonicwall-mcp-server
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
### Environment variables
|
|
58
|
-
|
|
59
|
-
| Variable | Required | Default | Description |
|
|
60
|
-
|----------|----------|---------|-------------|
|
|
61
|
-
| `SONICWALL_HOST` | Yes | — | Appliance IP or hostname |
|
|
62
|
-
| `SONICWALL_USERNAME` | Yes | — | Admin username |
|
|
63
|
-
| `SONICWALL_PASSWORD` | Yes | — | Admin password |
|
|
64
|
-
| `SONICWALL_PORT` | No | `443` | HTTPS management port |
|
|
65
|
-
| `SONICWALL_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |
|
|
66
|
-
| `SONICWALL_READWRITE` | No | `false` | Set `true` to allow write operations |
|
|
67
|
-
|
|
68
|
-
`SONICWALL_READ_ONLY=false` remains a deprecated compatibility alias for one release. `SONICWALL_READWRITE` takes precedence when both are set.
|
|
69
|
-
| `SONICWALL_DEVICES_FILE` | No | — | Path to JSON file for multi-device config |
|
|
70
|
-
| `SONICWALL_REQUEST_TIMEOUT` | No | `30.0` | Per-request timeout in seconds |
|
|
71
|
-
|
|
72
|
-
Copy `.env.example` to `.env` for local development.
|
|
73
|
-
|
|
74
|
-
### Claude Desktop / Claude Code Integration
|
|
75
|
-
|
|
76
|
-
Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
|
|
77
|
-
|
|
78
|
-
**Using npx (easiest):**
|
|
79
|
-
|
|
80
|
-
```json
|
|
81
|
-
{
|
|
82
|
-
"mcpServers": {
|
|
83
|
-
"sonicwall": {
|
|
84
|
-
"command": "npx",
|
|
85
|
-
"args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
|
|
86
|
-
"env": {
|
|
87
|
-
"SONICWALL_HOST": "192.168.168.168",
|
|
88
|
-
"SONICWALL_USERNAME": "admin",
|
|
89
|
-
"SONICWALL_PASSWORD": "your_password",
|
|
90
|
-
"SONICWALL_SSL_VERIFY": "false",
|
|
91
|
-
"SONICWALL_READWRITE": "true"
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
**Using uvx directly:**
|
|
99
|
-
|
|
100
|
-
```json
|
|
101
|
-
{
|
|
102
|
-
"mcpServers": {
|
|
103
|
-
"sonicwall": {
|
|
104
|
-
"command": "uvx",
|
|
105
|
-
"args": ["sonicwall-mcp-server"],
|
|
106
|
-
"env": {
|
|
107
|
-
"SONICWALL_HOST": "192.168.168.168",
|
|
108
|
-
"SONICWALL_USERNAME": "admin",
|
|
109
|
-
"SONICWALL_PASSWORD": "your_password",
|
|
110
|
-
"SONICWALL_SSL_VERIFY": "false",
|
|
111
|
-
"SONICWALL_READWRITE": "true"
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
**Using the installed Python CLI:**
|
|
119
|
-
|
|
120
|
-
```json
|
|
121
|
-
{
|
|
122
|
-
"mcpServers": {
|
|
123
|
-
"sonicwall": {
|
|
124
|
-
"command": "sonicwall-mcp",
|
|
125
|
-
"env": {
|
|
126
|
-
"SONICWALL_HOST": "192.168.168.168",
|
|
127
|
-
"SONICWALL_USERNAME": "admin",
|
|
128
|
-
"SONICWALL_PASSWORD": "your_password",
|
|
129
|
-
"SONICWALL_SSL_VERIFY": "false",
|
|
130
|
-
"SONICWALL_READWRITE": "true"
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
}
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### Multi-device setup
|
|
138
|
-
|
|
139
|
-
To manage multiple appliances, set `SONICWALL_DEVICES_FILE` to a JSON file:
|
|
140
|
-
|
|
141
|
-
```json
|
|
142
|
-
[
|
|
143
|
-
{
|
|
144
|
-
"name": "site-a",
|
|
145
|
-
"host": "10.0.1.1",
|
|
146
|
-
"username": "admin",
|
|
147
|
-
"password": "secret",
|
|
148
|
-
"ssl_verify": false,
|
|
149
|
-
"read_only": false
|
|
150
|
-
},
|
|
151
|
-
{
|
|
152
|
-
"name": "site-b",
|
|
153
|
-
"host": "10.0.2.1",
|
|
154
|
-
"username": "admin",
|
|
155
|
-
"password": "secret",
|
|
156
|
-
"ssl_verify": false,
|
|
157
|
-
"read_only": true
|
|
158
|
-
}
|
|
159
|
-
]
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Pass `device="site-b"` to any tool to target a specific appliance; omit it to use the first device.
|
|
163
|
-
|
|
164
|
-
### Development
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
uv venv && source .venv/bin/activate
|
|
168
|
-
uv pip install -e ".[dev]"
|
|
169
|
-
pytest tests/ -v # unit tests (no appliance needed)
|
|
170
|
-
mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## Agent guidance
|
|
174
|
-
|
|
175
|
-
The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
|
|
176
|
-
|
|
177
|
-
- **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
|
|
178
|
-
- **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
|
|
25
|
+
|
|
26
|
+
### Diagnosing an unreachable IP
|
|
27
|
+
|
|
28
|
+
Use `diagnose_ip` for a combined report containing the appliance's selected network path, configured interfaces and route policies, matching ARP entry, ping result, and traceroute. Set `interface` to force the live tests through an interface such as `X1`, or set `include_traceroute=false` for a faster check. The focused tools `find_network_path`, `lookup_arp`, `ping_from_appliance`, and `traceroute_from_appliance` are also available. Diagnostic POST actions are read-only and work without enabling `SONICWALL_READWRITE`.
|
|
29
|
+
|
|
30
|
+
Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
|
|
31
|
+
|
|
32
|
+
## Quick Start
|
|
33
|
+
|
|
34
|
+
### Prerequisites
|
|
35
|
+
|
|
36
|
+
- A SonicWall NSA appliance running SonicOS 6.5, 7.x, or 8.x
|
|
37
|
+
- SonicOS API enabled: **Device › Settings › Administration › SonicOS API** — toggle **SonicOS API** on, and ensure **RFC-2617 HTTP Basic Access authentication** is also enabled (the MCP server uses Basic auth to obtain a session token, falling back to RFC-7616 Digest if Basic is disabled)
|
|
38
|
+
- For npm install: [Node.js ≥ 18](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/)
|
|
39
|
+
- For Python install: Python ≥ 3.11
|
|
40
|
+
|
|
41
|
+
### Install
|
|
42
|
+
|
|
43
|
+
**Via npx (recommended — no Python setup required):**
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx @teamnetwork-nz/sonicwall-api-mcp-server
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
> The npm package is a thin launcher that calls `uvx sonicwall-mcp-server` under the hood. Only [uv](https://docs.astral.sh/uv/) needs to be installed — no Python environment setup required.
|
|
50
|
+
|
|
51
|
+
**Via pip / uv (Python):**
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install sonicwall-mcp-server
|
|
55
|
+
# or
|
|
56
|
+
uv pip install sonicwall-mcp-server
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Environment variables
|
|
60
|
+
|
|
61
|
+
| Variable | Required | Default | Description |
|
|
62
|
+
|----------|----------|---------|-------------|
|
|
63
|
+
| `SONICWALL_HOST` | Yes | — | Appliance IP or hostname |
|
|
64
|
+
| `SONICWALL_USERNAME` | Yes | — | Admin username |
|
|
65
|
+
| `SONICWALL_PASSWORD` | Yes | — | Admin password |
|
|
66
|
+
| `SONICWALL_PORT` | No | `443` | HTTPS management port |
|
|
67
|
+
| `SONICWALL_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |
|
|
68
|
+
| `SONICWALL_READWRITE` | No | `false` | Set `true` to allow write operations |
|
|
69
|
+
|
|
70
|
+
`SONICWALL_READ_ONLY=false` remains a deprecated compatibility alias for one release. `SONICWALL_READWRITE` takes precedence when both are set.
|
|
71
|
+
| `SONICWALL_DEVICES_FILE` | No | — | Path to JSON file for multi-device config |
|
|
72
|
+
| `SONICWALL_REQUEST_TIMEOUT` | No | `30.0` | Per-request timeout in seconds |
|
|
73
|
+
|
|
74
|
+
Copy `.env.example` to `.env` for local development.
|
|
75
|
+
|
|
76
|
+
### Claude Desktop / Claude Code Integration
|
|
77
|
+
|
|
78
|
+
Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
|
|
79
|
+
|
|
80
|
+
**Using npx (easiest):**
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"mcpServers": {
|
|
85
|
+
"sonicwall": {
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
|
|
88
|
+
"env": {
|
|
89
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
90
|
+
"SONICWALL_USERNAME": "admin",
|
|
91
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
92
|
+
"SONICWALL_SSL_VERIFY": "false",
|
|
93
|
+
"SONICWALL_READWRITE": "true"
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Using uvx directly:**
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"mcpServers": {
|
|
105
|
+
"sonicwall": {
|
|
106
|
+
"command": "uvx",
|
|
107
|
+
"args": ["sonicwall-mcp-server"],
|
|
108
|
+
"env": {
|
|
109
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
110
|
+
"SONICWALL_USERNAME": "admin",
|
|
111
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
112
|
+
"SONICWALL_SSL_VERIFY": "false",
|
|
113
|
+
"SONICWALL_READWRITE": "true"
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**Using the installed Python CLI:**
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"mcpServers": {
|
|
125
|
+
"sonicwall": {
|
|
126
|
+
"command": "sonicwall-mcp",
|
|
127
|
+
"env": {
|
|
128
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
129
|
+
"SONICWALL_USERNAME": "admin",
|
|
130
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
131
|
+
"SONICWALL_SSL_VERIFY": "false",
|
|
132
|
+
"SONICWALL_READWRITE": "true"
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Multi-device setup
|
|
140
|
+
|
|
141
|
+
To manage multiple appliances, set `SONICWALL_DEVICES_FILE` to a JSON file:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
[
|
|
145
|
+
{
|
|
146
|
+
"name": "site-a",
|
|
147
|
+
"host": "10.0.1.1",
|
|
148
|
+
"username": "admin",
|
|
149
|
+
"password": "secret",
|
|
150
|
+
"ssl_verify": false,
|
|
151
|
+
"read_only": false
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
"name": "site-b",
|
|
155
|
+
"host": "10.0.2.1",
|
|
156
|
+
"username": "admin",
|
|
157
|
+
"password": "secret",
|
|
158
|
+
"ssl_verify": false,
|
|
159
|
+
"read_only": true
|
|
160
|
+
}
|
|
161
|
+
]
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Pass `device="site-b"` to any tool to target a specific appliance; omit it to use the first device.
|
|
165
|
+
|
|
166
|
+
### Development
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
uv venv && source .venv/bin/activate
|
|
170
|
+
uv pip install -e ".[dev]"
|
|
171
|
+
pytest debug/tests/ -v # unit tests (no appliance needed)
|
|
172
|
+
mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Agent guidance
|
|
176
|
+
|
|
177
|
+
The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
|
|
178
|
+
|
|
179
|
+
- **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
|
|
180
|
+
- **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
|
|
179
181
|
- **Log configuration scope** — log tools expose categories and event definitions, not searchable runtime history
|
|
180
|
-
- **Object and rule management** — recommended workflow for creating address objects and firewall rules
|
|
181
|
-
- **Concurrent sessions** — SonicOS limit of one active API session per appliance
|
|
182
|
-
|
|
183
|
-
No special prompting is required — the agent receives these guidelines automatically.
|
|
184
|
-
|
|
185
|
-
## Important Notes
|
|
186
|
-
|
|
187
|
-
- SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
|
|
188
|
-
- All configuration changes (create/update/delete) are **staged** and do not take effect until you call `commit_config`. Use `discard_config` to abandon staged changes.
|
|
189
|
-
- Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
|
|
182
|
+
- **Object and rule management** — recommended workflow for creating address objects and firewall rules
|
|
183
|
+
- **Concurrent sessions** — SonicOS limit of one active API session per appliance
|
|
184
|
+
|
|
185
|
+
No special prompting is required — the agent receives these guidelines automatically.
|
|
186
|
+
|
|
187
|
+
## Important Notes
|
|
188
|
+
|
|
189
|
+
- SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
|
|
190
|
+
- All configuration changes (create/update/delete) are **staged** and do not take effect until you call `commit_config`. Use `discard_config` to abandon staged changes.
|
|
191
|
+
- Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
|
|
192
|
+
|
|
193
|
+
<!-- BEGIN MCP configuration reference -->
|
|
194
|
+
## Environment variable reference
|
|
195
|
+
|
|
196
|
+
The server does **not** automatically load `.env`. Inject these variables through the MCP client or process environment; copying the example alone does not configure the server.
|
|
197
|
+
|
|
198
|
+
Copy `.env.example` for variable names and safe placeholders. Replace required placeholders privately. Optional variables should be omitted unless needed; an empty value may override a default. Never commit credentials, real identities, device profiles, exports, or logs.
|
|
199
|
+
|
|
200
|
+
| Variable | Required | Default | Purpose and accepted values |
|
|
201
|
+
|---|---|---|---|
|
|
202
|
+
| `SONICWALL_DEVICES_FILE` | Alternative | `unset` | Private JSON device-profile array; replaces single-device credentials and settings, including per-profile read_only. |
|
|
203
|
+
| `SONICWALL_DEVICE_NAME` | No | `default` | Local name for the single-device profile. |
|
|
204
|
+
| `SONICWALL_HOST` | Conditional | `unset` | Firewall hostname; required unless SONICWALL_DEVICES_FILE is set. |
|
|
205
|
+
| `SONICWALL_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
|
|
206
|
+
| `SONICWALL_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
|
|
207
|
+
| `SONICWALL_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
|
|
208
|
+
| `SONICWALL_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
|
|
209
|
+
| `SONICWALL_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
|
|
210
|
+
| `SONICWALL_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
|
|
211
|
+
| `SONICWALL_PASSWORD` | Conditional | `unset` | Firewall API password; required in single-device mode. |
|
|
212
|
+
| `SONICWALL_PORT` | No | `443` | Firewall HTTPS port; integer 1–65535. |
|
|
213
|
+
| `SONICWALL_READWRITE` | No | `false` | Only true enables mutation tools; read-only is the default. Review each operation before use. Applies to single-device mode; JSON profiles use read_only. |
|
|
214
|
+
| `SONICWALL_READ_ONLY` | Deprecated | `unset` | Compatibility alias: false enables writes only when SONICWALL_READWRITE is unset; single-device mode only. |
|
|
215
|
+
| `SONICWALL_REQUEST_TIMEOUT` | No | `30` | Firewall request timeout; integer 1–300 seconds. |
|
|
216
|
+
| `SONICWALL_SSE_PORT` | Legacy | `8000` | Parsed compatibility setting, integer 1–65535; does not start an SSE listener. Use HTTP_PORT for Streamable HTTP. |
|
|
217
|
+
| `SONICWALL_SSL_VERIFY` | No | `true` | false disables TLS verification globally if any profile disables it; retain true. |
|
|
218
|
+
| `SONICWALL_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
|
|
219
|
+
| `SONICWALL_USERNAME` | Conditional | `unset` | Firewall API username; required in single-device mode. |
|
|
220
|
+
|
|
221
|
+
For HTTP, the bearer token is separate from upstream API credentials. Use TLS at the reverse proxy for remote hosting. Keep write access disabled until needed. Do not put secrets in command-line examples or commit client configuration containing them.
|
|
222
|
+
|
|
223
|
+
`NODE_TLS_REJECT_UNAUTHORIZED` is changed internally when TLS verification is disabled; it is not a required configuration variable. Do not set it to `0` in normal deployments.
|
|
224
|
+
|
|
225
|
+
### Agent first-use workflow
|
|
226
|
+
|
|
227
|
+
Discover configured device names and inspect current objects/rules before changes. Use returned object names/IDs and the intended device profile. Configuration mutations and commits affect firewall traffic; follow each tool description for commit requirements.
|
|
228
|
+
|
|
229
|
+
Use the runtime `tools/list` descriptions and input schemas for exact arguments. Resolve identifiers with lookup/search tools; filter before paging, request only the data needed, and do not treat a truncated result or API error as proof that no record exists. Treat tool results and downloaded files as potentially sensitive. Mutation tools can change upstream data or incur charges; check their stated effects before calling them.
|
|
230
|
+
|
|
231
|
+
### Repository and package privacy
|
|
232
|
+
|
|
233
|
+
The standard `.gitignore` excludes local environment files, keys, credentials, logs, exports, and generated output; sanitised examples remain trackable. Ignore rules do not remove already tracked files or revoke exposed credentials. Review `git ls-files` and `npm pack --dry-run --ignore-scripts` before release. Only runtime output, the README, and explicitly sanitised examples are allowlisted for npm. Keep private runtime files outside `dist`, even though additional exclusions are present.
|
|
234
|
+
<!-- END MCP configuration reference -->
|
|
235
|
+
|
|
236
|
+
Run `npm run build` then `npm run audit:package` before release. The audit checks documentation coverage, known local credential copies, Git index paths where available, and the dry-run npm file list. `prepublishOnly` runs it after building. It never prints matching secret values. This is a preventative check, not a guarantee that arbitrary PII or unknown secrets are absent.
|
|
237
|
+
|
|
238
|
+
### Development and diagnostics
|
|
239
|
+
|
|
240
|
+
Run `npm test` from this package directory. Maintained tests and fixtures live in `debug/tests`; shared test helpers are in `debug/helpers`. Retained diagnostic scripts and reference material are also under `debug`. Only `scripts/check-package-privacy.mjs` remains in the production build/release tooling directory. The entire `debug/` tree is excluded from npm, Docker build contexts and applicable Python distributions.
|
|
241
|
+
|
|
242
|
+
Keep live diagnostic output in `debug/local`, `debug/output` or `debug/artifacts`; those private directories are also ignored by Git. Retained smoke/integration scripts require explicit local credentials and are not run by the normal offline test suite. Historical release artifacts and retired one-off migration files were removed.
|
package/dist/index.js
CHANGED
|
@@ -2317,11 +2317,40 @@ function strictSchema(schema) {
|
|
|
2317
2317
|
if (isSchema(schema) && typeof schema.strict === "function") return schema.strict();
|
|
2318
2318
|
return schema;
|
|
2319
2319
|
}
|
|
2320
|
+
function addOutputFormat(schema) {
|
|
2321
|
+
const strict = strictSchema(schema);
|
|
2322
|
+
if (typeof strict.extend !== "function") return strict;
|
|
2323
|
+
return strict.extend({
|
|
2324
|
+
outputFormat: import_v317.z.enum(["json"]).optional().describe("Return the result as valid JSON text without Markdown wrappers.")
|
|
2325
|
+
}).strict?.() ?? strict;
|
|
2326
|
+
}
|
|
2327
|
+
function toJsonValue(text2) {
|
|
2328
|
+
const fenced = text2.match(/\x60\x60\x60json\s*([\s\S]*?)\s*\x60\x60\x60/i)?.[1];
|
|
2329
|
+
const candidate = fenced ?? text2;
|
|
2330
|
+
try {
|
|
2331
|
+
return JSON.parse(candidate);
|
|
2332
|
+
} catch {
|
|
2333
|
+
return text2;
|
|
2334
|
+
}
|
|
2335
|
+
}
|
|
2320
2336
|
function enforceStrictToolInputs(server) {
|
|
2321
2337
|
const mutable = server;
|
|
2322
2338
|
const createRegisteredTool = mutable._createRegisteredTool.bind(server);
|
|
2323
2339
|
mutable._createRegisteredTool = (...args) => {
|
|
2324
|
-
args[3] =
|
|
2340
|
+
args[3] = addOutputFormat(args[3]);
|
|
2341
|
+
const handler = args[8];
|
|
2342
|
+
if (typeof handler === "function") {
|
|
2343
|
+
args[8] = async (input, ...rest) => {
|
|
2344
|
+
const values = input && typeof input === "object" ? input : {};
|
|
2345
|
+
const { outputFormat, ...toolArgs } = values;
|
|
2346
|
+
const result = await handler(toolArgs, ...rest);
|
|
2347
|
+
if (outputFormat !== "json" || result?.isError || !Array.isArray(result?.content)) return result;
|
|
2348
|
+
const textItems = result.content.filter((item) => item.type === "text" && typeof item.text === "string");
|
|
2349
|
+
if (textItems.length === 0) return result;
|
|
2350
|
+
const data = result.structuredContent !== void 0 ? result.structuredContent : textItems.length === 1 ? toJsonValue(textItems[0]?.text ?? "") : textItems.map((item) => toJsonValue(item.text));
|
|
2351
|
+
return { ...result, content: [{ type: "text", text: JSON.stringify(data, null, 2) }], ...result.structuredContent === void 0 && data && typeof data === "object" ? { structuredContent: data } : {} };
|
|
2352
|
+
};
|
|
2353
|
+
}
|
|
2325
2354
|
return createRegisteredTool(...args);
|
|
2326
2355
|
};
|
|
2327
2356
|
}
|
package/dist/strict-tools.js
CHANGED
|
@@ -39,11 +39,40 @@ function strictSchema(schema) {
|
|
|
39
39
|
if (isSchema(schema) && typeof schema.strict === "function") return schema.strict();
|
|
40
40
|
return schema;
|
|
41
41
|
}
|
|
42
|
+
function addOutputFormat(schema) {
|
|
43
|
+
const strict = strictSchema(schema);
|
|
44
|
+
if (typeof strict.extend !== "function") return strict;
|
|
45
|
+
return strict.extend({
|
|
46
|
+
outputFormat: import_v3.z.enum(["json"]).optional().describe("Return the result as valid JSON text without Markdown wrappers.")
|
|
47
|
+
}).strict?.() ?? strict;
|
|
48
|
+
}
|
|
49
|
+
function toJsonValue(text) {
|
|
50
|
+
const fenced = text.match(/\x60\x60\x60json\s*([\s\S]*?)\s*\x60\x60\x60/i)?.[1];
|
|
51
|
+
const candidate = fenced ?? text;
|
|
52
|
+
try {
|
|
53
|
+
return JSON.parse(candidate);
|
|
54
|
+
} catch {
|
|
55
|
+
return text;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
42
58
|
function enforceStrictToolInputs(server) {
|
|
43
59
|
const mutable = server;
|
|
44
60
|
const createRegisteredTool = mutable._createRegisteredTool.bind(server);
|
|
45
61
|
mutable._createRegisteredTool = (...args) => {
|
|
46
|
-
args[3] =
|
|
62
|
+
args[3] = addOutputFormat(args[3]);
|
|
63
|
+
const handler = args[8];
|
|
64
|
+
if (typeof handler === "function") {
|
|
65
|
+
args[8] = async (input, ...rest) => {
|
|
66
|
+
const values = input && typeof input === "object" ? input : {};
|
|
67
|
+
const { outputFormat, ...toolArgs } = values;
|
|
68
|
+
const result = await handler(toolArgs, ...rest);
|
|
69
|
+
if (outputFormat !== "json" || result?.isError || !Array.isArray(result?.content)) return result;
|
|
70
|
+
const textItems = result.content.filter((item) => item.type === "text" && typeof item.text === "string");
|
|
71
|
+
if (textItems.length === 0) return result;
|
|
72
|
+
const data = result.structuredContent !== void 0 ? result.structuredContent : textItems.length === 1 ? toJsonValue(textItems[0]?.text ?? "") : textItems.map((item) => toJsonValue(item.text));
|
|
73
|
+
return { ...result, content: [{ type: "text", text: JSON.stringify(data, null, 2) }], ...result.structuredContent === void 0 && data && typeof data === "object" ? { structuredContent: data } : {} };
|
|
74
|
+
};
|
|
75
|
+
}
|
|
47
76
|
return createRegisteredTool(...args);
|
|
48
77
|
};
|
|
49
78
|
}
|
package/package.json
CHANGED
|
@@ -1,52 +1,53 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@teamnetwork-nz/sonicwall-api-mcp-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "MCP server for SonicWall appliance configuration and diagnostics
|
|
5
|
-
"keywords": [
|
|
6
|
-
"mcp",
|
|
7
|
-
"model-context-protocol",
|
|
8
|
-
"sonicwall",
|
|
9
|
-
"firewall",
|
|
10
|
-
"sonicOS",
|
|
11
|
-
"api",
|
|
12
|
-
"network",
|
|
13
|
-
"security"
|
|
14
|
-
],
|
|
15
|
-
"homepage": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server",
|
|
16
|
-
"bugs": {
|
|
17
|
-
"url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server/issues"
|
|
18
|
-
},
|
|
19
|
-
"license": "MIT",
|
|
20
|
-
"
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
"
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
"dist
|
|
31
|
-
"README.md",
|
|
32
|
-
"
|
|
33
|
-
],
|
|
34
|
-
"scripts": {
|
|
35
|
-
"build": "tsup",
|
|
36
|
-
"test": "npm run build && node --test tests/*.test.mjs",
|
|
37
|
-
"prepublishOnly": "npm run build",
|
|
38
|
-
"start": "node dist/index.js"
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
"
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
"
|
|
50
|
-
"
|
|
51
|
-
|
|
52
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@teamnetwork-nz/sonicwall-api-mcp-server",
|
|
3
|
+
"version": "0.10.0",
|
|
4
|
+
"description": "MCP server for SonicWall appliance configuration and diagnostics — objects, rules, NAT, routing, reachability, and GeoIP lookup",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"mcp",
|
|
7
|
+
"model-context-protocol",
|
|
8
|
+
"sonicwall",
|
|
9
|
+
"firewall",
|
|
10
|
+
"sonicOS",
|
|
11
|
+
"api",
|
|
12
|
+
"network",
|
|
13
|
+
"security"
|
|
14
|
+
],
|
|
15
|
+
"homepage": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server",
|
|
16
|
+
"bugs": {
|
|
17
|
+
"url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server/issues"
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT",
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
|
|
23
|
+
},
|
|
24
|
+
"main": "dist/index.js",
|
|
25
|
+
"bin": {
|
|
26
|
+
"sonicwall-mcp": "./dist/index.js"
|
|
27
|
+
},
|
|
28
|
+
"files": [
|
|
29
|
+
"dist/**/*.js",
|
|
30
|
+
"dist/**/*.d.ts",
|
|
31
|
+
"README.md",
|
|
32
|
+
".env.example"
|
|
33
|
+
],
|
|
34
|
+
"scripts": {
|
|
35
|
+
"build": "tsup",
|
|
36
|
+
"test": "npm run build && node --test debug/tests/*.test.mjs",
|
|
37
|
+
"prepublishOnly": "npm run build && npm run audit:package",
|
|
38
|
+
"start": "node dist/index.js",
|
|
39
|
+
"audit:package": "node scripts/check-package-privacy.mjs"
|
|
40
|
+
},
|
|
41
|
+
"engines": {
|
|
42
|
+
"node": ">=18"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
46
|
+
"zod": "^4.6.7"
|
|
47
|
+
},
|
|
48
|
+
"devDependencies": {
|
|
49
|
+
"@types/node": "^20.0.0",
|
|
50
|
+
"tsup": "^8.0.0",
|
|
51
|
+
"typescript": "^5.4.0"
|
|
52
|
+
}
|
|
53
|
+
}
|