@teamnetwork-nz/sonicwall-api-mcp-server 0.5.1 → 0.7.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.
Files changed (3) hide show
  1. package/README.md +3 -3
  2. package/dist/index.js +167 -187
  3. package/package.json +51 -51
package/README.md CHANGED
@@ -4,7 +4,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io/) server that provide
4
4
 
5
5
  ## Features
6
6
 
7
- - **Log analysis** — retrieve, filter, and search event logs and threat/IPS events
7
+ - **Log configuration** — inspect log categories and event-definition settings (not runtime event history)
8
8
  - **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
9
9
  - **Service objects & groups** — CRUD for protocol/port service definitions
10
10
  - **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
@@ -14,7 +14,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io/) server that provide
14
14
  - **GeoIP lookup** — identify the country/botnet classification of an IP address
15
15
  - **Config management** — view and commit (or discard) staged changes
16
16
 
17
- > The SonicOS REST API is configuration-focused. Connection/flow ("traffic") logs and GeoIP *policy* objects are not exposed as REST endpoints and therefore have no tools.
17
+ > 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.
18
18
 
19
19
  Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
20
20
 
@@ -165,7 +165,7 @@ The server supplies MCP `instructions` that are automatically delivered to the c
165
165
 
166
166
  - **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
167
167
  - **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
168
- - **Log tool selection** — when to use `get_event_logs` vs `get_traffic_logs` vs `get_threat_logs` vs `search_logs`
168
+ - **Log configuration scope** — log tools expose categories and event definitions, not searchable runtime history
169
169
  - **Object and rule management** — recommended workflow for creating address objects and firewall rules
170
170
  - **Concurrent sessions** — SonicOS limit of one active API session per appliance
171
171
 
package/dist/index.js CHANGED
@@ -377,9 +377,21 @@ var SonicWallClient = class {
377
377
  await this.auth.logout(this.baseUrl);
378
378
  }
379
379
  async request(method, path, options) {
380
- if (this.profile.readOnly && WRITE_METHODS.has(method.toUpperCase())) {
380
+ const isWrite = WRITE_METHODS.has(method.toUpperCase());
381
+ if (this.profile.readOnly && isWrite) {
381
382
  throw new ReadOnlyError(method.toUpperCase(), path);
382
383
  }
384
+ try {
385
+ return await this.send(method, path, options);
386
+ } catch (e) {
387
+ if (isWrite && e instanceof APIError && e.code === "E_NON_CONFIG") {
388
+ await this.send("POST", "config-mode");
389
+ return this.send(method, path, options);
390
+ }
391
+ throw e;
392
+ }
393
+ }
394
+ async send(method, path, options) {
383
395
  let url = `${this.baseUrl}/${path.replace(/^\//, "")}`;
384
396
  if (options?.params && Object.keys(options.params).length > 0) {
385
397
  const qs = new URLSearchParams(
@@ -1180,7 +1192,7 @@ function matchesZone(value, filter) {
1180
1192
  function registerAccessRuleTools(server, registry) {
1181
1193
  server.tool(
1182
1194
  "list_access_rules",
1183
- "List firewall access rules, optionally filtered by source and/or destination zone. Filtering is applied client-side (the SonicOS endpoint returns the full ruleset), so use from_zone/to_zone to keep responses small.",
1195
+ "List firewall access rules, optionally filtered by source and/or destination zone. Filtering is applied client-side over the complete ruleset; matched is the number returned and total is the unfiltered rule count (not pagination). Use each rule's uuid value as rule_uuid for get/update/enable/disable/delete tools.",
1184
1196
  {
1185
1197
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1186
1198
  from_zone: import_zod6.z.string().optional(),
@@ -1211,16 +1223,16 @@ function registerAccessRuleTools(server, registry) {
1211
1223
  );
1212
1224
  server.tool(
1213
1225
  "get_access_rule",
1214
- "Retrieve a single access rule by its numeric ID.",
1226
+ "Retrieve a single access rule by UUID. Pass a rule's uuid value from list_access_rules as rule_uuid.",
1215
1227
  {
1216
- rule_id: import_zod6.z.number(),
1228
+ rule_uuid: import_zod6.z.string().uuid(),
1217
1229
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1218
1230
  device: import_zod6.z.string().optional()
1219
1231
  },
1220
- async ({ rule_id, ip_version, device }) => {
1232
+ async ({ rule_uuid, ip_version, device }) => {
1221
1233
  try {
1222
1234
  const client = await registry.getClient(device);
1223
- const result = await client.get(`access-rules/${ip_version}/${rule_id}`);
1235
+ const result = await client.get(`access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`);
1224
1236
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1225
1237
  } catch (e) {
1226
1238
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1274,9 +1286,9 @@ function registerAccessRuleTools(server, registry) {
1274
1286
  );
1275
1287
  server.tool(
1276
1288
  "update_access_rule",
1277
- "Update fields on an existing access rule (GET-then-PUT). Only provided fields are changed. geo_ip_policy: name of an existing appliance GeoIP policy, or '' to remove it. Changes are STAGED; call commit_config to apply.",
1289
+ "Update an access rule selected by UUID (GET-then-PUT). Pass a rule's uuid value from list_access_rules as rule_uuid. Only provided fields are changed. geo_ip_policy: name of an existing appliance GeoIP policy, or '' to remove it. Changes are STAGED; call commit_config to apply.",
1278
1290
  {
1279
- rule_id: import_zod6.z.number(),
1291
+ rule_uuid: import_zod6.z.string().uuid(),
1280
1292
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1281
1293
  action: import_zod6.z.enum(["allow", "deny", "discard"]).optional(),
1282
1294
  source: import_zod6.z.string().optional(),
@@ -1288,10 +1300,11 @@ function registerAccessRuleTools(server, registry) {
1288
1300
  comment: import_zod6.z.string().optional(),
1289
1301
  device: import_zod6.z.string().optional()
1290
1302
  },
1291
- async ({ rule_id, ip_version, action, source, destination, service, enabled, log, geo_ip_policy, comment, device }) => {
1303
+ async ({ rule_uuid, ip_version, action, source, destination, service, enabled, log, geo_ip_policy, comment, device }) => {
1292
1304
  try {
1293
1305
  const client = await registry.getClient(device);
1294
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1306
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1307
+ const current = await client.get(path);
1295
1308
  const rules = current.access_rules;
1296
1309
  const rule = rules?.[0]?.[ip_version] ?? {};
1297
1310
  if (action !== void 0) rule.action = action;
@@ -1314,7 +1327,7 @@ function registerAccessRuleTools(server, registry) {
1314
1327
  rule.security_profile = { geo_ip_policy: { name: geo_ip_policy } };
1315
1328
  }
1316
1329
  }
1317
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1330
+ const result = await client.put(path, {
1318
1331
  access_rules: [{ [ip_version]: rule }]
1319
1332
  });
1320
1333
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1325,16 +1338,16 @@ function registerAccessRuleTools(server, registry) {
1325
1338
  );
1326
1339
  server.tool(
1327
1340
  "delete_access_rule",
1328
- "Delete an access rule by ID. Changes are STAGED; call commit_config to apply.",
1341
+ "Delete an access rule by UUID. Copy rule_uuid from list_access_rules. Changes are STAGED; call commit_config to apply.",
1329
1342
  {
1330
- rule_id: import_zod6.z.number(),
1343
+ rule_uuid: import_zod6.z.string().uuid(),
1331
1344
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1332
1345
  device: import_zod6.z.string().optional()
1333
1346
  },
1334
- async ({ rule_id, ip_version, device }) => {
1347
+ async ({ rule_uuid, ip_version, device }) => {
1335
1348
  try {
1336
1349
  const client = await registry.getClient(device);
1337
- const result = await client.delete(`access-rules/${ip_version}/${rule_id}`);
1350
+ const result = await client.delete(`access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`);
1338
1351
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1339
1352
  } catch (e) {
1340
1353
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1343,20 +1356,21 @@ function registerAccessRuleTools(server, registry) {
1343
1356
  );
1344
1357
  server.tool(
1345
1358
  "enable_access_rule",
1346
- "Enable a disabled access rule without modifying any other fields. Changes are STAGED; call commit_config to apply.",
1359
+ "Enable an access rule selected by UUID without modifying other fields. Copy rule_uuid from list_access_rules. Changes are STAGED; call commit_config to apply.",
1347
1360
  {
1348
- rule_id: import_zod6.z.number(),
1361
+ rule_uuid: import_zod6.z.string().uuid(),
1349
1362
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1350
1363
  device: import_zod6.z.string().optional()
1351
1364
  },
1352
- async ({ rule_id, ip_version, device }) => {
1365
+ async ({ rule_uuid, ip_version, device }) => {
1353
1366
  try {
1354
1367
  const client = await registry.getClient(device);
1355
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1368
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1369
+ const current = await client.get(path);
1356
1370
  const rules = current.access_rules;
1357
1371
  const rule = rules?.[0]?.[ip_version] ?? {};
1358
1372
  rule.enable = true;
1359
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1373
+ const result = await client.put(path, {
1360
1374
  access_rules: [{ [ip_version]: rule }]
1361
1375
  });
1362
1376
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1367,20 +1381,21 @@ function registerAccessRuleTools(server, registry) {
1367
1381
  );
1368
1382
  server.tool(
1369
1383
  "disable_access_rule",
1370
- "Disable an access rule without deleting it. Changes are STAGED; call commit_config to apply.",
1384
+ "Disable an access rule selected by UUID without deleting it. Copy rule_uuid from list_access_rules. Changes are STAGED; call commit_config to apply.",
1371
1385
  {
1372
- rule_id: import_zod6.z.number(),
1386
+ rule_uuid: import_zod6.z.string().uuid(),
1373
1387
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1374
1388
  device: import_zod6.z.string().optional()
1375
1389
  },
1376
- async ({ rule_id, ip_version, device }) => {
1390
+ async ({ rule_uuid, ip_version, device }) => {
1377
1391
  try {
1378
1392
  const client = await registry.getClient(device);
1379
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1393
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1394
+ const current = await client.get(path);
1380
1395
  const rules = current.access_rules;
1381
1396
  const rule = rules?.[0]?.[ip_version] ?? {};
1382
1397
  rule.enable = false;
1383
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1398
+ const result = await client.put(path, {
1384
1399
  access_rules: [{ [ip_version]: rule }]
1385
1400
  });
1386
1401
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1393,13 +1408,30 @@ function registerAccessRuleTools(server, registry) {
1393
1408
 
1394
1409
  // src/tools/nat-policies.ts
1395
1410
  var import_zod7 = require("zod");
1396
- function setNameField(obj, key, value) {
1397
- if (value !== void 0) obj[key] = { name: value };
1411
+ function interfaceValue(value) {
1412
+ return value.toLowerCase() === "any" ? "any" : value;
1413
+ }
1414
+ async function resolveRef(client, kind, value, ipVersion, allowOriginal) {
1415
+ const lower = value.toLowerCase();
1416
+ if (lower === "any") return { any: true };
1417
+ if (allowOriginal && lower === "original") return { original: true };
1418
+ const groupPath = kind === "address" ? `address-groups/${ipVersion}/name/${encodeURIComponent(value)}` : `service-groups/name/${encodeURIComponent(value)}`;
1419
+ try {
1420
+ await client.get(groupPath);
1421
+ return { group: value };
1422
+ } catch (e) {
1423
+ if (e instanceof APIError) return { name: value };
1424
+ throw e;
1425
+ }
1426
+ }
1427
+ var prioritySchema = import_zod7.z.union([import_zod7.z.number().int().min(1), import_zod7.z.literal("auto")]).optional().describe("Rule order: lower number = evaluated first. A positive integer sets a manual priority; 'auto' lets SonicOS assign it.");
1428
+ function priorityField(priority) {
1429
+ return priority === "auto" ? { auto: true } : { manual: priority };
1398
1430
  }
1399
1431
  function registerNatPolicyTools(server, registry) {
1400
1432
  server.tool(
1401
1433
  "list_nat_policies",
1402
- "List all NAT policies. ip_version: 'ipv4' (default) or 'ipv6'.",
1434
+ "List all NAT policies. ip_version: 'ipv4' (default) or 'ipv6'. Use each policy's uuid value as policy_uuid for get/update/enable/disable/delete tools.",
1403
1435
  {
1404
1436
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1405
1437
  device: import_zod7.z.string().optional()
@@ -1416,16 +1448,16 @@ function registerNatPolicyTools(server, registry) {
1416
1448
  );
1417
1449
  server.tool(
1418
1450
  "get_nat_policy",
1419
- "Retrieve a NAT policy by its numeric ID.",
1451
+ "Retrieve a NAT policy by UUID. Pass a policy's uuid value from list_nat_policies as policy_uuid.",
1420
1452
  {
1421
- policy_id: import_zod7.z.number(),
1453
+ policy_uuid: import_zod7.z.string().uuid(),
1422
1454
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1423
1455
  device: import_zod7.z.string().optional()
1424
1456
  },
1425
- async ({ policy_id, ip_version, device }) => {
1457
+ async ({ policy_uuid, ip_version, device }) => {
1426
1458
  try {
1427
1459
  const client = await registry.getClient(device);
1428
- const result = await client.get(`nat-policies/${ip_version}/${policy_id}`);
1460
+ const result = await client.get(`nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`);
1429
1461
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1430
1462
  } catch (e) {
1431
1463
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1434,7 +1466,7 @@ function registerNatPolicyTools(server, registry) {
1434
1466
  );
1435
1467
  server.tool(
1436
1468
  "create_nat_policy",
1437
- "Create a NAT policy. Use 'Original' for translated fields to mean no translation. Use 'Any' for interfaces to match all. Changes are STAGED; call commit_config to apply.",
1469
+ "Create a NAT policy. Address and service fields take an object or group name (groups are detected automatically) or 'Any'; translated fields also accept 'Original' for no translation. Interfaces take a name like 'X1' or 'Any'. Optional priority sets rule order (lower number = evaluated first). Changes are STAGED; call commit_config to apply.",
1438
1470
  {
1439
1471
  name: import_zod7.z.string(),
1440
1472
  original_source: import_zod7.z.string(),
@@ -1447,25 +1479,29 @@ function registerNatPolicyTools(server, registry) {
1447
1479
  outbound_interface: import_zod7.z.string().optional().default("Any"),
1448
1480
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1449
1481
  enabled: import_zod7.z.boolean().optional().default(true),
1482
+ dns_doctoring: import_zod7.z.boolean().optional().default(false),
1483
+ priority: prioritySchema,
1450
1484
  comment: import_zod7.z.string().optional(),
1451
1485
  device: import_zod7.z.string().optional()
1452
1486
  },
1453
- async ({ name, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, ip_version, enabled, comment, device }) => {
1487
+ async ({ name, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, ip_version, enabled, dns_doctoring, priority, comment, device }) => {
1454
1488
  try {
1455
1489
  const client = await registry.getClient(device);
1456
1490
  const policy = {
1457
1491
  name,
1458
1492
  enable: enabled,
1459
- original_source: { name: original_source },
1460
- translated_source: { name: translated_source },
1461
- original_destination: { name: original_destination },
1462
- translated_destination: { name: translated_destination },
1463
- original_service: { name: original_service },
1464
- translated_service: { name: translated_service },
1465
- inbound_interface: { name: inbound_interface },
1466
- outbound_interface: { name: outbound_interface }
1493
+ source: await resolveRef(client, "address", original_source, ip_version, false),
1494
+ translated_source: await resolveRef(client, "address", translated_source, ip_version, true),
1495
+ destination: await resolveRef(client, "address", original_destination, ip_version, false),
1496
+ translated_destination: await resolveRef(client, "address", translated_destination, ip_version, true),
1497
+ service: await resolveRef(client, "service", original_service, ip_version, false),
1498
+ translated_service: await resolveRef(client, "service", translated_service, ip_version, true),
1499
+ inbound: interfaceValue(inbound_interface),
1500
+ outbound: interfaceValue(outbound_interface),
1501
+ dns_doctoring
1467
1502
  };
1468
1503
  if (comment) policy.comment = comment;
1504
+ if (priority !== void 0) policy.priority = priorityField(priority);
1469
1505
  const result = await client.post(`nat-policies/${ip_version}`, {
1470
1506
  nat_policies: [{ [ip_version]: policy }]
1471
1507
  });
@@ -1477,9 +1513,9 @@ function registerNatPolicyTools(server, registry) {
1477
1513
  );
1478
1514
  server.tool(
1479
1515
  "update_nat_policy",
1480
- "Update fields on an existing NAT policy (GET-then-PUT). Changes are STAGED; call commit_config to apply.",
1516
+ "Update a NAT policy selected by UUID (GET-then-PUT). Pass a policy's uuid value from list_nat_policies as policy_uuid. dns_doctoring can be changed independently. priority changes rule order (lower number = evaluated first; 'auto' lets SonicOS assign it). Position 1 is held by the built-in IKE policy, so use 2 or higher; an unavailable priority can return success yet be ignored, so confirm with get_nat_policy. Changes are STAGED; call commit_config to apply.",
1481
1517
  {
1482
- policy_id: import_zod7.z.number(),
1518
+ policy_uuid: import_zod7.z.string().uuid(),
1483
1519
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1484
1520
  original_source: import_zod7.z.string().optional(),
1485
1521
  translated_source: import_zod7.z.string().optional(),
@@ -1490,26 +1526,31 @@ function registerNatPolicyTools(server, registry) {
1490
1526
  inbound_interface: import_zod7.z.string().optional(),
1491
1527
  outbound_interface: import_zod7.z.string().optional(),
1492
1528
  enabled: import_zod7.z.boolean().optional(),
1529
+ dns_doctoring: import_zod7.z.boolean().optional(),
1530
+ priority: prioritySchema,
1493
1531
  comment: import_zod7.z.string().optional(),
1494
1532
  device: import_zod7.z.string().optional()
1495
1533
  },
1496
- async ({ policy_id, ip_version, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, enabled, comment, device }) => {
1534
+ async ({ policy_uuid, ip_version, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, enabled, dns_doctoring, priority, comment, device }) => {
1497
1535
  try {
1498
1536
  const client = await registry.getClient(device);
1499
- const current = await client.get(`nat-policies/${ip_version}/${policy_id}`);
1537
+ const path = `nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`;
1538
+ const current = await client.get(path);
1500
1539
  const policies = current.nat_policies;
1501
1540
  const policy = policies?.[0]?.[ip_version] ?? {};
1502
- setNameField(policy, "original_source", original_source);
1503
- setNameField(policy, "translated_source", translated_source);
1504
- setNameField(policy, "original_destination", original_destination);
1505
- setNameField(policy, "translated_destination", translated_destination);
1506
- setNameField(policy, "original_service", original_service);
1507
- setNameField(policy, "translated_service", translated_service);
1508
- setNameField(policy, "inbound_interface", inbound_interface);
1509
- setNameField(policy, "outbound_interface", outbound_interface);
1541
+ if (original_source !== void 0) policy.source = await resolveRef(client, "address", original_source, ip_version, false);
1542
+ if (translated_source !== void 0) policy.translated_source = await resolveRef(client, "address", translated_source, ip_version, true);
1543
+ if (original_destination !== void 0) policy.destination = await resolveRef(client, "address", original_destination, ip_version, false);
1544
+ if (translated_destination !== void 0) policy.translated_destination = await resolveRef(client, "address", translated_destination, ip_version, true);
1545
+ if (original_service !== void 0) policy.service = await resolveRef(client, "service", original_service, ip_version, false);
1546
+ if (translated_service !== void 0) policy.translated_service = await resolveRef(client, "service", translated_service, ip_version, true);
1547
+ if (inbound_interface !== void 0) policy.inbound = interfaceValue(inbound_interface);
1548
+ if (outbound_interface !== void 0) policy.outbound = interfaceValue(outbound_interface);
1510
1549
  if (enabled !== void 0) policy.enable = enabled;
1550
+ if (dns_doctoring !== void 0) policy.dns_doctoring = dns_doctoring;
1511
1551
  if (comment !== void 0) policy.comment = comment;
1512
- const result = await client.put(`nat-policies/${ip_version}/${policy_id}`, {
1552
+ if (priority !== void 0) policy.priority = priorityField(priority);
1553
+ const result = await client.put(path, {
1513
1554
  nat_policies: [{ [ip_version]: policy }]
1514
1555
  });
1515
1556
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1520,16 +1561,59 @@ function registerNatPolicyTools(server, registry) {
1520
1561
  );
1521
1562
  server.tool(
1522
1563
  "delete_nat_policy",
1523
- "Delete a NAT policy by ID. Changes are STAGED; call commit_config to apply.",
1564
+ "Delete a NAT policy by UUID. Copy policy_uuid from list_nat_policies. Changes are STAGED; call commit_config to apply.",
1524
1565
  {
1525
- policy_id: import_zod7.z.number(),
1566
+ policy_uuid: import_zod7.z.string().uuid(),
1526
1567
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1527
1568
  device: import_zod7.z.string().optional()
1528
1569
  },
1529
- async ({ policy_id, ip_version, device }) => {
1570
+ async ({ policy_uuid, ip_version, device }) => {
1530
1571
  try {
1531
1572
  const client = await registry.getClient(device);
1532
- const result = await client.delete(`nat-policies/${ip_version}/${policy_id}`);
1573
+ const result = await client.delete(`nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`);
1574
+ return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1575
+ } catch (e) {
1576
+ return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1577
+ }
1578
+ }
1579
+ );
1580
+ async function setNatPolicyEnabled(policyUuid, ipVersion, enabled, device) {
1581
+ const client = await registry.getClient(device);
1582
+ const path = `nat-policies/${ipVersion}/uuid/${encodeURIComponent(policyUuid)}`;
1583
+ const current = await client.get(path);
1584
+ const policies = current.nat_policies;
1585
+ const policy = policies?.[0]?.[ipVersion] ?? {};
1586
+ policy.enable = enabled;
1587
+ return client.put(path, { nat_policies: [{ [ipVersion]: policy }] });
1588
+ }
1589
+ server.tool(
1590
+ "enable_nat_policy",
1591
+ "Enable a NAT policy selected by UUID without modifying other fields. Copy policy_uuid from list_nat_policies. Changes are STAGED; call commit_config to apply.",
1592
+ {
1593
+ policy_uuid: import_zod7.z.string().uuid(),
1594
+ ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1595
+ device: import_zod7.z.string().optional()
1596
+ },
1597
+ async ({ policy_uuid, ip_version, device }) => {
1598
+ try {
1599
+ const result = await setNatPolicyEnabled(policy_uuid, ip_version, true, device);
1600
+ return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1601
+ } catch (e) {
1602
+ return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1603
+ }
1604
+ }
1605
+ );
1606
+ server.tool(
1607
+ "disable_nat_policy",
1608
+ "Disable a NAT policy selected by UUID without deleting it. Copy policy_uuid from list_nat_policies. Changes are STAGED; call commit_config to apply.",
1609
+ {
1610
+ policy_uuid: import_zod7.z.string().uuid(),
1611
+ ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1612
+ device: import_zod7.z.string().optional()
1613
+ },
1614
+ async ({ policy_uuid, ip_version, device }) => {
1615
+ try {
1616
+ const result = await setNatPolicyEnabled(policy_uuid, ip_version, false, device);
1533
1617
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1534
1618
  } catch (e) {
1535
1619
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1771,145 +1855,47 @@ function registerGeoIpTools(server, registry) {
1771
1855
 
1772
1856
  // src/tools/logs.ts
1773
1857
  var import_zod10 = require("zod");
1774
- async function getLogsWithFallback(client, candidates, params) {
1775
- let lastErr;
1858
+ async function getWithFallback(client, candidates) {
1859
+ let lastError;
1776
1860
  for (const path of candidates) {
1777
1861
  try {
1778
- return await client.get(path, params);
1779
- } catch (e) {
1780
- if (e instanceof APIError && (e.status === 404 || e.status === 400)) {
1781
- lastErr = e;
1862
+ return await client.get(path);
1863
+ } catch (error) {
1864
+ if (error instanceof APIError && (error.status === 400 || error.status === 404)) {
1865
+ lastError = error;
1782
1866
  continue;
1783
1867
  }
1784
- throw e;
1868
+ throw error;
1785
1869
  }
1786
1870
  }
1787
- throw lastErr;
1871
+ throw lastError;
1788
1872
  }
1789
- var EVENT_LOG_PATHS = ["log/events", "reporting/log/events"];
1790
1873
  function registerLogTools(server, registry) {
1791
1874
  server.tool(
1792
1875
  "get_log_categories",
1793
- "Return the list of available log category names for use with get_event_logs.",
1876
+ "List SonicOS log category configuration. This describes available event categories; it does not return recorded runtime log entries.",
1794
1877
  { device: import_zod10.z.string().optional() },
1795
1878
  async ({ device }) => {
1796
1879
  try {
1797
1880
  const client = await registry.getClient(device);
1798
- try {
1799
- const result = await getLogsWithFallback(
1800
- client,
1801
- ["log/categories", "reporting/log/categories"],
1802
- {}
1803
- );
1804
- return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1805
- } catch (e) {
1806
- if (e instanceof APIError && (e.status === 404 || e.status === 400)) {
1807
- const fallback = {
1808
- categories: [
1809
- "network access",
1810
- "firewall",
1811
- "vpn",
1812
- "system",
1813
- "security",
1814
- "IPS",
1815
- "anti-virus",
1816
- "anti-spyware",
1817
- "application control",
1818
- "content filter",
1819
- "decryption",
1820
- "geoip",
1821
- "authentication"
1822
- ]
1823
- };
1824
- return { content: [{ type: "text", text: JSON.stringify(fallback, null, 2) }] };
1825
- }
1826
- throw e;
1827
- }
1828
- } catch (e) {
1829
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1830
- }
1831
- }
1832
- );
1833
- server.tool(
1834
- "get_event_logs",
1835
- "Retrieve system/event logs from the appliance. count: max entries (default 100). category: e.g. 'network access', 'system', 'vpn'. priority: emergency/alert/critical/error/warning/notice/info/debug. start_time/end_time: ISO 8601. source_ip: filter by source IP. keyword: full-text search.",
1836
- {
1837
- count: import_zod10.z.number().optional().default(100),
1838
- category: import_zod10.z.string().optional(),
1839
- priority: import_zod10.z.enum(["emergency", "alert", "critical", "error", "warning", "notice", "info", "debug"]).optional(),
1840
- start_time: import_zod10.z.string().optional(),
1841
- end_time: import_zod10.z.string().optional(),
1842
- source_ip: import_zod10.z.string().optional(),
1843
- keyword: import_zod10.z.string().optional(),
1844
- device: import_zod10.z.string().optional()
1845
- },
1846
- async ({ count, category, priority, start_time, end_time, source_ip, keyword, device }) => {
1847
- try {
1848
- const client = await registry.getClient(device);
1849
- const params = { count };
1850
- if (category) params.category = category;
1851
- if (priority) params.priority = priority;
1852
- if (start_time) params.start_time = start_time;
1853
- if (end_time) params.end_time = end_time;
1854
- if (source_ip) params.src_ip = source_ip;
1855
- if (keyword) params.keyword = keyword;
1856
- const result = await getLogsWithFallback(client, EVENT_LOG_PATHS, params);
1857
- return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1858
- } catch (e) {
1859
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1860
- }
1861
- }
1862
- );
1863
- server.tool(
1864
- "search_logs",
1865
- "Full-text keyword search across event logs. query: text to search. count: max entries.",
1866
- {
1867
- query: import_zod10.z.string(),
1868
- count: import_zod10.z.number().optional().default(200),
1869
- start_time: import_zod10.z.string().optional(),
1870
- end_time: import_zod10.z.string().optional(),
1871
- device: import_zod10.z.string().optional()
1872
- },
1873
- async ({ query, count, start_time, end_time, device }) => {
1874
- try {
1875
- const client = await registry.getClient(device);
1876
- const params = { count, keyword: query };
1877
- if (start_time) params.start_time = start_time;
1878
- if (end_time) params.end_time = end_time;
1879
- const result = await getLogsWithFallback(client, EVENT_LOG_PATHS, params);
1881
+ const result = await getWithFallback(client, ["log/categories", "reporting/log/categories"]);
1880
1882
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1881
- } catch (e) {
1882
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1883
+ } catch (error) {
1884
+ return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
1883
1885
  }
1884
1886
  }
1885
1887
  );
1886
1888
  server.tool(
1887
- "get_threat_logs",
1888
- "Retrieve IPS and threat-detection log events (filters by IPS category). severity maps to SonicOS priority levels: 'critical'\u2192critical, 'high'\u2192error, 'medium'\u2192warning, 'low'\u2192notice.",
1889
- {
1890
- count: import_zod10.z.number().optional().default(50),
1891
- severity: import_zod10.z.enum(["critical", "high", "medium", "low"]).optional(),
1892
- start_time: import_zod10.z.string().optional(),
1893
- end_time: import_zod10.z.string().optional(),
1894
- device: import_zod10.z.string().optional()
1895
- },
1896
- async ({ count, severity, start_time, end_time, device }) => {
1889
+ "list_log_event_definitions",
1890
+ "List SonicOS event-definition configuration (event names, categories, priorities, and alert/syslog settings). This is not the appliance event history and cannot be searched by IP, message, or timestamp.",
1891
+ { device: import_zod10.z.string().optional() },
1892
+ async ({ device }) => {
1897
1893
  try {
1898
1894
  const client = await registry.getClient(device);
1899
- const severityToPriority = {
1900
- critical: "critical",
1901
- high: "error",
1902
- medium: "warning",
1903
- low: "notice"
1904
- };
1905
- const params = { count, category: "IPS" };
1906
- if (severity) params.priority = severityToPriority[severity];
1907
- if (start_time) params.start_time = start_time;
1908
- if (end_time) params.end_time = end_time;
1909
- const result = await getLogsWithFallback(client, EVENT_LOG_PATHS, params);
1895
+ const result = await getWithFallback(client, ["log/events", "reporting/log/events"]);
1910
1896
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1911
- } catch (e) {
1912
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1897
+ } catch (error) {
1898
+ return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
1913
1899
  }
1914
1900
  }
1915
1901
  );
@@ -2055,7 +2041,7 @@ async function main() {
2055
2041
  const registry = new DeviceRegistry(config.profiles);
2056
2042
  const server = new import_mcp.McpServer({
2057
2043
  name: "sonicwall-mcp-server",
2058
- version: "0.5.1",
2044
+ version: "0.7.0",
2059
2045
  instructions: `SonicWall NSA MCP server \u2014 full read/write access to SonicWall firewalls via the SonicOS REST API.
2060
2046
 
2061
2047
  ## Device targeting
@@ -2064,22 +2050,16 @@ Use list_devices to discover available appliances and their names. Pass device='
2064
2050
  ## Staged configuration
2065
2051
  IMPORTANT: All create/update/delete operations are STAGED and do not take effect until you call commit_config. Call discard_config to abandon staged changes. Always commit after completing a related set of changes, or discard if the user changes their mind. Never leave uncommitted changes unless the user explicitly asks to review before committing.
2066
2052
 
2067
- ## Datetime handling
2068
- All timestamp parameters (start_time, end_time in log tools) are in the appliance's LOCAL timezone \u2014 SonicWall stores and filters logs using its own configured clock. Do not convert to UTC. Pass wall-clock time as the user states it, e.g. '2025-04-01T00:00:00'. Log timestamps in responses are also in the appliance's local timezone.
2069
-
2070
- ## Log querying
2071
- - Call get_log_categories first to discover valid category names for get_event_logs.
2072
- - get_event_logs: general system/security events. Filter by category, priority, source_ip, or keyword.
2073
- - get_threat_logs: IPS and AV detections. Filter by severity.
2074
- - search_logs: full-text keyword search across event logs \u2014 use when you have a specific IP, hostname, or error string.
2075
- - Default count is 100. Increase for broader searches, but keep it reasonable to avoid large payloads.
2053
+ ## Log configuration
2054
+ - get_log_categories and list_log_event_definitions return logging configuration, not recorded event history.
2055
+ - SonicOS does not expose runtime event, threat, connection, or traffic history through the documented REST API. Do not use these tools to search for IP addresses or incidents.
2076
2056
 
2077
2057
  ## Object and rule management
2078
2058
  - Address objects (IPv4/IPv6/FQDN/MAC) and groups are the building blocks of access rules and NAT policies. Use list_address_objects / list_address_groups to discover existing objects before creating rules.
2079
2059
  - Service objects define protocol/port combinations. Use list_service_objects and list_service_groups to discover available services before referencing them in rules.
2080
2060
  - Typical workflow for a new firewall rule: list_address_objects \u2192 create_address_object_ipv4/fqdn/etc if needed \u2192 list_service_objects \u2192 create_service_object if needed \u2192 create_access_rule \u2192 commit_config.
2081
2061
  - 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.
2082
- - Always call list_access_rules, list_nat_policies, or list_security_policies before modifying, to confirm current state and avoid duplicates.
2062
+ - 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.
2083
2063
  - 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.
2084
2064
  - 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.
2085
2065
 
package/package.json CHANGED
@@ -1,51 +1,51 @@
1
- {
2
- "name": "@teamnetwork-nz/sonicwall-api-mcp-server",
3
- "version": "0.5.1",
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
- "repository": {
22
- "type": "git",
23
- "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
24
- },
25
- "main": "dist/index.js",
26
- "bin": {
27
- "sonicwall-mcp": "./dist/index.js"
28
- },
29
- "files": [
30
- "dist/",
31
- "README.md",
32
- "LICENSE"
33
- ],
34
- "scripts": {
35
- "build": "tsup",
36
- "prepublishOnly": "npm run build",
37
- "start": "node dist/index.js"
38
- },
39
- "engines": {
40
- "node": ">=18"
41
- },
42
- "dependencies": {
43
- "@modelcontextprotocol/sdk": "^1.10.0",
44
- "zod": "^3.23.0"
45
- },
46
- "devDependencies": {
47
- "@types/node": "^20.0.0",
48
- "tsup": "^8.0.0",
49
- "typescript": "^5.4.0"
50
- }
51
- }
1
+ {
2
+ "name": "@teamnetwork-nz/sonicwall-api-mcp-server",
3
+ "version": "0.7.0",
4
+ "description": "MCP server for SonicWall NSA appliance configuration — objects, rules, NAT, routing, 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
+ "author": "Daryl",
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
24
+ },
25
+ "main": "dist/index.js",
26
+ "bin": {
27
+ "sonicwall-mcp": "./dist/index.js"
28
+ },
29
+ "files": [
30
+ "dist/",
31
+ "README.md",
32
+ "LICENSE"
33
+ ],
34
+ "scripts": {
35
+ "build": "tsup",
36
+ "prepublishOnly": "npm run build",
37
+ "start": "node dist/index.js"
38
+ },
39
+ "engines": {
40
+ "node": ">=18"
41
+ },
42
+ "dependencies": {
43
+ "@modelcontextprotocol/sdk": "^1.10.0",
44
+ "zod": "^3.23.0"
45
+ },
46
+ "devDependencies": {
47
+ "@types/node": "^20.0.0",
48
+ "tsup": "^8.0.0",
49
+ "typescript": "^5.4.0"
50
+ }
51
+ }