@usex/mikrotik-mcp 4.7.0 → 4.9.0

package/prompts/setup-vxlan-tunnel-between-sites.md

@@ -0,0 +1,129 @@
+---
+name: setup-vxlan-tunnel-between-sites
+title: Build a VXLAN overlay between two (or more) MikroTik devices
+description: Configure a VXLAN L2 overlay across MikroTik routers — VNI, VTEP peering, bridging, MTU — for multi-site / multi-tenant L2. Honest about RouterOS VTEP tooling limits; recommends EoIP for a simple two-site link.
+arguments:
+  - name: device_a
+    description: First configured device (config key or label from list_mikrotik_devices), e.g. site-a.
+    required: false
+  - name: device_b
+    description: Second configured device, e.g. site-b.
+    required: false
+  - name: vni
+    description: VXLAN Network Identifier (VNI, 1–16777215). MUST match on every VTEP in this overlay. Omit to let you pick one.
+    required: false
+  - name: port
+    description: VXLAN UDP port. Default 8472 (Linux/MikroTik); 4789 is the IANA standard. Pick one that suits the path.
+    required: false
+---
+
+You are building a **VXLAN Layer-2 overlay across MikroTik routers** this server can
+reach. VXLAN encapsulates Ethernet in **UDP** and identifies each virtual segment by
+a 24-bit **VNI**, so it scales to millions of segments and — unlike EoIP — is
+naturally **multipoint** (three+ sites on one overlay) and firewall-friendly (it's
+just UDP). Two honest caveats up front, state them to the user:
+
+1. **For a simple TWO-site L2 link, EoIP is usually the better fit** (fewer moving
+   parts, built-in keepalive + IPsec option). Use VXLAN when you need **multipoint**
+   or many segments. If the user only wants two sites bridged, recommend
+   `setup-eoip-tunnel-between-sites` unless they specifically want VXLAN.
+2. **RouterOS unicast VXLAN needs per-peer VTEP entries** (`/interface vxlan vteps`).
+   This MCP's `create_vxlan_tunnel` builds the VXLAN interface and its options but
+   does **not** expose a dedicated add-VTEP tool. So for static-unicast peering you
+   will add the remote VTEPs with the raw command tool (`run_routeros_command` /
+   the raw-command escape hatch) — call this out and get approval, or use a
+   **multicast** group for flood/learn if the WAN path carries multicast (rare across
+   the internet).
+
+Drive each device via the `device` argument. Confirm the plan before any change.
+
+Device A: {{device_a}}
+Device B: {{device_b}}
+VNI: {{vni}}
+UDP port: {{port}}
+
+## 0. Discover and confirm (FIRST)
+
+- `list_mikrotik_devices`; resolve the endpoints — never substitute a similar name;
+  ask which devices if omitted. VXLAN can span more than two, so ask for the full
+  VTEP list if it's a multipoint overlay.
+- Because VXLAN is UDP, each VTEP just needs to reach the others' public IP on the
+  chosen `port` — NAT-friendly (unlike GRE/EoIP protocol 47). Note each site's
+  reachable source IP (the local VTEP address).
+- **L2 safety:** as with EoIP, VXLAN stretches a broadcast domain — decide the single
+  DHCP authority, enable STP, and warn about loops before bridging.
+
+## 1. Facts (read-only, per device)
+
+Per side (`device=<name>`): `get_system_identity`, `list_interfaces`,
+`list_ip_addresses`, `get_routing_table`, `get_ip_cloud`. Record each VTEP's source
+IP/interface, WAN MTU, target bridge, and the segment to carry.
+
+## 2. Plan
+
+Pick `vni`={{vni}} (identical on every VTEP), `port`={{port}} or 8472, and the local
+source address/interface for each VTEP. Confirm interface names (`vxlan<vni>`) and
+the peer VTEP IP list with the user.
+
+## 3. Create the VXLAN interface (each device)
+
+On each device: `create_vxlan_tunnel` — `name`=`vxlan{{vni}}`, `vni`={{vni}},
+`port`={{port}}, `local_address`=this site's VTEP source IP (or `interface`=source
+interface), `mtu` per step 6. (`vteps_ip_version` if you're doing IPv6 VTEPs.)
+
+## 4. Peer the VTEPs (the multipoint step)
+
+For **static unicast** (internet-friendly): on each device add every OTHER site's
+VTEP as a remote VTEP under this VXLAN interface. Since there's no dedicated tool,
+use the raw-command tool with the user's approval, e.g.
+`/interface vxlan vteps add interface=vxlan{{vni}} remote-ip=<peer VTEP IP>` — repeat
+for each peer, on each device (full mesh). For **multicast** flood/learn instead,
+set the multicast group on the interface (only viable if the path carries multicast).
+
+## 5. Bridge the overlay (L2 step)
+
+Add the VXLAN interface as a **bridge port** on the LAN bridge that owns the segment,
+on every site. Enable **STP/RSTP**. Do not put an IP on the VXLAN interface (it's a
+bridge member). One DHCP authority for the stretched segment.
+
+## 6. MTU / MSS (VXLAN eats 50 bytes)
+
+VXLAN adds a **50-byte** header (UDP+VXLAN+inner-Ethernet). If the WAN MTU is 1500,
+either raise the underlay MTU/L2MTU to ~1550 (if the path supports jumbo) or lower
+the guests' effective MTU / clamp MSS so encapsulated frames don't fragment. This is
+the #1 VXLAN gotcha — verify with a large-frame test.
+
+## 7. Firewall — safely, per device
+
+Per side under Safe Mode: `input` accept `protocol=udp dst-port={{port}}` (or 8472)
+from each peer VTEP IP. Bridged traffic is `forward` (allow if `use-ip-firewall`).
+VXLAN has **no built-in encryption** — if the underlay is untrusted, run VXLAN over
+an IPsec transport policy (protect UDP/{{port}} between the VTEPs) or inside another
+encrypted tunnel; call this out.
+
+## 8. Verify
+
+- `get_vxlan_tunnel` each device: interface up, VNI/port correct, VTEP peers present.
+- L2 proof: a host at one site ARP-resolves and `ping`s a host at another **in the
+  same subnet**, no router hop; DHCP from the designated server reaches all sites.
+- Large-frame test to confirm MTU (step 6).
+
+## Bypassing country / DPI restrictions (legitimate circumvention)
+
+Lawful privacy/accessibility only. VXLAN is plain UDP on a fixed port, so:
+
+1. **Move `port` to a common UDP port** (e.g. 443) so it blends with QUIC-like
+   traffic; update every VTEP to match.
+2. **Encrypt the underlay** (IPsec transport for UDP/{{port}}), both to protect and
+   to ride ESP/4500 where raw UDP is inspected.
+3. If VXLAN itself is blocked, **carry the bridge over OpenVPN-TAP/443** (L2, HTTPS-
+   like — see `setup-openvpn-tunnel-between-sites`).
+4. Advanced obfuscation (XRay/Reality, sing-box, obfs4) via `/container` — not native.
+   Never present obfuscation as a guarantee.
+
+---
+
+Report per device: VXLAN interface, VNI, port, local VTEP IP, peer VTEP list, bridge
+joined, STP status, MTU/MSS, and verification results — noting any raw-command steps
+used for VTEP peering. State which device each change ran on. Never apply changes the
+user hasn't approved.

package/prompts/setup-wireguard-tunnel-between-sites.md

@@ -0,0 +1,183 @@
+---
+name: setup-wireguard-tunnel-between-sites
+title: Build a WireGuard tunnel between two MikroTik devices
+description: Configure BOTH routers of a WireGuard site-to-site tunnel from one conversation — keys, peers, addressing, routes, firewall, MTU/MSS — then verify end to end. Includes DPI-resistant / censorship-bypass transport options.
+arguments:
+  - name: device_a
+    description: First configured device (config key or label from list_mikrotik_devices), e.g. site-a.
+    required: false
+  - name: device_b
+    description: Second configured device, e.g. site-b.
+    required: false
+  - name: tunnel_subnet
+    description: Small transit subnet for the tunnel link itself in CIDR, e.g. 10.255.255.0/30 (A=.1, B=.2). Omit to let you pick one that doesn't collide with either LAN.
+    required: false
+  - name: listen_port
+    description: UDP port WireGuard listens on. Default 13231. Consider 443/53/500 to survive restrictive networks (see the bypass section).
+    required: false
+---
+
+You are building a **WireGuard site-to-site tunnel between two MikroTik routers**
+this server can both reach. WireGuard is the right default for MikroTik↔MikroTik:
+modern crypto (Curve25519 / ChaCha20-Poly1305), stateless, tiny, and roams across
+IP changes. You will drive **both** routers in one flow via the `device` argument.
+Precision matters — a single mismatched key, allowed-address, or MTU silently
+breaks the tunnel. Confirm the plan before any change; never write without approval.
+
+Device A: {{device_a}}
+Device B: {{device_b}}
+Transit subnet: {{tunnel_subnet}}
+Listen port: {{listen_port}}
+
+## 0. Discover and confirm both endpoints (do this FIRST)
+
+- Call `list_mikrotik_devices` to enumerate the configured routers (key, label,
+  transport target, default).
+- Resolve `{{device_a}}` / `{{device_b}}` against that inventory. If either is
+  missing or ambiguous, STOP and show the list — never substitute a similar name
+  (these are different physical routers). If either was omitted, ask the user which
+  two devices to connect.
+- Only one of the two ends needs a reachable public endpoint. Determine which side
+  is publicly reachable (static WAN IP or DDNS) — that side is the **responder**;
+  the other becomes the **initiator** and uses `persistent-keepalive` to hold the
+  path open through NAT. If **both** are behind NAT with no port-forward, say so:
+  a plain WireGuard tunnel can't form — you'd need a relay/VPS or a reachable side.
+
+## 1. Gather the facts (read-only, per device)
+
+For each of {{device_a}} and {{device_b}}, with `device=<name>`:
+`get_system_identity`, `list_interfaces`, `list_ip_addresses`, `get_routing_table`,
+and `get_ip_cloud` (for a DDNS name if there's no static WAN). Record each side's:
+public/WAN address (or DDNS), the WAN interface and its MTU, and the **LAN
+subnet(s)** to route. Verify the two LANs do **not overlap** — if they do, WireGuard
+allowed-address routing is ambiguous and you must NAT one side or renumber; flag it.
+
+## 2. Pick non-colliding addressing
+
+- Transit subnet: `{{tunnel_subnet}}` or a /30 that collides with neither LAN
+  (e.g. `10.255.255.0/30`). A=`.1`, B=`.2`.
+- Confirm the plan back to the user: interface names (`wg-<peer>`), listen ports,
+  transit IPs, and which LAN each side will advertise.
+
+## 3. Create the WireGuard interfaces and exchange keys
+
+- On EACH side: `create_wireguard_interface` (`device=<name>`, name e.g.
+  `wg-{{device_b}}` on A and `wg-{{device_a}}` on B, `listen_port`={{listen_port}}
+  or 13231). RouterOS auto-generates the private key and derives the public key.
+- Read each side's **public key** with `get_wireguard_interface` (`device=<name>`).
+  You will cross-feed these: A's peer uses **B's** public key and vice-versa. Never
+  transmit or log the private keys — they never leave their router.
+- `add_ip_address` the transit IP on each wg interface (A: `10.255.255.1/30` on
+  `wg-...`; B: `10.255.255.2/30`).
+
+## 4. Add the peers (the exact, symmetric part)
+
+On **A** (`device={{device_a}}`): `add_wireguard_peer`
+
+- `interface` = A's wg interface
+- `public_key` = **B's** public key
+- `allowed_address` = the transit peer + **B's LAN(s)**, e.g.
+  `10.255.255.2/32,192.168.20.0/24` (comma-separated; this is WireGuard's crypto-
+  routing table — it must list every subnet you expect to reach through B)
+- `endpoint_address` = B's public IP/DDNS, `endpoint_port` = B's listen port
+  (set these on whichever side is the initiator; the responder can omit them)
+- `persistent_keepalive` = `25` on the side behind NAT (the initiator) so the
+  mapping stays open
+- optional `preshared_key` = the SAME 32-byte PSK on both peers for an extra
+  symmetric layer (post-quantum-ish defense-in-depth; must match exactly).
+
+On **B** (`device={{device_b}}`): mirror it — `public_key` = **A's**,
+`allowed_address` = `10.255.255.1/32,<A's LAN>`, endpoint pointing at A **only if**
+A is the reachable side.
+
+## 5. Route each far LAN over the tunnel
+
+`allowed-address` governs what WireGuard will _cryptographically_ accept, but you
+still need an IP route so RouterOS _sends_ far-LAN traffic into the interface:
+
+- On A: `add_route` (`device={{device_a}}`) `dst-address=<B's LAN>`,
+  `gateway=<A's wg interface>`.
+- On B: mirror with A's LAN.
+  (The transit /30 already has a connected route from step 3.)
+
+## 6. Firewall — safely, per device
+
+Per side, under Safe Mode (`enable_safe_mode` `device=<name>` → edits → verify →
+`commit_safe_mode`; Safe Mode is per-device so each commits independently):
+
+- `input` chain: accept `protocol=udp dst-port=<listen_port>` from the far side's
+  WAN (or from any, if the endpoint is dynamic) — place it **above** any default
+  drop.
+- `forward` chain: accept traffic between the two LANs in both directions; if there
+  is a default-deny, add explicit accepts for `src`/`dst` of each LAN over the wg
+  interface.
+- Do NOT masquerade the tunnel subnet unless you deliberately want NAT (it breaks
+  return routing for site-to-site).
+
+## 7. MTU / MSS (the silent-failure trap)
+
+WireGuard adds ~60 bytes of overhead. Small pings work but large flows (TLS, file
+transfer) stall if MTU is wrong:
+
+- Set the wg interface MTU to **1420** (1412 if the WAN is PPPoE) via
+  `update_wireguard_interface`.
+- Clamp TCP MSS on the `forward` chain (`create_filter_rule` mangle
+  `action=change-mss new-mss=clamp-to-pmtu tcp-flags=syn`) or set it per the
+  interface MTU, so TCP sessions negotiate a size that fits.
+
+## 8. Verify end to end
+
+- From A (`ping` `device={{device_a}}`): ping B's transit IP (`10.255.255.2`), then
+  a host in B's LAN with `src_address` = A's LAN IP. Repeat from B.
+- `list_wireguard_peers` / `get_wireguard_status` on each side: confirm a recent
+  **last-handshake** and rx/tx counters climbing. No handshake ⇒ firewall/endpoint/
+  key/allowed-address mismatch — check in that order.
+- Large-payload test: ping with size 1400 and `do-not-fragment`; if it fails,
+  revisit MTU/MSS (step 7).
+
+## Bypassing country / DPI restrictions (legitimate censorship circumvention)
+
+Some networks block or throttle VPNs. The following are for lawful privacy /
+accessibility on links you're authorized to use — comply with local law and any
+service terms. From least to most evasive:
+
+1. **Port camouflage.** Move `listen_port` to a port that's rarely filtered:
+   `443` (HTTPS/QUIC), `53` (DNS), `123` (NTP), or `500`. UDP/443 often survives
+   because it looks like QUIC. Cheapest change; update the peer `endpoint_port` on
+   the other side to match. _Caveat: this hides the port, not the handshake._
+2. **DPI fingerprinting reality.** WireGuard's first handshake message has a fixed,
+   recognizable shape, so deep-packet-inspection can block it regardless of port.
+   RouterOS has **no native WireGuard obfuscation** (no obfs4/wstunnel/Shadowsocks/
+   XRay). To defeat DPI you must wrap the tunnel in something that looks benign:
+3. **Wrap WireGuard inside a TLS-looking tunnel.** Bring up an **SSTP** tunnel
+   (PPP-over-TLS on **TCP 443** — indistinguishable from HTTPS to most DPI) between
+   the sites with `create_sstp_client`/the SSTP server tools, then either route the
+   far LANs directly over SSTP, or run the WireGuard endpoint _across_ the SSTP link
+   so the WG handshake never touches the open internet. **OpenVPN in TCP/443 mode**
+   (`create_ovpn_client`, `tls`) is an equivalent camouflage. This trades throughput
+   (TCP-in-TCP) for reachability.
+4. **IPsec IKEv2 as an alternative fingerprint.** If WireGuard specifically is
+   blocked, an IKEv2 tunnel over **UDP 4500 (NAT-T)** presents a different signature
+   and is often allowed; use the `setup-ipsec-site-to-site` flow. GRE-over-IPsec
+   (`ipsec_secret`) rides ESP and is another option.
+5. **Advanced obfuscation via a RouterOS container.** For hostile DPI (active
+   probing, protocol allow-lists), the strong tools — **XRay/VLESS+Reality,
+   sing-box, Shadowsocks, obfs4** — aren't native. Run one in a RouterOS
+   **`/container`** (or on a VPS you control) and route the site tunnel through it;
+   WireGuard then rides an already-obfuscated transport. Call this out as the
+   heavier, most robust option and confirm the device has container support and
+   spare resources before proposing it.
+6. **Keepalive + MTU hygiene under hostile networks.** Keep `persistent-keepalive`
+   low (15–25 s) so aggressive NATs don't reap the mapping, and set MTU
+   conservatively (fragmentation-sensitive DPI drops oversized handshakes).
+
+Recommend the lightest option that works for the user's threat model (start at #1,
+escalate to #3, reserve #5 for active blocking), explain the throughput/complexity
+trade-off, and never present obfuscation as a guarantee — it is an arms race.
+
+---
+
+Report, per side: interface name, public key (never the private key), listen port,
+transit IP, peer allowed-address, routes and firewall rules added, the MTU/MSS
+settings, and the verification results (handshake time, ping). State plainly which
+device each change ran on. Never apply changes the user hasn't approved.

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 794 tools: `name`, `risk`, `title`, `description`, and input JSON Schema. |
+| `tool-catalog.json` | Every one of the 819 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: