@teamnetwork-nz/sonicwall-api-mcp-server 0.2.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/README.md +141 -0
- package/bin/index.js +63 -0
- package/package.json +39 -0
package/README.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# SonicWall NSA MCP Server
|
|
2
|
+
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) server that provides full read/write access to SonicWall NSA series appliances via the SonicOS REST API.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Log analysis** — retrieve, filter, and search event logs, traffic logs, and threat/IPS events
|
|
8
|
+
- **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
|
|
9
|
+
- **Service objects & groups** — CRUD for protocol/port service definitions
|
|
10
|
+
- **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
|
|
11
|
+
- **NAT policies** — full CRUD for inbound/outbound NAT rules
|
|
12
|
+
- **Security policies** — CRUD for zone-based security policies
|
|
13
|
+
- **GeoIP filtering** — manage GeoIP country-block policies and assign them to access rules
|
|
14
|
+
- **Config management** — view and commit (or discard) staged changes
|
|
15
|
+
|
|
16
|
+
Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
### Install
|
|
21
|
+
|
|
22
|
+
**Via npm / npx (recommended — no Python setup required):**
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
# Run directly with npx (requires uv: https://docs.astral.sh/uv/)
|
|
26
|
+
npx @teamnetwork-nz/sonicwall-api-mcp-server
|
|
27
|
+
|
|
28
|
+
# Or install globally
|
|
29
|
+
npm install -g @teamnetwork-nz/sonicwall-api-mcp-server
|
|
30
|
+
sonicwall-mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Via pip / uv (Python):**
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install sonicwall-mcp-server
|
|
37
|
+
# or:
|
|
38
|
+
uv pip install sonicwall-mcp-server
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
> **Note:** The npm package is a thin launcher. It requires [uv](https://docs.astral.sh/uv/) to be installed and uses `uvx sonicwall-mcp-server` under the hood. No Python environment setup is needed beyond installing uv.
|
|
42
|
+
|
|
43
|
+
### Configure
|
|
44
|
+
|
|
45
|
+
Pass credentials as environment variables (no config file needed):
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
SONICWALL_HOST=192.168.168.168
|
|
49
|
+
SONICWALL_USERNAME=admin
|
|
50
|
+
SONICWALL_PASSWORD=your_password
|
|
51
|
+
SONICWALL_SSL_VERIFY=false # most appliances use self-signed certs
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Copy `.env.example` to `.env` for local development.
|
|
55
|
+
|
|
56
|
+
### Claude Desktop / Claude Code Integration
|
|
57
|
+
|
|
58
|
+
Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
|
|
59
|
+
|
|
60
|
+
**Using npx (easiest):**
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"sonicwall": {
|
|
66
|
+
"command": "npx",
|
|
67
|
+
"args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
|
|
68
|
+
"env": {
|
|
69
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
70
|
+
"SONICWALL_USERNAME": "admin",
|
|
71
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
72
|
+
"SONICWALL_SSL_VERIFY": "false"
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Using uvx directly:**
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"mcpServers": {
|
|
84
|
+
"sonicwall": {
|
|
85
|
+
"command": "uvx",
|
|
86
|
+
"args": ["sonicwall-mcp-server"],
|
|
87
|
+
"env": {
|
|
88
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
89
|
+
"SONICWALL_USERNAME": "admin",
|
|
90
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
91
|
+
"SONICWALL_SSL_VERIFY": "false"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Using the installed Python CLI:**
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"mcpServers": {
|
|
103
|
+
"sonicwall": {
|
|
104
|
+
"command": "sonicwall-mcp",
|
|
105
|
+
"env": {
|
|
106
|
+
"SONICWALL_HOST": "192.168.168.168",
|
|
107
|
+
"SONICWALL_USERNAME": "admin",
|
|
108
|
+
"SONICWALL_PASSWORD": "your_password",
|
|
109
|
+
"SONICWALL_SSL_VERIFY": "false"
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Development
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
uv venv && source .venv/bin/activate
|
|
120
|
+
uv pip install -e ".[dev]"
|
|
121
|
+
pytest tests/ -v # unit tests (no appliance needed)
|
|
122
|
+
mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Agent guidance
|
|
126
|
+
|
|
127
|
+
The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
|
|
128
|
+
|
|
129
|
+
- **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
|
|
130
|
+
- **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
|
|
131
|
+
- **Log tool selection** — when to use `get_event_logs` vs `get_traffic_logs` vs `get_threat_logs` vs `search_logs`
|
|
132
|
+
- **Object and rule management** — recommended workflow for creating address objects and firewall rules
|
|
133
|
+
- **Concurrent sessions** — SonicOS limit of one active API session per appliance
|
|
134
|
+
|
|
135
|
+
No special prompting is required — the agent receives these guidelines automatically.
|
|
136
|
+
|
|
137
|
+
## Important Notes
|
|
138
|
+
|
|
139
|
+
- SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
|
|
140
|
+
- 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.
|
|
141
|
+
- Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
|
package/bin/index.js
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Launcher for the SonicWall MCP server (Python package).
|
|
4
|
+
* Requires uv to be installed: https://docs.astral.sh/uv/
|
|
5
|
+
*
|
|
6
|
+
* Usage:
|
|
7
|
+
* npx @teamnetwork-nz/sonicwall-api-mcp-server
|
|
8
|
+
*
|
|
9
|
+
* Environment variables:
|
|
10
|
+
* SONICWALL_HOST, SONICWALL_USERNAME, SONICWALL_PASSWORD (required)
|
|
11
|
+
* SONICWALL_SSL_VERIFY, SONICWALL_READ_ONLY, ... (optional — see .env.example)
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
const { spawn } = require('child_process');
|
|
15
|
+
|
|
16
|
+
const args = process.argv.slice(2);
|
|
17
|
+
const isWindows = process.platform === 'win32';
|
|
18
|
+
|
|
19
|
+
function run(cmd, cmdArgs) {
|
|
20
|
+
return spawn(cmd, cmdArgs, {
|
|
21
|
+
stdio: 'inherit',
|
|
22
|
+
env: process.env,
|
|
23
|
+
shell: isWindows,
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function startWithFallback() {
|
|
28
|
+
const proc = run('uvx', ['sonicwall-mcp-server@latest', ...args]);
|
|
29
|
+
|
|
30
|
+
proc.on('error', (err) => {
|
|
31
|
+
if (err.code !== 'ENOENT') {
|
|
32
|
+
console.error(`sonicwall-mcp: failed to start via uvx: ${err.message}`);
|
|
33
|
+
process.exit(1);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// uvx not available — try python -m fallback
|
|
37
|
+
console.error(
|
|
38
|
+
'sonicwall-mcp: uvx not found. Falling back to `python -m sonicwall_mcp.server`.\n' +
|
|
39
|
+
'Install uv for the best experience: https://docs.astral.sh/uv/'
|
|
40
|
+
);
|
|
41
|
+
|
|
42
|
+
const fallback = run('python', ['-m', 'sonicwall_mcp.server', ...args]);
|
|
43
|
+
|
|
44
|
+
fallback.on('error', (e) => {
|
|
45
|
+
if (e.code === 'ENOENT') {
|
|
46
|
+
console.error(
|
|
47
|
+
'sonicwall-mcp: neither uvx nor python was found.\n' +
|
|
48
|
+
'Install uv (https://docs.astral.sh/uv/) or Python with sonicwall-mcp-server:\n' +
|
|
49
|
+
' pip install sonicwall-mcp-server'
|
|
50
|
+
);
|
|
51
|
+
} else {
|
|
52
|
+
console.error(`sonicwall-mcp: ${e.message}`);
|
|
53
|
+
}
|
|
54
|
+
process.exit(1);
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
fallback.on('close', (code) => process.exit(code ?? 0));
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
proc.on('close', (code) => process.exit(code ?? 0));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
startWithFallback();
|
package/package.json
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@teamnetwork-nz/sonicwall-api-mcp-server",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "MCP server for SonicWall NSA appliance API — logs, CRUD objects, rules, NAT, GeoIP",
|
|
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
|
+
"author": "Daryl",
|
|
21
|
+
"bin": {
|
|
22
|
+
"sonicwall-mcp": "./bin/index.js"
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"bin/",
|
|
26
|
+
"README.md",
|
|
27
|
+
"LICENSE"
|
|
28
|
+
],
|
|
29
|
+
"scripts": {
|
|
30
|
+
"start": "node bin/index.js"
|
|
31
|
+
},
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=18"
|
|
34
|
+
},
|
|
35
|
+
"repository": {
|
|
36
|
+
"type": "git",
|
|
37
|
+
"url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
|
|
38
|
+
}
|
|
39
|
+
}
|