@usex/mikrotik-mcp 4.24.0 → 5.0.0

package/README.md

@@ -1,20 +1,20 @@
 <div align="center">
   <img src="assets/logo.svg" alt="@usex/mikrotik-mcp" width="440" />
-  <p><strong>Drive one or more MikroTik routers in plain language — 819 risk-annotated tools your AI can call, over SSH.</strong><br/>
-  Firewall · routing · DHCP/DNS · wireless · QoS · a complete VPN suite · transactional Safe Mode · and a live observability dashboard that watches every call.</p>
+  <p><strong>Drive one or more MikroTik routers in plain language — 885 risk-annotated tools your AI can call, over SSH.</strong><br/>
+  Firewall · routing · DHCP/DNS · wireless · QoS · a complete VPN suite · transactional Safe Mode · live attack detection · and an observability dashboard that watches every call.</p>
 
   <p>
     <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-7C3AED.svg"></a>
     <img alt="Runtime: Bun" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3-06B6D4.svg">
     <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-6366F1.svg">
-    <img alt="MCP" src="https://img.shields.io/badge/MCP-819%20tools-1F2937.svg">
+    <img alt="MCP" src="https://img.shields.io/badge/MCP-885%20tools-1F2937.svg">
     <a href="docs/"><img alt="Docs" src="https://img.shields.io/badge/docs-reference-7C3AED.svg"></a>
   </p>
 </div>
 
 ---
 
-`@usex/mikrotik-mcp` turns **MikroTik RouterOS** into **819 [Model Context Protocol](https://modelcontextprotocol.io)
+`@usex/mikrotik-mcp` turns **MikroTik RouterOS** into **885 [Model Context Protocol](https://modelcontextprotocol.io)
 tools** any MCP client (Claude Desktop, Claude Code, Cursor, …) can call to read and
 configure your router by talking to it. It reaches the device over **plain SSH** — no
 agent, no package to install on RouterOS — runs on **[Bun](https://bun.sh)**, and
@@ -46,9 +46,23 @@ Then just ask:
 
 ## Highlights
 
-- 🧰 **819 tools, one per RouterOS scope** — L2 (bridge, VLAN, wireless, PoE),
+- 🧰 **885 tools, one per RouterOS scope** — L2 (bridge, VLAN, wireless, PoE),
   L3 (addressing, routing, DHCP, DNS), security (firewall, NAT, address-lists,
   certificates), QoS, and system ops (users, logs, backups, scheduler).
+- 🛡️ **Attack detection** — reads every device's log, correlates brute force,
+  credential spraying and _a login that succeeded after failures_ into incidents with
+  evidence, and can block the source with a timed, reversible entry. Detect-only until
+  you say otherwise. [→](docs/attack-detection.md)
+- ⏱️ **Scheduled audits** — run the auditors on a cron with nobody in the loop, and
+  hear only about what **changed** since the last run: new, worsened, resolved.
+  [→](docs/scheduled-audits.md)
+- 📖 **`explain_device`** — turns a config into the architecture document that should
+  have been in the wiki (topology diagram, what's exposed, what each chain does), and
+  explains what the difference between two snapshots actually _means_.
+  [→](docs/config-narrative.md)
+- 🧪 **Offline simulator** — trace a hypothetical packet through NAT, routing and
+  firewall against a snapshot, with no device in the loop. Reports UNKNOWN rather than
+  guessing. [→](docs/simulator.md)
 - 📊 **Live observability dashboard** — a localhost web UI that shows **every tool
   call the AI makes** in real time: inputs, outputs, latency, errors, per-device
   analytics. Secrets redacted. [Jump to it ↓](#-observability-dashboard)
@@ -67,6 +81,9 @@ Then just ask:
   bastion (`jumpVia`); commands, Safe Mode and file upload all ride the hop.
 - ⚡ **Connection pooling** — one persistent SSH session per device saves ~200-500 ms
   per command.
+- 🔀 **REST API, opt-in** — point a device at RouterOS 7.9+'s `/rest` for structured
+  JSON and real HTTP status codes, with automatic SSH fallback for anything REST
+  can't express. Per-device, off by default.
 
 ## Install
 
@@ -195,7 +212,7 @@ mikrotik-mcp serve --dashboard          # → http://127.0.0.1:9090
 ```
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-overview.png" alt="Observability dashboard — overview" width="820" />
+  <img src="assets/screenshots/web/dashboard-overview.webp" alt="Observability dashboard — overview" width="820" />
 </div>
 
 Every call flows through one choke point in the registry, so the dashboard sees **all
@@ -215,16 +232,19 @@ of them, across every transport**. Why you'll want it on:
   RouterOS identity/version and recent activity.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-live-feed.png" alt="Observability dashboard — live call feed" width="820" />
+  <img src="assets/screenshots/web/dashboard-live-feed.webp" alt="Observability dashboard — live call feed" width="820" />
 </div>
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-devices.png" alt="Observability dashboard — devices & connectivity" width="820" />
+  <img src="assets/screenshots/web/dashboard-devices.webp" alt="Observability dashboard — devices & connectivity" width="820" />
 </div>
 
-It also carries **Config Studio** (edit the config JSON with autocomplete + safe-apply
-auto-rollback), a **live topology map** from MNDP discovery, a **releases/upgrade**
-timeline, and a **reload/restart** button. Everything persists to a Bun-native SQLite
+It also carries a page per flagship workflow — **Attacks** (live incidents, the evidence
+behind each, guarded blocking), **Schedules** (audit posture over time and what regressed),
+**Explain** (the architecture document with its topology diagram), **Policies**,
+**Simulator**, **Transactions**, **Flows** and **Rollout** — plus **Config Studio** (edit
+the config JSON with autocomplete + safe-apply auto-rollback), a **live topology map** from
+MNDP discovery, a **releases/upgrade** timeline, and a **reload/restart** button. Everything persists to a Bun-native SQLite
 store on your machine — no external database. Binds to loopback (`127.0.0.1`) by default;
 set a bearer token (`--dashboard-token`) to expose it safely.
 
@@ -237,89 +257,89 @@ set a bearer token (`--dashboard-token`) to expose it safely.
 duration, risk annotation — secrets already `«redacted»`.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-live-feed-detail.png" alt="Live feed — call detail drawer" width="820" />
+  <img src="assets/screenshots/web/dashboard-live-feed-detail.webp" alt="Live feed — call detail drawer" width="820" />
 </div>
 
 **Clients.** Every DHCP lease / connected station across devices, with identity, traffic
 and last-seen.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-clients.png" alt="Clients" width="820" />
+  <img src="assets/screenshots/web/dashboard-clients.webp" alt="Clients" width="820" />
 </div>
 
 **RADIUS & User Manager.** Servers, sessions, profiles, limitations and vouchers.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-radius-um.png" alt="RADIUS & User Manager" width="820" />
+  <img src="assets/screenshots/web/dashboard-radius-um.webp" alt="RADIUS & User Manager" width="820" />
 </div>
 
 **Topology.** Live L2 map built from MNDP neighbour discovery.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-topology.png" alt="Topology map" width="820" />
+  <img src="assets/screenshots/web/dashboard-topology.webp" alt="Topology map" width="820" />
 </div>
 
 **Packets.** Packet captures started from the dashboard, with status and download.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-packets.png" alt="Packet capture" width="820" />
+  <img src="assets/screenshots/web/dashboard-packets.webp" alt="Packet capture" width="820" />
 </div>
 
 **Snapshots.** `/export`-based config snapshots kept locally — browse and diff any two.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-snapshots.png" alt="Config snapshots" width="820" />
+  <img src="assets/screenshots/web/dashboard-snapshots.webp" alt="Config snapshots" width="820" />
 </div>
 
 **Drift Guard.** Baseline vs. live config, with drift promoted or reconciled.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-drift-guard.png" alt="Drift Guard" width="820" />
+  <img src="assets/screenshots/web/dashboard-drift-guard.webp" alt="Drift Guard" width="820" />
 </div>
 
 **Change Plan.** Dry-run a batch of changes, review the exact commands, then apply under
 Safe Mode.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-changeplan.png" alt="Change plan / dry-run" width="820" />
+  <img src="assets/screenshots/web/dashboard-changeplan.webp" alt="Change plan / dry-run" width="820" />
 </div>
 
 **S3 Backups.** Off-device backup archive — upload, list, download, delete.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-s3-backup.png" alt="S3 backups" width="820" />
+  <img src="assets/screenshots/web/dashboard-s3-backup.webp" alt="S3 backups" width="820" />
 </div>
 
 **Backups.** Local backup files kept on the MCP host.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-local-backup.png" alt="Local backups" width="820" />
+  <img src="assets/screenshots/web/dashboard-local-backup.webp" alt="Local backups" width="820" />
 </div>
 
 **Modules.** The full tool catalog by module and risk annotation.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-modules.png" alt="Tool modules" width="820" />
+  <img src="assets/screenshots/web/dashboard-modules.webp" alt="Tool modules" width="820" />
 </div>
 
 **Config.** Config Studio — edit the config JSON with autocomplete, then safe-apply with
 auto-rollback.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-config.png" alt="Config Studio" width="820" />
+  <img src="assets/screenshots/web/dashboard-config.webp" alt="Config Studio" width="820" />
 </div>
 
 **Memory.** Knowledge graph of entities, relations and observations gathered from calls.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-memory.png" alt="Memory knowledge graph" width="820" />
+  <img src="assets/screenshots/web/dashboard-memory.webp" alt="Memory knowledge graph" width="820" />
 </div>
 
 **What's new.** Release notes for the running server version, shown on first launch after
 an upgrade.
 
 <div align="center">
-  <img src="assets/screenshots/dashboard-whats-new.png" alt="What's new — release notes" width="820" />
+  <img src="assets/screenshots/web/dashboard-whats-new.webp" alt="What's new — release notes" width="820" />
 </div>
 
 </details>
@@ -328,18 +348,24 @@ Full reference: **[docs/observability.md](docs/observability.md)**.
 
 ## The tool catalog
 
-**819 tools across 111 modules.** Full, always-current reference (parameters + risk per
+**885 tools across 137 modules.** Full, always-current reference (parameters + risk per
 tool) is generated from source: **[docs/tools-reference.md](docs/tools-reference.md)**.
 
-| Group                    | Tools | Modules                                                                                          |
-| ------------------------ | ----: | ------------------------------------------------------------------------------------------------ |
-| **Interfaces**           |    41 | interfaces, VLAN, bridge, wireless, PoE                                                          |
-| **Addressing & Routing** |    46 | IP addresses, IP pools, routing, DHCP, DNS                                                       |
-| **Dynamic Routing**      |    99 | router-id, tables, rules, next-hops, filters, BFD, BGP, OSPF, RIP, PIM-SM, IGMP proxy, GMP, RPKI |
-| **Security**             |    34 | firewall filter, NAT, address-lists, certificates, IP services                                   |
-| **VPN & Tunneling**      |    96 | WireGuard, IPsec, PPP, L2TP, PPTP, SSTP, OpenVPN, GRE/IPIP/EoIP/VXLAN                            |
-| **QoS**                  |    19 | queue types, queue trees, simple queues                                                          |
-| **System & Ops**         |   102 | system, network tools, scheduler/scripts, users, logs, backup, Safe Mode                         |
+| Group                    | Tools | Modules                                                                                                           |
+| ------------------------ | ----: | ----------------------------------------------------------------------------------------------------------------- |
+| **System & Ops**         |   182 | system, network tools, scheduler/scripts, users, logs, backup, Safe Mode, transactions, rollout, scheduled audits |
+| **Security**             |   125 | firewall filter, NAT, address-lists, certificates, IP services, hardening, policy-as-code, attack detection       |
+| **VPN & Tunneling**      |   108 | WireGuard, IPsec, PPP, L2TP, PPTP, SSTP, OpenVPN, GRE/IPIP/EoIP/VXLAN                                             |
+| **Dynamic Routing**      |    99 | router-id, tables, rules, next-hops, filters, BFD, BGP, OSPF, RIP, PIM-SM, IGMP proxy, GMP, RPKI                  |
+| **IPv6**                 |    90 | addressing, DHCPv6, ND, neighbours, pools, routes, firewall filter/NAT/mangle/raw                                 |
+| **Tools**                |    67 | ping, traceroute, bandwidth test, sniffer, traffic generator, RoMON, Wake-on-LAN, SMS                             |
+| **Addressing & Routing** |    62 | IP addresses, IP pools, routing, DHCP, DNS                                                                        |
+| **Interfaces**           |    56 | interfaces, VLAN, bridge, wireless, PoE                                                                           |
+| **AAA**                  |    34 | RADIUS, User Manager, 802.1X                                                                                      |
+| **QoS**                  |    23 | queue types, queue trees, simple queues                                                                           |
+| **Switch**               |    18 | switch settings, ports, rules, port isolation                                                                     |
+| **Discovery & Meta**     |     9 | tool gateway (find/describe/invoke), server pulse, capability probe                                               |
+| **Memory**               |     9 | persistent knowledge graph                                                                                        |
 
 ## Beyond the catalog
 
@@ -348,12 +374,33 @@ Higher-level workflows built on top of the per-scope tools:
 - **[Change Plan & Dry-Run](docs/change-plan.md)** — preview commands as a
   terraform-style plan, apply under Safe Mode, show the exact `/export` diff, commit
   only if still reachable.
+- **[Cross-Device Transactions](docs/transactions.md)** — coordinate Safe Mode across
+  several routers: prepare, verify while still uncommitted, then commit everywhere or
+  roll back everywhere.
+- **[Staged Fleet Rollout](docs/fleet-rollout.md)** — apply one change as canary → wave →
+  fleet with a health gate and soak between waves, reverting everything already changed
+  on the first failure.
+- **[Scheduled Audits](docs/scheduled-audits.md)** — run the auditors on a cron with
+  nobody in the loop and alert only on what changed since the previous run: new,
+  worsened, resolved.
+- **[Config Narrative](docs/config-narrative.md)** — turn a router's configuration into a
+  plain-language architecture document with a topology diagram, and explain what the
+  difference between two snapshots actually means.
+- **[Attack Detection](docs/attack-detection.md)** — watch the fleet's logs for brute
+  force, credential spraying and a login that succeeded after failures, correlate them
+  into incidents with evidence, and block the source reversibly when you ask.
 - **[Config Snapshots](docs/config-snapshots.md)** — store `/export` snapshots and
   time-travel diff any two, or one against the live device.
 - **[Firewall Audit](docs/firewall-audit.md)** — find shadowed, broad, missing-default-drop,
   duplicate and dead rules, risk-scored, with one-click fixes.
 - **[Security Hardening](docs/security-hardening.md)** — per-category audit+remediate
   pairs; audits read-only, fixes dry-run + snapshot + Safe-Mode first.
+- **[Policy-as-Code](docs/policy-as-code.md)** — write your own compliance rules in
+  YAML and lint a config snapshot offline; Markdown/JSON/SARIF, read-only, CI-able.
+- **[Offline Simulator](docs/simulator.md)** — trace a hypothetical packet through NAT,
+  routing and firewall against a snapshot; reports UNKNOWN rather than guessing.
+- **[Traffic Flow](docs/traffic-flow.md)** — NetFlow/IPFIX collection and continuous
+  top-talker / conversation / application analytics; flow metadata only, no payload.
 - **[Port-Scan Detection](docs/port-scan-detection.md)** · **[Packet Capture Studio](docs/packet-capture.md)** ·
   **[Discovery](docs/discovery.md)** · **[Config Studio](docs/config-studio.md)**.
 
@@ -402,22 +449,32 @@ Full table (HTTP host, allow-lists, timeouts, dashboard options, `MIKROTIK_LOG_L
 
 ## Documentation
 
-| Doc                                                                 |                                                             |
-| ------------------------------------------------------------------- | ----------------------------------------------------------- |
-| [Getting started](docs/getting-started.md)                          | Install, verify, first run                                  |
-| [Configuration](docs/configuration.md)                              | Every env var & flag                                        |
-| [Multiple devices](docs/multi-device.md)                            | Manage several routers; per-call targeting                  |
-| [Connecting clients](docs/connecting-clients.md)                    | Claude Desktop, stdio, HTTP                                 |
-| **[Observability](docs/observability.md)**                          | Real-time dashboard: live feed + analytics, SQLite          |
-| [Safe Mode](docs/safe-mode.md)                                      | Transactional changes                                       |
-| **[Change Plan & Dry-Run](docs/change-plan.md)**                    | Preview commands, apply with the exact diff + auto-rollback |
-| **[Firewall Audit](docs/firewall-audit.md)**                        | Shadowed/broad/dead rules, risk-scored                      |
-| **[Security Hardening](docs/security-hardening.md)**                | Per-category audit+remediate, snapshot + Safe-Mode          |
-| **[VPN guide](docs/vpn-guide.md)**                                  | Every tunnel type + how to build it                         |
-| [Prompts](docs/prompts.md)                                          | The 9 guided workflows                                      |
-| [Architecture](docs/architecture.md) · [Security](docs/security.md) | How it's built · credentials & risk gating                  |
-| [Tool reference](docs/tools-reference.md)                           | The full generated catalog                                  |
-| [Development](docs/development.md) · [Docker](docs/docker.md)       | Build, test, deploy                                         |
+| Doc                                                                 |                                                              |
+| ------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [Getting started](docs/getting-started.md)                          | Install, verify, first run                                   |
+| [Configuration](docs/configuration.md)                              | Every env var & flag                                         |
+| [Device capabilities](docs/capabilities.md)                         | What a router supports; how tools are gated on it            |
+| [Alerting](docs/alerting.md)                                        | Rules that reach out — Slack, Discord, ntfy, webhook, MCP    |
+| [Multiple devices](docs/multi-device.md)                            | Manage several routers; per-call targeting                   |
+| [Connecting clients](docs/connecting-clients.md)                    | Claude Desktop, stdio, HTTP                                  |
+| **[Observability](docs/observability.md)**                          | Real-time dashboard: live feed + analytics, SQLite           |
+| [Safe Mode](docs/safe-mode.md)                                      | Transactional changes                                        |
+| **[Cross-Device Transactions](docs/transactions.md)**               | Two-phase commit across several routers                      |
+| **[Staged Fleet Rollout](docs/fleet-rollout.md)**                   | Canary → wave → fleet with health gates and auto-revert      |
+| **[Change Plan & Dry-Run](docs/change-plan.md)**                    | Preview commands, apply with the exact diff + auto-rollback  |
+| **[Traffic Flow](docs/traffic-flow.md)**                            | NetFlow/IPFIX collection + top-talker analytics              |
+| **[Attack Detection](docs/attack-detection.md)**                    | Live attack incidents from logs; guarded, timed blocking     |
+| **[Firewall Audit](docs/firewall-audit.md)**                        | Shadowed/broad/dead rules, risk-scored                       |
+| **[Security Hardening](docs/security-hardening.md)**                | Per-category audit+remediate, snapshot + Safe-Mode           |
+| **[Scheduled Audits](docs/scheduled-audits.md)**                    | Auditors on a cron, alerting only on run-over-run changes    |
+| **[Policy-as-Code](docs/policy-as-code.md)**                        | Your own YAML compliance rules, linted offline → SARIF       |
+| **[Config Narrative](docs/config-narrative.md)**                    | Config → architecture doc + Mermaid; consequence-level diffs |
+| **[Offline Simulator](docs/simulator.md)**                          | Trace a packet through firewall + routing, no device         |
+| **[VPN guide](docs/vpn-guide.md)**                                  | Every tunnel type + how to build it                          |
+| [Prompts](docs/prompts.md)                                          | The 9 guided workflows                                       |
+| [Architecture](docs/architecture.md) · [Security](docs/security.md) | How it's built · credentials & risk gating                   |
+| [Tool reference](docs/tools-reference.md)                           | The full generated catalog                                   |
+| [Development](docs/development.md) · [Docker](docs/docker.md)       | Build, test, deploy                                          |
 
 ## Security