@teamnetwork-nz/sonicwall-api-mcp-server 0.5.1 → 0.6.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 +124 -177
  3. package/package.json +2 -2
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
@@ -1180,7 +1180,7 @@ function matchesZone(value, filter) {
1180
1180
  function registerAccessRuleTools(server, registry) {
1181
1181
  server.tool(
1182
1182
  "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.",
1183
+ "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
1184
  {
1185
1185
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1186
1186
  from_zone: import_zod6.z.string().optional(),
@@ -1211,16 +1211,16 @@ function registerAccessRuleTools(server, registry) {
1211
1211
  );
1212
1212
  server.tool(
1213
1213
  "get_access_rule",
1214
- "Retrieve a single access rule by its numeric ID.",
1214
+ "Retrieve a single access rule by UUID. Pass a rule's uuid value from list_access_rules as rule_uuid.",
1215
1215
  {
1216
- rule_id: import_zod6.z.number(),
1216
+ rule_uuid: import_zod6.z.string().uuid(),
1217
1217
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1218
1218
  device: import_zod6.z.string().optional()
1219
1219
  },
1220
- async ({ rule_id, ip_version, device }) => {
1220
+ async ({ rule_uuid, ip_version, device }) => {
1221
1221
  try {
1222
1222
  const client = await registry.getClient(device);
1223
- const result = await client.get(`access-rules/${ip_version}/${rule_id}`);
1223
+ const result = await client.get(`access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`);
1224
1224
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1225
1225
  } catch (e) {
1226
1226
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1274,9 +1274,9 @@ function registerAccessRuleTools(server, registry) {
1274
1274
  );
1275
1275
  server.tool(
1276
1276
  "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.",
1277
+ "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
1278
  {
1279
- rule_id: import_zod6.z.number(),
1279
+ rule_uuid: import_zod6.z.string().uuid(),
1280
1280
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1281
1281
  action: import_zod6.z.enum(["allow", "deny", "discard"]).optional(),
1282
1282
  source: import_zod6.z.string().optional(),
@@ -1288,10 +1288,11 @@ function registerAccessRuleTools(server, registry) {
1288
1288
  comment: import_zod6.z.string().optional(),
1289
1289
  device: import_zod6.z.string().optional()
1290
1290
  },
1291
- async ({ rule_id, ip_version, action, source, destination, service, enabled, log, geo_ip_policy, comment, device }) => {
1291
+ async ({ rule_uuid, ip_version, action, source, destination, service, enabled, log, geo_ip_policy, comment, device }) => {
1292
1292
  try {
1293
1293
  const client = await registry.getClient(device);
1294
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1294
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1295
+ const current = await client.get(path);
1295
1296
  const rules = current.access_rules;
1296
1297
  const rule = rules?.[0]?.[ip_version] ?? {};
1297
1298
  if (action !== void 0) rule.action = action;
@@ -1314,7 +1315,7 @@ function registerAccessRuleTools(server, registry) {
1314
1315
  rule.security_profile = { geo_ip_policy: { name: geo_ip_policy } };
1315
1316
  }
1316
1317
  }
1317
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1318
+ const result = await client.put(path, {
1318
1319
  access_rules: [{ [ip_version]: rule }]
1319
1320
  });
1320
1321
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1325,16 +1326,16 @@ function registerAccessRuleTools(server, registry) {
1325
1326
  );
1326
1327
  server.tool(
1327
1328
  "delete_access_rule",
1328
- "Delete an access rule by ID. Changes are STAGED; call commit_config to apply.",
1329
+ "Delete an access rule by UUID. Copy rule_uuid from list_access_rules. Changes are STAGED; call commit_config to apply.",
1329
1330
  {
1330
- rule_id: import_zod6.z.number(),
1331
+ rule_uuid: import_zod6.z.string().uuid(),
1331
1332
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1332
1333
  device: import_zod6.z.string().optional()
1333
1334
  },
1334
- async ({ rule_id, ip_version, device }) => {
1335
+ async ({ rule_uuid, ip_version, device }) => {
1335
1336
  try {
1336
1337
  const client = await registry.getClient(device);
1337
- const result = await client.delete(`access-rules/${ip_version}/${rule_id}`);
1338
+ const result = await client.delete(`access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`);
1338
1339
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1339
1340
  } catch (e) {
1340
1341
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1343,20 +1344,21 @@ function registerAccessRuleTools(server, registry) {
1343
1344
  );
1344
1345
  server.tool(
1345
1346
  "enable_access_rule",
1346
- "Enable a disabled access rule without modifying any other fields. Changes are STAGED; call commit_config to apply.",
1347
+ "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
1348
  {
1348
- rule_id: import_zod6.z.number(),
1349
+ rule_uuid: import_zod6.z.string().uuid(),
1349
1350
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1350
1351
  device: import_zod6.z.string().optional()
1351
1352
  },
1352
- async ({ rule_id, ip_version, device }) => {
1353
+ async ({ rule_uuid, ip_version, device }) => {
1353
1354
  try {
1354
1355
  const client = await registry.getClient(device);
1355
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1356
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1357
+ const current = await client.get(path);
1356
1358
  const rules = current.access_rules;
1357
1359
  const rule = rules?.[0]?.[ip_version] ?? {};
1358
1360
  rule.enable = true;
1359
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1361
+ const result = await client.put(path, {
1360
1362
  access_rules: [{ [ip_version]: rule }]
1361
1363
  });
1362
1364
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1367,20 +1369,21 @@ function registerAccessRuleTools(server, registry) {
1367
1369
  );
1368
1370
  server.tool(
1369
1371
  "disable_access_rule",
1370
- "Disable an access rule without deleting it. Changes are STAGED; call commit_config to apply.",
1372
+ "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
1373
  {
1372
- rule_id: import_zod6.z.number(),
1374
+ rule_uuid: import_zod6.z.string().uuid(),
1373
1375
  ip_version: import_zod6.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1374
1376
  device: import_zod6.z.string().optional()
1375
1377
  },
1376
- async ({ rule_id, ip_version, device }) => {
1378
+ async ({ rule_uuid, ip_version, device }) => {
1377
1379
  try {
1378
1380
  const client = await registry.getClient(device);
1379
- const current = await client.get(`access-rules/${ip_version}/${rule_id}`);
1381
+ const path = `access-rules/${ip_version}/uuid/${encodeURIComponent(rule_uuid)}`;
1382
+ const current = await client.get(path);
1380
1383
  const rules = current.access_rules;
1381
1384
  const rule = rules?.[0]?.[ip_version] ?? {};
1382
1385
  rule.enable = false;
1383
- const result = await client.put(`access-rules/${ip_version}/${rule_id}`, {
1386
+ const result = await client.put(path, {
1384
1387
  access_rules: [{ [ip_version]: rule }]
1385
1388
  });
1386
1389
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1399,7 +1402,7 @@ function setNameField(obj, key, value) {
1399
1402
  function registerNatPolicyTools(server, registry) {
1400
1403
  server.tool(
1401
1404
  "list_nat_policies",
1402
- "List all NAT policies. ip_version: 'ipv4' (default) or 'ipv6'.",
1405
+ "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
1406
  {
1404
1407
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1405
1408
  device: import_zod7.z.string().optional()
@@ -1416,16 +1419,16 @@ function registerNatPolicyTools(server, registry) {
1416
1419
  );
1417
1420
  server.tool(
1418
1421
  "get_nat_policy",
1419
- "Retrieve a NAT policy by its numeric ID.",
1422
+ "Retrieve a NAT policy by UUID. Pass a policy's uuid value from list_nat_policies as policy_uuid.",
1420
1423
  {
1421
- policy_id: import_zod7.z.number(),
1424
+ policy_uuid: import_zod7.z.string().uuid(),
1422
1425
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1423
1426
  device: import_zod7.z.string().optional()
1424
1427
  },
1425
- async ({ policy_id, ip_version, device }) => {
1428
+ async ({ policy_uuid, ip_version, device }) => {
1426
1429
  try {
1427
1430
  const client = await registry.getClient(device);
1428
- const result = await client.get(`nat-policies/${ip_version}/${policy_id}`);
1431
+ const result = await client.get(`nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`);
1429
1432
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1430
1433
  } catch (e) {
1431
1434
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1447,23 +1450,25 @@ function registerNatPolicyTools(server, registry) {
1447
1450
  outbound_interface: import_zod7.z.string().optional().default("Any"),
1448
1451
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1449
1452
  enabled: import_zod7.z.boolean().optional().default(true),
1453
+ dns_doctoring: import_zod7.z.boolean().optional().default(false),
1450
1454
  comment: import_zod7.z.string().optional(),
1451
1455
  device: import_zod7.z.string().optional()
1452
1456
  },
1453
- async ({ name, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, ip_version, enabled, comment, device }) => {
1457
+ async ({ name, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, ip_version, enabled, dns_doctoring, comment, device }) => {
1454
1458
  try {
1455
1459
  const client = await registry.getClient(device);
1456
1460
  const policy = {
1457
1461
  name,
1458
1462
  enable: enabled,
1459
- original_source: { name: original_source },
1463
+ source: { name: original_source },
1460
1464
  translated_source: { name: translated_source },
1461
- original_destination: { name: original_destination },
1465
+ destination: { name: original_destination },
1462
1466
  translated_destination: { name: translated_destination },
1463
- original_service: { name: original_service },
1467
+ service: { name: original_service },
1464
1468
  translated_service: { name: translated_service },
1465
- inbound_interface: { name: inbound_interface },
1466
- outbound_interface: { name: outbound_interface }
1469
+ inbound: { name: inbound_interface },
1470
+ outbound: { name: outbound_interface },
1471
+ dns_doctoring
1467
1472
  };
1468
1473
  if (comment) policy.comment = comment;
1469
1474
  const result = await client.post(`nat-policies/${ip_version}`, {
@@ -1477,9 +1482,9 @@ function registerNatPolicyTools(server, registry) {
1477
1482
  );
1478
1483
  server.tool(
1479
1484
  "update_nat_policy",
1480
- "Update fields on an existing NAT policy (GET-then-PUT). Changes are STAGED; call commit_config to apply.",
1485
+ "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. Changes are STAGED; call commit_config to apply.",
1481
1486
  {
1482
- policy_id: import_zod7.z.number(),
1487
+ policy_uuid: import_zod7.z.string().uuid(),
1483
1488
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1484
1489
  original_source: import_zod7.z.string().optional(),
1485
1490
  translated_source: import_zod7.z.string().optional(),
@@ -1490,26 +1495,29 @@ function registerNatPolicyTools(server, registry) {
1490
1495
  inbound_interface: import_zod7.z.string().optional(),
1491
1496
  outbound_interface: import_zod7.z.string().optional(),
1492
1497
  enabled: import_zod7.z.boolean().optional(),
1498
+ dns_doctoring: import_zod7.z.boolean().optional(),
1493
1499
  comment: import_zod7.z.string().optional(),
1494
1500
  device: import_zod7.z.string().optional()
1495
1501
  },
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 }) => {
1502
+ async ({ policy_uuid, ip_version, original_source, translated_source, original_destination, translated_destination, original_service, translated_service, inbound_interface, outbound_interface, enabled, dns_doctoring, comment, device }) => {
1497
1503
  try {
1498
1504
  const client = await registry.getClient(device);
1499
- const current = await client.get(`nat-policies/${ip_version}/${policy_id}`);
1505
+ const path = `nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`;
1506
+ const current = await client.get(path);
1500
1507
  const policies = current.nat_policies;
1501
1508
  const policy = policies?.[0]?.[ip_version] ?? {};
1502
- setNameField(policy, "original_source", original_source);
1509
+ setNameField(policy, "source", original_source);
1503
1510
  setNameField(policy, "translated_source", translated_source);
1504
- setNameField(policy, "original_destination", original_destination);
1511
+ setNameField(policy, "destination", original_destination);
1505
1512
  setNameField(policy, "translated_destination", translated_destination);
1506
- setNameField(policy, "original_service", original_service);
1513
+ setNameField(policy, "service", original_service);
1507
1514
  setNameField(policy, "translated_service", translated_service);
1508
- setNameField(policy, "inbound_interface", inbound_interface);
1509
- setNameField(policy, "outbound_interface", outbound_interface);
1515
+ setNameField(policy, "inbound", inbound_interface);
1516
+ setNameField(policy, "outbound", outbound_interface);
1510
1517
  if (enabled !== void 0) policy.enable = enabled;
1518
+ if (dns_doctoring !== void 0) policy.dns_doctoring = dns_doctoring;
1511
1519
  if (comment !== void 0) policy.comment = comment;
1512
- const result = await client.put(`nat-policies/${ip_version}/${policy_id}`, {
1520
+ const result = await client.put(path, {
1513
1521
  nat_policies: [{ [ip_version]: policy }]
1514
1522
  });
1515
1523
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
@@ -1520,16 +1528,59 @@ function registerNatPolicyTools(server, registry) {
1520
1528
  );
1521
1529
  server.tool(
1522
1530
  "delete_nat_policy",
1523
- "Delete a NAT policy by ID. Changes are STAGED; call commit_config to apply.",
1531
+ "Delete a NAT policy by UUID. Copy policy_uuid from list_nat_policies. Changes are STAGED; call commit_config to apply.",
1524
1532
  {
1525
- policy_id: import_zod7.z.number(),
1533
+ policy_uuid: import_zod7.z.string().uuid(),
1526
1534
  ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1527
1535
  device: import_zod7.z.string().optional()
1528
1536
  },
1529
- async ({ policy_id, ip_version, device }) => {
1537
+ async ({ policy_uuid, ip_version, device }) => {
1530
1538
  try {
1531
1539
  const client = await registry.getClient(device);
1532
- const result = await client.delete(`nat-policies/${ip_version}/${policy_id}`);
1540
+ const result = await client.delete(`nat-policies/${ip_version}/uuid/${encodeURIComponent(policy_uuid)}`);
1541
+ return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1542
+ } catch (e) {
1543
+ return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1544
+ }
1545
+ }
1546
+ );
1547
+ async function setNatPolicyEnabled(policyUuid, ipVersion, enabled, device) {
1548
+ const client = await registry.getClient(device);
1549
+ const path = `nat-policies/${ipVersion}/uuid/${encodeURIComponent(policyUuid)}`;
1550
+ const current = await client.get(path);
1551
+ const policies = current.nat_policies;
1552
+ const policy = policies?.[0]?.[ipVersion] ?? {};
1553
+ policy.enable = enabled;
1554
+ return client.put(path, { nat_policies: [{ [ipVersion]: policy }] });
1555
+ }
1556
+ server.tool(
1557
+ "enable_nat_policy",
1558
+ "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.",
1559
+ {
1560
+ policy_uuid: import_zod7.z.string().uuid(),
1561
+ ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1562
+ device: import_zod7.z.string().optional()
1563
+ },
1564
+ async ({ policy_uuid, ip_version, device }) => {
1565
+ try {
1566
+ const result = await setNatPolicyEnabled(policy_uuid, ip_version, true, device);
1567
+ return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1568
+ } catch (e) {
1569
+ return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1570
+ }
1571
+ }
1572
+ );
1573
+ server.tool(
1574
+ "disable_nat_policy",
1575
+ "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.",
1576
+ {
1577
+ policy_uuid: import_zod7.z.string().uuid(),
1578
+ ip_version: import_zod7.z.enum(["ipv4", "ipv6"]).optional().default("ipv4"),
1579
+ device: import_zod7.z.string().optional()
1580
+ },
1581
+ async ({ policy_uuid, ip_version, device }) => {
1582
+ try {
1583
+ const result = await setNatPolicyEnabled(policy_uuid, ip_version, false, device);
1533
1584
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1534
1585
  } catch (e) {
1535
1586
  return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
@@ -1771,145 +1822,47 @@ function registerGeoIpTools(server, registry) {
1771
1822
 
1772
1823
  // src/tools/logs.ts
1773
1824
  var import_zod10 = require("zod");
1774
- async function getLogsWithFallback(client, candidates, params) {
1775
- let lastErr;
1825
+ async function getWithFallback(client, candidates) {
1826
+ let lastError;
1776
1827
  for (const path of candidates) {
1777
1828
  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;
1829
+ return await client.get(path);
1830
+ } catch (error) {
1831
+ if (error instanceof APIError && (error.status === 400 || error.status === 404)) {
1832
+ lastError = error;
1782
1833
  continue;
1783
1834
  }
1784
- throw e;
1835
+ throw error;
1785
1836
  }
1786
1837
  }
1787
- throw lastErr;
1838
+ throw lastError;
1788
1839
  }
1789
- var EVENT_LOG_PATHS = ["log/events", "reporting/log/events"];
1790
1840
  function registerLogTools(server, registry) {
1791
1841
  server.tool(
1792
1842
  "get_log_categories",
1793
- "Return the list of available log category names for use with get_event_logs.",
1843
+ "List SonicOS log category configuration. This describes available event categories; it does not return recorded runtime log entries.",
1794
1844
  { device: import_zod10.z.string().optional() },
1795
1845
  async ({ device }) => {
1796
1846
  try {
1797
1847
  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);
1848
+ const result = await getWithFallback(client, ["log/categories", "reporting/log/categories"]);
1880
1849
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1881
- } catch (e) {
1882
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1850
+ } catch (error) {
1851
+ return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
1883
1852
  }
1884
1853
  }
1885
1854
  );
1886
1855
  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 }) => {
1856
+ "list_log_event_definitions",
1857
+ "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.",
1858
+ { device: import_zod10.z.string().optional() },
1859
+ async ({ device }) => {
1897
1860
  try {
1898
1861
  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);
1862
+ const result = await getWithFallback(client, ["log/events", "reporting/log/events"]);
1910
1863
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
1911
- } catch (e) {
1912
- return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
1864
+ } catch (error) {
1865
+ return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
1913
1866
  }
1914
1867
  }
1915
1868
  );
@@ -2055,7 +2008,7 @@ async function main() {
2055
2008
  const registry = new DeviceRegistry(config.profiles);
2056
2009
  const server = new import_mcp.McpServer({
2057
2010
  name: "sonicwall-mcp-server",
2058
- version: "0.5.1",
2011
+ version: "0.6.0",
2059
2012
  instructions: `SonicWall NSA MCP server \u2014 full read/write access to SonicWall firewalls via the SonicOS REST API.
2060
2013
 
2061
2014
  ## Device targeting
@@ -2064,22 +2017,16 @@ Use list_devices to discover available appliances and their names. Pass device='
2064
2017
  ## Staged configuration
2065
2018
  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
2019
 
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.
2020
+ ## Log configuration
2021
+ - get_log_categories and list_log_event_definitions return logging configuration, not recorded event history.
2022
+ - 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
2023
 
2077
2024
  ## Object and rule management
2078
2025
  - 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
2026
  - Service objects define protocol/port combinations. Use list_service_objects and list_service_groups to discover available services before referencing them in rules.
2080
2027
  - 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
2028
  - 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.
2029
+ - 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
2030
  - 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
2031
  - 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
2032
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
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",
3
+ "version": "0.6.0",
4
+ "description": "MCP server for SonicWall NSA appliance configuration — objects, rules, NAT, routing, and GeoIP lookup",
5
5
  "keywords": [
6
6
  "mcp",
7
7
  "model-context-protocol",