@teamnetwork-nz/sonicwall-api-mcp-server 0.8.1 → 0.9.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 +5 -0
- package/dist/index.js +154 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -15,11 +15,16 @@ A [Model Context Protocol](https://modelcontextprotocol.io/) server that provide
|
|
|
15
15
|
- **NAT policies** — full CRUD for inbound/outbound NAT rules
|
|
16
16
|
- **Security policies** — CRUD for zone-based security policies
|
|
17
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)
|
|
18
19
|
- **GeoIP lookup** — identify the country/botnet classification of an IP address
|
|
19
20
|
- **Config management** — view and commit (or discard) staged changes
|
|
20
21
|
|
|
21
22
|
> 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.
|
|
22
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
|
+
|
|
23
28
|
Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
|
|
24
29
|
|
|
25
30
|
## Quick Start
|
package/dist/index.js
CHANGED
|
@@ -306,8 +306,8 @@ var AuthManager = class {
|
|
|
306
306
|
throw new AuthenticationError("Login rejected \u2014 check username and password.");
|
|
307
307
|
}
|
|
308
308
|
if (resp.status >= 400) {
|
|
309
|
-
const
|
|
310
|
-
throw new AuthenticationError(`Login failed with HTTP ${resp.status}: ${
|
|
309
|
+
const text2 = await resp.text().catch(() => "");
|
|
310
|
+
throw new AuthenticationError(`Login failed with HTTP ${resp.status}: ${text2.slice(0, 200)}`);
|
|
311
311
|
}
|
|
312
312
|
try {
|
|
313
313
|
const body = await resp.json();
|
|
@@ -419,7 +419,7 @@ var SonicWallClient = class {
|
|
|
419
419
|
await this.auth.logout(this.baseUrl);
|
|
420
420
|
}
|
|
421
421
|
async request(method, path, options) {
|
|
422
|
-
const isWrite = WRITE_METHODS.has(method.toUpperCase());
|
|
422
|
+
const isWrite = WRITE_METHODS.has(method.toUpperCase()) && !options?.readonlyAction;
|
|
423
423
|
if (this.profile.readOnly && isWrite) {
|
|
424
424
|
throw new ReadOnlyError(method.toUpperCase(), path);
|
|
425
425
|
}
|
|
@@ -472,8 +472,8 @@ var SonicWallClient = class {
|
|
|
472
472
|
await this._throwApiError(resp);
|
|
473
473
|
}
|
|
474
474
|
this.auth.touch();
|
|
475
|
-
const
|
|
476
|
-
return
|
|
475
|
+
const text2 = await resp.text();
|
|
476
|
+
return text2 ? JSON.parse(text2) : {};
|
|
477
477
|
}
|
|
478
478
|
throw new Error("unreachable");
|
|
479
479
|
}
|
|
@@ -506,6 +506,10 @@ var SonicWallClient = class {
|
|
|
506
506
|
post(path, body) {
|
|
507
507
|
return this.request("POST", path, { body });
|
|
508
508
|
}
|
|
509
|
+
/** Execute a POST endpoint whose semantics are read-only (for example diagnostics). */
|
|
510
|
+
postAction(path, body) {
|
|
511
|
+
return this.request("POST", path, { body, readonlyAction: true });
|
|
512
|
+
}
|
|
509
513
|
put(path, body) {
|
|
510
514
|
return this.request("PUT", path, { body });
|
|
511
515
|
}
|
|
@@ -1223,8 +1227,8 @@ var import_zod7 = require("zod");
|
|
|
1223
1227
|
function zoneName(v) {
|
|
1224
1228
|
if (typeof v === "string") return v;
|
|
1225
1229
|
if (v && typeof v === "object") {
|
|
1226
|
-
const
|
|
1227
|
-
if (typeof
|
|
1230
|
+
const z18 = v.zone;
|
|
1231
|
+
if (typeof z18 === "string") return z18;
|
|
1228
1232
|
}
|
|
1229
1233
|
return void 0;
|
|
1230
1234
|
}
|
|
@@ -1669,8 +1673,8 @@ var import_zod9 = require("zod");
|
|
|
1669
1673
|
function zoneName2(v) {
|
|
1670
1674
|
if (typeof v === "string") return v;
|
|
1671
1675
|
if (v && typeof v === "object") {
|
|
1672
|
-
const
|
|
1673
|
-
if (typeof
|
|
1676
|
+
const z18 = v.zone;
|
|
1677
|
+
if (typeof z18 === "string") return z18;
|
|
1674
1678
|
}
|
|
1675
1679
|
return void 0;
|
|
1676
1680
|
}
|
|
@@ -2075,6 +2079,142 @@ function registerRoutePolicyTools(server, registry) {
|
|
|
2075
2079
|
);
|
|
2076
2080
|
}
|
|
2077
2081
|
|
|
2082
|
+
// src/tools/diagnostics.ts
|
|
2083
|
+
var import_zod16 = require("zod");
|
|
2084
|
+
function text(value) {
|
|
2085
|
+
return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
|
|
2086
|
+
}
|
|
2087
|
+
function failure(e) {
|
|
2088
|
+
return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
|
|
2089
|
+
}
|
|
2090
|
+
function actionPath(action, host, iface, preferIpv6 = false) {
|
|
2091
|
+
const base = `diag/${action}-action/${encodeURIComponent(host)}`;
|
|
2092
|
+
if (!iface) return base;
|
|
2093
|
+
return `${base}/interface/${encodeURIComponent(iface)}/${preferIpv6 ? "true" : "false"}`;
|
|
2094
|
+
}
|
|
2095
|
+
async function readArpCache(client) {
|
|
2096
|
+
const paths = ["reporting/arp/caches", "arp/entries"];
|
|
2097
|
+
let lastError;
|
|
2098
|
+
for (const path of paths) {
|
|
2099
|
+
try {
|
|
2100
|
+
return await client.get(path);
|
|
2101
|
+
} catch (e) {
|
|
2102
|
+
lastError = e;
|
|
2103
|
+
if (!(e instanceof APIError) || ![400, 404].includes(e.status)) throw e;
|
|
2104
|
+
}
|
|
2105
|
+
}
|
|
2106
|
+
throw lastError;
|
|
2107
|
+
}
|
|
2108
|
+
function matchingEntries(value, ip) {
|
|
2109
|
+
const matches2 = [];
|
|
2110
|
+
const visit = (item) => {
|
|
2111
|
+
if (Array.isArray(item)) {
|
|
2112
|
+
for (const child of item) visit(child);
|
|
2113
|
+
} else if (item && typeof item === "object") {
|
|
2114
|
+
const object = item;
|
|
2115
|
+
if (Object.values(object).some((v) => typeof v === "string" && v === ip)) matches2.push(object);
|
|
2116
|
+
else for (const child of Object.values(object)) visit(child);
|
|
2117
|
+
}
|
|
2118
|
+
};
|
|
2119
|
+
visit(value);
|
|
2120
|
+
return matches2;
|
|
2121
|
+
}
|
|
2122
|
+
function registerDiagnosticTools(server, registry) {
|
|
2123
|
+
const targetSchema = {
|
|
2124
|
+
host: import_zod16.z.string().min(1).describe("Destination IP address or hostname"),
|
|
2125
|
+
interface: import_zod16.z.string().min(1).optional().describe("Source interface, such as X1; omit to let SonicOS choose"),
|
|
2126
|
+
prefer_ipv6: import_zod16.z.boolean().optional().default(false),
|
|
2127
|
+
device: import_zod16.z.string().optional()
|
|
2128
|
+
};
|
|
2129
|
+
server.tool(
|
|
2130
|
+
"ping_from_appliance",
|
|
2131
|
+
"Ping an IP address or hostname from the SonicWall appliance, optionally through a specific interface. This is a live, read-only diagnostic.",
|
|
2132
|
+
targetSchema,
|
|
2133
|
+
async ({ host, interface: iface, prefer_ipv6, device }) => {
|
|
2134
|
+
try {
|
|
2135
|
+
const client = await registry.getClient(device);
|
|
2136
|
+
return text(await client.postAction(actionPath("ping", host, iface, prefer_ipv6)));
|
|
2137
|
+
} catch (e) {
|
|
2138
|
+
return failure(e);
|
|
2139
|
+
}
|
|
2140
|
+
}
|
|
2141
|
+
);
|
|
2142
|
+
server.tool(
|
|
2143
|
+
"traceroute_from_appliance",
|
|
2144
|
+
"Trace the network path from the SonicWall appliance to an IP address or hostname, optionally through a specific interface. This can take several minutes.",
|
|
2145
|
+
targetSchema,
|
|
2146
|
+
async ({ host, interface: iface, prefer_ipv6, device }) => {
|
|
2147
|
+
try {
|
|
2148
|
+
const client = await registry.getClient(device);
|
|
2149
|
+
return text(await client.postAction(actionPath("traceroute", host, iface, prefer_ipv6)));
|
|
2150
|
+
} catch (e) {
|
|
2151
|
+
return failure(e);
|
|
2152
|
+
}
|
|
2153
|
+
}
|
|
2154
|
+
);
|
|
2155
|
+
server.tool(
|
|
2156
|
+
"find_network_path",
|
|
2157
|
+
"Ask the appliance to resolve the network path for a destination, including the route/interface selected by SonicOS.",
|
|
2158
|
+
{ host: import_zod16.z.string().min(1), device: import_zod16.z.string().optional() },
|
|
2159
|
+
async ({ host, device }) => {
|
|
2160
|
+
try {
|
|
2161
|
+
const client = await registry.getClient(device);
|
|
2162
|
+
return text(await client.postAction(`diag/network-path-action/${encodeURIComponent(host)}`));
|
|
2163
|
+
} catch (e) {
|
|
2164
|
+
return failure(e);
|
|
2165
|
+
}
|
|
2166
|
+
}
|
|
2167
|
+
);
|
|
2168
|
+
server.tool(
|
|
2169
|
+
"lookup_arp",
|
|
2170
|
+
"Read the appliance ARP cache. When ip is supplied, return only entries exactly matching that address.",
|
|
2171
|
+
{ ip: import_zod16.z.string().min(1).optional(), device: import_zod16.z.string().optional() },
|
|
2172
|
+
async ({ ip, device }) => {
|
|
2173
|
+
try {
|
|
2174
|
+
const client = await registry.getClient(device);
|
|
2175
|
+
const result = await readArpCache(client);
|
|
2176
|
+
return text(ip ? { ip, entries: matchingEntries(result, ip) } : result);
|
|
2177
|
+
} catch (e) {
|
|
2178
|
+
return failure(e);
|
|
2179
|
+
}
|
|
2180
|
+
}
|
|
2181
|
+
);
|
|
2182
|
+
server.tool(
|
|
2183
|
+
"diagnose_ip",
|
|
2184
|
+
"Run a combined, read-only diagnosis for an IP from the appliance: collect network-path selection, interface configuration, route policies, matching ARP state, ping, and optionally traceroute. Individual failures are reported without aborting the remaining checks.",
|
|
2185
|
+
{
|
|
2186
|
+
ip: import_zod16.z.string().ip(),
|
|
2187
|
+
interface: import_zod16.z.string().min(1).optional(),
|
|
2188
|
+
include_traceroute: import_zod16.z.boolean().optional().default(true),
|
|
2189
|
+
device: import_zod16.z.string().optional()
|
|
2190
|
+
},
|
|
2191
|
+
async ({ ip, interface: iface, include_traceroute, device }) => {
|
|
2192
|
+
try {
|
|
2193
|
+
const client = await registry.getClient(device);
|
|
2194
|
+
const checks = { target: ip, requested_interface: iface ?? null };
|
|
2195
|
+
const capture = async (name, fn) => {
|
|
2196
|
+
try {
|
|
2197
|
+
checks[name] = await fn();
|
|
2198
|
+
} catch (e) {
|
|
2199
|
+
checks[name] = { error: e.message };
|
|
2200
|
+
}
|
|
2201
|
+
};
|
|
2202
|
+
await capture("network_path", () => client.postAction(`diag/network-path-action/${encodeURIComponent(ip)}`));
|
|
2203
|
+
await capture("interfaces", () => client.get("interfaces/ipv4"));
|
|
2204
|
+
await capture("route_policies", () => client.get("route-policies/ipv4"));
|
|
2205
|
+
await capture("arp", async () => ({ entries: matchingEntries(await readArpCache(client), ip) }));
|
|
2206
|
+
await capture("ping", () => client.postAction(actionPath("ping", ip, iface)));
|
|
2207
|
+
if (include_traceroute) {
|
|
2208
|
+
await capture("traceroute", () => client.postAction(actionPath("traceroute", ip, iface)));
|
|
2209
|
+
}
|
|
2210
|
+
return text(checks);
|
|
2211
|
+
} catch (e) {
|
|
2212
|
+
return failure(e);
|
|
2213
|
+
}
|
|
2214
|
+
}
|
|
2215
|
+
);
|
|
2216
|
+
}
|
|
2217
|
+
|
|
2078
2218
|
// src/http-server.ts
|
|
2079
2219
|
var import_node_crypto = require("crypto");
|
|
2080
2220
|
var import_node_http = __toESM(require("http"));
|
|
@@ -2162,7 +2302,7 @@ var packageName = packageJson.name ?? "sonicwall-api-mcp-server";
|
|
|
2162
2302
|
var packageVersion = packageJson.version ?? "0.0.0";
|
|
2163
2303
|
|
|
2164
2304
|
// src/strict-tools.ts
|
|
2165
|
-
var
|
|
2305
|
+
var import_zod17 = require("zod");
|
|
2166
2306
|
function isSchema(value) {
|
|
2167
2307
|
return typeof value === "object" && value !== null && "_def" in value;
|
|
2168
2308
|
}
|
|
@@ -2172,8 +2312,8 @@ function isRawShape(value) {
|
|
|
2172
2312
|
return values.length === 0 || values.some(isSchema);
|
|
2173
2313
|
}
|
|
2174
2314
|
function strictSchema(schema) {
|
|
2175
|
-
if (schema === void 0) return
|
|
2176
|
-
if (isRawShape(schema)) return
|
|
2315
|
+
if (schema === void 0) return import_zod17.z.object({}).strict();
|
|
2316
|
+
if (isRawShape(schema)) return import_zod17.z.object(schema).strict();
|
|
2177
2317
|
if (isSchema(schema) && typeof schema.strict === "function") return schema.strict();
|
|
2178
2318
|
return schema;
|
|
2179
2319
|
}
|
|
@@ -2226,6 +2366,7 @@ IMPORTANT: All create/update/delete operations are STAGED and do not take effect
|
|
|
2226
2366
|
- Access rules (create_access_rule / list_access_rules) control traffic flow between zones with allow/deny/discard actions. Security policies (create_security_policy / list_security_policies) are zone-based and additionally support user and schedule filtering \u2014 use them when you need user-aware or time-restricted policies.
|
|
2227
2367
|
- Always call list_access_rules, list_nat_policies, or list_security_policies before modifying, to confirm current state and avoid duplicates. Access-rule and NAT-policy mutations use the UUID returned by their list tools; numeric IDs are not accepted.
|
|
2228
2368
|
- Rules and policies reference zones and schedules by name: use list_zones and list_schedules to discover valid names. list_interfaces shows interface IP/zone assignments and list_route_policies shows static routing \u2014 both are read-only discovery aids.
|
|
2369
|
+
- For reachability problems, use diagnose_ip for a combined appliance-side network-path, interface, route-policy, ARP, ping, and traceroute report. Use the individual diagnostic tools when you need a targeted test or a specific source interface.
|
|
2229
2370
|
- lookup_ip_country identifies which country an IP address belongs to (uses the appliance GeoIP database). Note: GeoIP *policy* management is not available via the SonicOS REST API.
|
|
2230
2371
|
|
|
2231
2372
|
## Read-only API note
|
|
@@ -2249,6 +2390,7 @@ SonicOS allows only ONE concurrent API session per appliance. If a session error
|
|
|
2249
2390
|
registerInterfaceTools(server, registry);
|
|
2250
2391
|
registerScheduleTools(server, registry);
|
|
2251
2392
|
registerRoutePolicyTools(server, registry);
|
|
2393
|
+
registerDiagnosticTools(server, registry);
|
|
2252
2394
|
return server;
|
|
2253
2395
|
};
|
|
2254
2396
|
const transport = config.transport;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@teamnetwork-nz/sonicwall-api-mcp-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "MCP server for SonicWall
|
|
3
|
+
"version": "0.9.0",
|
|
4
|
+
"description": "MCP server for SonicWall appliance configuration and diagnostics — objects, rules, NAT, routing, reachability, and GeoIP lookup",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
7
7
|
"model-context-protocol",
|