@usex/mikrotik-mcp 4.10.0 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usex/mikrotik-mcp",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "description": "MCP server for MikroTik RouterOS — 780+ tools over SSH for firewall, NAT, routing, DHCP, DNS, WireGuard, wireless, QoS and more.",
   "keywords": [
     "ai",
@@ -85,7 +85,7 @@
     "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tikoci/centrs": "^0.1.0",
-    "figlet": "^1.11.0",
+    "figlet": "^1.11.1",
     "gradient-string": "^3.0.0",
     "ipaddr.js": "^2.4.0",
     "ssh2": "^1.17.0",

package/prompts/setup-port-scan-detection.md

@@ -0,0 +1,109 @@
+---
+name: setup-port-scan-detection
+title: Set up port-scan detection (detect + tag, never block)
+description: Pick a device, present the six port-scan signatures, let the user choose which to enable, validate the trust list, then install them into a trust-excluding detect-portscan jump-gate — snapshotted and applied under Safe Mode. Detects and tags scanners; never blocks.
+arguments:
+  - name: device
+    description: Which configured device to protect (config key or label from list_mikrotik_devices). Omit to discover the devices and let the user choose.
+    required: false
+  - name: trusted_list_name
+    description: The existing management/trusted address-list on that device (e.g. Trust-IP). Omit to discover it and confirm with the user — it must already exist and contain the address you manage the device from.
+    required: false
+---
+
+You are setting up **port-scan detection** on a MikroTik router managed by this
+MCP server. These rules **detect and tag** a scanning source into an address list
+(default `port scanners`) — they **never drop or block** anything. Blocking is a
+separate, deliberately out-of-scope concern (see the closing note). The server may
+manage several routers, so establish which one first, and **never enable a
+signature the user did not explicitly choose.**
+
+Target device: {{device}}
+Trusted list: {{trusted_list_name}}
+
+## 0. Discover the device (do this FIRST)
+
+- Call `list_mikrotik_devices` to enumerate the configured routers (key, label,
+  transport target, default).
+- Resolve `{{device}}` against that inventory. If it doesn't match a known key or
+  label, STOP and show the list — never substitute a similar name. If it was
+  omitted, present the inventory and **ask which device to protect.** Pass that
+  device on every subsequent tool call.
+
+## 1. Present the catalog and get an EXPLICIT selection (mandatory)
+
+- Call `list_port_scan_detection_signatures` (with the chosen `device` so it also
+  reports which signatures are already present). Show the user **all six** with
+  their one-line descriptions and exact match syntax:
+  - `psd_generic` — "Port scanners to list" — RouterOS built-in PSD heuristic;
+    catches ordinary `nmap -sT/-sS` sweeps the flag signatures can't see.
+  - `nmap_fin_stealth` — "NMAP FIN Stealth scan" — lone FIN (`nmap -sF`).
+  - `syn_fin_scan` — "SYN/FIN scan" — impossible SYN+FIN combo.
+  - `syn_rst_scan` — "SYN/RST scan" — impossible SYN+RST combo.
+  - `fin_psh_urg_scan` — "FIN/PSH/URG scan" — Nmap `-sX` Xmas scan.
+  - `nmap_null_scan` — "NMAP NULL scan" — Nmap `-sN`, no flags set.
+- **Ask the user which specific signature IDs to enable.** Do NOT infer, do NOT
+  default to all six, do NOT default to none. Wait for an explicit list. There is
+  no select-all. A good default suggestion to offer (but still confirm): all six,
+  since they only tag and don't block — but the choice is the user's.
+
+## 2. Validate the trust list (pre-flight, before any write)
+
+The detection chain is gated by a single `input` jump that EXCLUDES a trusted
+address-list, so a trusted source is never tagged. That protection is only real if
+the trust list exists and contains your management address:
+
+- Determine `{{trusted_list_name}}` — the actual management/trusted list on THIS
+  device (commonly `Trust-IP`, but confirm; there is no default). If omitted, call
+  `list_address_lists` (`device=<name>`) and ask the user which list holds their
+  trusted management addresses.
+- Confirm with `list_address_lists` that the list **exists and is non-empty**. If
+  it is missing or empty, STOP: this design protects nothing without it. Guide the
+  user to create/populate it with their management address(es) first (e.g.
+  `add_address_list_entry list=<trusted_list_name> address=<your-mgmt-IP>`). Do NOT
+  auto-create or auto-populate it as part of this flow.
+- **Explicitly ask the human to confirm** that the address they are currently
+  managing this device from is in that list. The tool cannot know which IP you
+  connect from, so this is a human acknowledgement — you will pass it as
+  `confirmed_trusted_list_includes_my_ip=true`, and you may only set it after the
+  user has said yes.
+
+## 3. Apply (only after the selection + trust confirmation)
+
+- Call `add_port_scan_detection_rules` with:
+  - `device` = the chosen device,
+  - `rule_types` = **exactly** the signature IDs the user named (non-empty),
+  - `trusted_list_name` = the validated list,
+  - `address_list_name` (optional, default `"port scanners"`),
+  - `address_list_timeout` (optional, default `"2w"`),
+  - `confirm=true`,
+  - `confirmed_trusted_list_includes_my_ip=true`.
+- The tool: captures a config snapshot (returns a `snapshot_id`), creates the
+  `detect-portscan` chain if absent, installs the single trust-excluding jump —
+  positioned **before** the input default-deny (or appended after the management
+  accepts if there is none), inserts only the not-yet-present signatures, and
+  applies everything inside **Safe Mode** (auto-reverts if your session drops).
+- It is **idempotent**: re-running with the same selection adds nothing and reports
+  already-present rules. It will refuse if `rule_types` is empty, contains an
+  unknown value, or if the trust list is missing/empty.
+
+## 4. Verify management access (do not skip)
+
+- Present the tool's result: the `snapshot_id`, which signatures were added vs.
+  already present, the jump gate's position relative to the default-deny, and the
+  final `detect-portscan` chain.
+- **Instruct the user to verify their management access (SSH/Winbox/whatever they
+  use) from a SEPARATE, FRESH connection now**, before considering the change
+  final. Safe Mode's auto-revert is the safety net, but confirm no lockout. If
+  anything is wrong, roll back with
+  `diff_config_snapshots from=<snapshot_id> to=live` and the snapshot tools.
+- If the tool noted this device has **no input default-deny**, mention it as an
+  unrelated observation — do not fix it here (out of scope).
+
+## Scope — detection only
+
+These rules only populate the `port scanners` list; they do not block it. To turn
+that list into an active drop, use the separate, purpose-built
+`enforce_address_list_blocking` (Security Hardening) after confirming your trusted
+sources are safely excluded — never fold blocking into this detection step. Do not
+enable any signature the user didn't explicitly choose.

package/schemas/README.md

@@ -7,7 +7,7 @@ edit by hand — regenerate instead.
 | File | Contents |
 |------|----------|
 | `config.schema.json` | The runtime configuration object (env vars / CLI flags). |
-| `tool-catalog.json` | Every one of the 819 tools: `name`, `risk`, `title`, `description`, and input JSON Schema. |
+| `tool-catalog.json` | Every one of the 821 tools: `name`, `risk`, `title`, `description`, and input JSON Schema. |
 | `tools/<name>.json` | The input JSON Schema for a single tool. |
 
 `risk` is derived from the MCP tool annotations:

package/schemas/tool-catalog.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "generated": "by scripts/gen-schemas.ts — do not edit by hand",
-  "toolCount": 819,
+  "toolCount": 821,
   "tools": [
     {
       "name": "find_tools",
@@ -12780,9 +12780,11 @@
             "type": "string"
           },
           "in_interface": {
+            "description": "Match by inbound interface NAME (e.g. ether1, pppoe-out1) — NOT a chain and NOT an interface list. For an interface list use in_interface_list.",
             "type": "string"
           },
           "out_interface": {
+            "description": "Match by outbound interface NAME (e.g. ether1, pppoe-out1) — NOT a chain and NOT an interface list. For an interface list use out_interface_list.",
             "type": "string"
           },
           "connection_state": {
@@ -13075,9 +13077,11 @@
             "type": "string"
           },
           "in_interface": {
+            "description": "Inbound interface NAME (e.g. ether1) — not a chain; use in_interface_list for a list.",
             "type": "string"
           },
           "out_interface": {
+            "description": "Outbound interface NAME (e.g. ether1) — not a chain; use out_interface_list for a list.",
             "type": "string"
           },
           "connection_state": {
@@ -16015,6 +16019,89 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "list_port_scan_detection_signatures",
+      "title": "List Port-Scan Detection Signatures",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Read-only catalog of the six port-scan detection signatures this fleet can install (psd_generic, nmap_fin_stealth, syn_fin_scan, syn_rst_scan, fin_psh_urg_scan, nmap_null_scan) — each with its id, display name, one-line description and exact RouterOS match syntax. CALL THIS FIRST and show the user all six signatures with their descriptions. Do NOT proceed to add_port_scan_detection_rules until the user has explicitly named which specific signature IDs they want — never infer, never default to all six, never default to none. When `device` is supplied, also reports per signature whether it is already present in that device's detect-portscan chain. (On a multi-device server, target the device with the `device` selector this tool exposes.)",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "add_port_scan_detection_rules",
+      "title": "Add Port-Scan Detection Rules",
+      "risk": "dangerous",
+      "annotations": {
+        "destructiveHint": true,
+        "openWorldHint": false
+      },
+      "description": "Installs the user-selected port-scan detection signatures into a dedicated `detect-portscan` sub-chain, gated by a single input jump that EXCLUDES a trusted address-list (so trusted sources are never tagged). These rules only add the source to an address list — they NEVER drop or block. NEVER call this with a guessed or default set of rule_types: it must only be called with signature IDs the user explicitly chose after seeing list_port_scan_detection_signatures — there is no select-all. Requires `trusted_list_name` (must already exist and be non-empty on the device) and the human acknowledgement `confirmed_trusted_list_includes_my_ip=true`. Captures a config snapshot and applies every write inside Safe Mode (auto-revert on session drop). Idempotent — a second identical run adds nothing. Enforcement/blocking of the tagged list is intentionally out of scope.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "rule_types": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "psd_generic",
+                "nmap_fin_stealth",
+                "syn_fin_scan",
+                "syn_rst_scan",
+                "fin_psh_urg_scan",
+                "nmap_null_scan"
+              ]
+            },
+            "description": "REQUIRED, non-empty. The specific signature IDs the user explicitly chose after seeing the catalog. No default, no select-all — unknown values are rejected."
+          },
+          "trusted_list_name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "REQUIRED. The management/trusted address-list on THIS device (no default). Must already exist and contain at least one entry, or the call is refused."
+          },
+          "address_list_name": {
+            "default": "port scanners",
+            "description": "Address list detected scanners are tagged into (default \"port scanners\").",
+            "type": "string"
+          },
+          "address_list_timeout": {
+            "default": "2w",
+            "description": "How long a detected source stays tagged (default \"2w\").",
+            "type": "string"
+          },
+          "confirm": {
+            "type": "boolean",
+            "const": true,
+            "description": "Must be true to write."
+          },
+          "confirmed_trusted_list_includes_my_ip": {
+            "type": "boolean",
+            "const": true,
+            "description": "Human acknowledgement that the address you currently manage this device from is present in trusted_list_name. The tool cannot infer this — it must be explicitly true."
+          }
+        },
+        "required": [
+          "rule_types",
+          "trusted_list_name",
+          "address_list_name",
+          "address_list_timeout",
+          "confirm",
+          "confirmed_trusted_list_includes_my_ip"
+        ],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "setup_port_knock",
       "title": "Set Up Port-Knock Guardian",

package/schemas/tools/add_port_scan_detection_rules.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "add_port_scan_detection_rules",
+  "type": "object",
+  "properties": {
+    "rule_types": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "psd_generic",
+          "nmap_fin_stealth",
+          "syn_fin_scan",
+          "syn_rst_scan",
+          "fin_psh_urg_scan",
+          "nmap_null_scan"
+        ]
+      },
+      "description": "REQUIRED, non-empty. The specific signature IDs the user explicitly chose after seeing the catalog. No default, no select-all — unknown values are rejected."
+    },
+    "trusted_list_name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED. The management/trusted address-list on THIS device (no default). Must already exist and contain at least one entry, or the call is refused."
+    },
+    "address_list_name": {
+      "default": "port scanners",
+      "description": "Address list detected scanners are tagged into (default \"port scanners\").",
+      "type": "string"
+    },
+    "address_list_timeout": {
+      "default": "2w",
+      "description": "How long a detected source stays tagged (default \"2w\").",
+      "type": "string"
+    },
+    "confirm": {
+      "type": "boolean",
+      "const": true,
+      "description": "Must be true to write."
+    },
+    "confirmed_trusted_list_includes_my_ip": {
+      "type": "boolean",
+      "const": true,
+      "description": "Human acknowledgement that the address you currently manage this device from is present in trusted_list_name. The tool cannot infer this — it must be explicitly true."
+    }
+  },
+  "required": [
+    "rule_types",
+    "trusted_list_name",
+    "address_list_name",
+    "address_list_timeout",
+    "confirm",
+    "confirmed_trusted_list_includes_my_ip"
+  ],
+  "additionalProperties": false
+}

package/schemas/tools/create_filter_rule.json

@@ -41,9 +41,11 @@
       "type": "string"
     },
     "in_interface": {
+      "description": "Match by inbound interface NAME (e.g. ether1, pppoe-out1) — NOT a chain and NOT an interface list. For an interface list use in_interface_list.",
       "type": "string"
     },
     "out_interface": {
+      "description": "Match by outbound interface NAME (e.g. ether1, pppoe-out1) — NOT a chain and NOT an interface list. For an interface list use out_interface_list.",
       "type": "string"
     },
     "connection_state": {

package/schemas/tools/list_port_scan_detection_signatures.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "list_port_scan_detection_signatures",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/schemas/tools/update_filter_rule.json

@@ -28,9 +28,11 @@
       "type": "string"
     },
     "in_interface": {
+      "description": "Inbound interface NAME (e.g. ether1) — not a chain; use in_interface_list for a list.",
       "type": "string"
     },
     "out_interface": {
+      "description": "Outbound interface NAME (e.g. ether1) — not a chain; use out_interface_list for a list.",
       "type": "string"
     },
     "connection_state": {