@usex/mikrotik-mcp 5.19.0 → 5.20.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 (70) hide show
  1. package/README.md +172 -8
  2. package/dist/cli.js +2751 -679
  3. package/dist/index.js +148 -27
  4. package/dist/shared/{library-7wcv2ckk.js → library-73y8qdjr.js} +2231 -540
  5. package/dist/shared/{library-tqrvrykj.js → library-76naf20r.js} +1 -1
  6. package/dist/shared/{library-ppnv0f07.js → library-81amv3az.js} +1 -1
  7. package/dist/shared/{library-z7qsdq88.js → library-krajvnj9.js} +1 -1
  8. package/dist/shared/{library-f3be6g03.js → library-y9tt30y1.js} +1 -1
  9. package/dist/ui/aaa.html +8 -8
  10. package/dist/ui/connected-devices.html +8 -8
  11. package/dist/ui/dashboard.html +16 -16
  12. package/dist/ui/fabric.html +11 -11
  13. package/dist/ui/firewall-audit.html +8 -8
  14. package/dist/ui/firewall.html +9 -9
  15. package/dist/ui/interfaces.html +8 -8
  16. package/dist/ui/investigations.html +11 -11
  17. package/dist/ui/observability.html +63 -61
  18. package/dist/ui/operations.html +11 -11
  19. package/dist/ui/records.html +12 -12
  20. package/dist/ui/reports.html +11 -11
  21. package/dist/ui/round-trip.html +11 -11
  22. package/dist/ui/service-health.html +11 -11
  23. package/package.json +22 -22
  24. package/prompts/audit-routeros-containers.md +27 -0
  25. package/prompts/audit-vlan-segmentation.md +31 -0
  26. package/prompts/setup-guest-wifi.md +23 -24
  27. package/prompts/setup-routeros-container.md +36 -0
  28. package/prompts/setup-v2ray-container-proxy.md +68 -194
  29. package/prompts/setup-vlan-network.md +27 -33
  30. package/schemas/README.md +1 -1
  31. package/schemas/devtools-manifest.json +287 -16
  32. package/schemas/tool-catalog.json +785 -109
  33. package/schemas/tools/add_container.json +42 -30
  34. package/schemas/tools/add_container_env.json +3 -4
  35. package/schemas/tools/add_container_mount.json +10 -4
  36. package/schemas/tools/apply_service_routing.json +23 -0
  37. package/schemas/tools/arm_service_routing.json +23 -0
  38. package/schemas/tools/configure_flight_recorder.json +30 -0
  39. package/schemas/tools/create_service_routing.json +78 -0
  40. package/schemas/tools/design_network_segment.json +22 -6
  41. package/schemas/tools/destroy_recovery_lab.json +18 -0
  42. package/schemas/tools/export_network_incident.json +14 -0
  43. package/schemas/tools/freeze_network_incident.json +14 -0
  44. package/schemas/tools/get_container.json +11 -4
  45. package/schemas/tools/get_flight_recorder.json +7 -0
  46. package/schemas/tools/get_recovery_lab.json +7 -0
  47. package/schemas/tools/get_routeros_container_guide.json +22 -0
  48. package/schemas/tools/get_vlan_segmentation_guide.json +14 -0
  49. package/schemas/tools/list_container_envs.json +1 -1
  50. package/schemas/tools/list_container_mounts.json +7 -2
  51. package/schemas/tools/list_containers.json +2 -4
  52. package/schemas/tools/list_service_routing.json +7 -0
  53. package/schemas/tools/poll_recovery_lab.json +14 -0
  54. package/schemas/tools/prepare_recovery_lab.json +23 -0
  55. package/schemas/tools/preview_service_routing.json +23 -0
  56. package/schemas/tools/probe_service_routing.json +14 -0
  57. package/schemas/tools/recovery_lab_inventory.json +7 -0
  58. package/schemas/tools/remove_container.json +11 -4
  59. package/schemas/tools/remove_container_env.json +7 -3
  60. package/schemas/tools/remove_container_mount.json +18 -2
  61. package/schemas/tools/service_routing_inventory.json +7 -0
  62. package/schemas/tools/set_container_config.json +4 -6
  63. package/schemas/tools/start_container.json +11 -4
  64. package/schemas/tools/start_recovery_lab.json +18 -0
  65. package/schemas/tools/stop_container.json +11 -4
  66. package/schemas/tools/update_container.json +46 -6
  67. /package/dist/shared/{cli-j07tbrke.js → cli-426pkqe9.js} +0 -0
  68. /package/dist/shared/{cli-y00nwzxx.js → cli-6wdstvdq.js} +0 -0
  69. /package/dist/shared/{cli-s0rxncz4.js → cli-cvt06346.js} +0 -0
  70. /package/dist/shared/{cli-gtq5bw8q.js → cli-z1kavk0z.js} +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usex/mikrotik-mcp",
3
- "version": "5.19.0",
3
+ "version": "5.20.0",
4
4
  "description": "MCP server for MikroTik RouterOS — 780+ tools over SSH for firewall, NAT, routing, DHCP, DNS, WireGuard, wireless, QoS and more.",
5
5
  "keywords": [
6
6
  "ai",
@@ -90,12 +90,12 @@
90
90
  "prepare": "vp config"
91
91
  },
92
92
  "dependencies": {
93
- "@modelcontextprotocol/client": "^2.1.0",
94
- "@modelcontextprotocol/core": "^2.1.0",
95
- "@modelcontextprotocol/ext-apps": "^2.0.0",
96
- "@modelcontextprotocol/sdk": "^1.30.1",
97
- "@tikoci/centrs": "^0.1.6",
98
- "figlet": "^1.11.4",
93
+ "@modelcontextprotocol/client": "^2.3.0",
94
+ "@modelcontextprotocol/core": "^2.3.0",
95
+ "@modelcontextprotocol/ext-apps": "^2.0.3",
96
+ "@modelcontextprotocol/sdk": "^1.32.0",
97
+ "@tikoci/centrs": "^0.1.7",
98
+ "figlet": "^1.12.0",
99
99
  "gradient-string": "^3.0.0",
100
100
  "ipaddr.js": "^2.5.0",
101
101
  "ssh2": "^1.17.0",
@@ -103,38 +103,38 @@
103
103
  },
104
104
  "devDependencies": {
105
105
  "@anthropic-ai/mcpb": "^2.1.2",
106
- "@devframes/hub": "1.1.0",
107
- "@devframes/hub-ui": "1.1.0",
108
- "@devframes/plugin-a11y": "1.1.0",
109
- "@devframes/plugin-a11y--assets": "1.1.0",
110
- "@devframes/plugin-data-inspector": "1.1.0",
111
- "@devframes/plugin-data-inspector--assets": "1.1.0",
112
- "@devframes/plugin-inspect": "1.1.0",
113
- "@devframes/plugin-inspect--assets": "1.1.0",
114
- "@devframes/vite": "1.1.0",
106
+ "@devframes/hub": "1.2.0",
107
+ "@devframes/hub-ui": "1.2.0",
108
+ "@devframes/plugin-a11y": "1.2.0",
109
+ "@devframes/plugin-a11y--assets": "1.2.0",
110
+ "@devframes/plugin-data-inspector": "1.2.0",
111
+ "@devframes/plugin-data-inspector--assets": "1.2.0",
112
+ "@devframes/plugin-inspect": "1.2.0",
113
+ "@devframes/plugin-inspect--assets": "1.2.0",
114
+ "@devframes/vite": "1.2.0",
115
115
  "@paper-design/shaders-react": "^0.0.81",
116
116
  "@resvg/resvg-js": "^2.6.2",
117
117
  "@tailwindcss/vite": "^4.3.3",
118
118
  "@tanstack/react-virtual": "^3.14.13",
119
119
  "@types/bun": "1.4.2",
120
120
  "@types/figlet": "^1.7.0",
121
- "@types/node": "^26.6.3",
121
+ "@types/node": "^26.6.4",
122
122
  "@types/react": "^19.3.0",
123
123
  "@types/react-dom": "^19.3.0",
124
124
  "@types/ssh2": "^1.15.6",
125
125
  "@types/update-notifier": "^6.0.8",
126
126
  "@typescript/native": "npm:typescript@^7.0.2",
127
- "@vitest/coverage-v8": "5.0.2",
128
- "@vitest/ui": "5.0.2",
127
+ "@vitest/coverage-v8": "5.0.3",
128
+ "@vitest/ui": "5.0.3",
129
129
  "bunup": "^0.16.32",
130
130
  "class-variance-authority": "^0.7.1",
131
131
  "clsx": "^2.1.1",
132
- "devframe": "1.1.0",
132
+ "devframe": "1.2.0",
133
133
  "gsap": "^3.15.0",
134
134
  "happy-dom": "^20.14.5",
135
135
  "lenis": "^1.3.26",
136
136
  "license-checker": "^25.0.1",
137
- "lucide-react": "^1.48.0",
137
+ "lucide-react": "^1.51.0",
138
138
  "motion": "^13.4.4",
139
139
  "qrcode-generator": "^2.0.4",
140
140
  "radix-ui": "^1.6.7",
@@ -142,7 +142,7 @@
142
142
  "react-dom": "^19.3.0",
143
143
  "recharts": "^3.10.1",
144
144
  "release-it": "^21.1.0",
145
- "shiki": "^4.4.3",
145
+ "shiki": "^4.5.0",
146
146
  "sonner": "^2.0.8",
147
147
  "tailwind-merge": "^3.7.0",
148
148
  "tailwindcss": "^4.3.3",
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: audit-routeros-containers
3
+ title: Audit RouterOS container readiness and isolation
4
+ description: Read-only container architecture, storage, lifecycle, network policy and security audit with an evidence-based cleanup plan.
5
+ arguments:
6
+ - name: device
7
+ description: Exact configured router; omit to discover and ask.
8
+ required: false
9
+ - name: requirements
10
+ description: Intended workloads, trusted clients and restrictions.
11
+ required: false
12
+ ---
13
+
14
+ Audit {{device}} against the shared container guide below. Requirements: {{requirements}}.
15
+ This is READ-ONLY: no package installation, device-mode updates, container restart,
16
+ network changes, disk formatting or file deletion. Any implementation needs separate approval.
17
+
18
+ Resolve the device exactly. Inventory architecture/version/package/device-mode,
19
+ resource headroom, disks, container metadata/status, VETHs, bridge/VLAN membership,
20
+ IPv4/IPv6 routes, firewall and NAT. Inspect env KEY metadata, never values.
21
+ Use bounded filtered reads. Separate unsupported menus, failed transport and unknown state.
22
+
23
+ Produce a prioritized table: finding, observed evidence, affected workload, risk,
24
+ recommended change, backup/recovery requirements and verification. Distinguish
25
+ readiness, process running and application health. Flag shared lists/volumes,
26
+ management-path dependencies and physical/reboot steps. Do not claim benchmarks
27
+ or successful client tests without measurements. Offer a staged plan, not automatic cleanup.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: audit-vlan-segmentation
3
+ title: Audit VLAN isolation and migration readiness
4
+ description: Read-only topology, IPv4/IPv6 isolation and management-path review with a prioritized cleanup plan; never applies changes.
5
+ arguments:
6
+ - name: requirements
7
+ description: Desired zones, allowed services, remote sites and constraints. If omitted, discover facts and ask about policy rather than inventing it.
8
+ required: false
9
+ ---
10
+
11
+ Audit VLAN segmentation on the explicitly selected device. Requirements: {{requirements}}
12
+ This workflow is READ-ONLY. Do not create backups on routers, start/verify transactions,
13
+ change configuration, enable filtering, write memory, or run disruptive load tests.
14
+
15
+ Use bounded dedicated read tools discovered with `find_tools`. If another managed
16
+ router is in scope, resolve and inspect it separately; otherwise report its
17
+ dependencies as unknown. Never substitute the default router for an unknown name.
18
+
19
+ Produce:
20
+
21
+ 1. Observed topology: port roles, VLAN/PVID/CPU map, SSIDs, subnets, IPv6 and tunnels.
22
+ 2. Intended vs observed IPv4/IPv6 INPUT/FORWARD policy, including shadowed rules,
23
+ management exposure, guest peers and remote return routing. Mark unsupported,
24
+ incomplete or timed-out evidence unknown; static policy analysis is not a live test.
25
+ 3. Prioritized findings with evidence, risk, affected devices, proposed correction,
26
+ dependency/lockout impact, rollback requirements and a concrete acceptance test.
27
+ 4. A staged migration and cleanup proposal, separating necessary fixes, optional
28
+ improvements and choices that need the operator. Never assume disabled means unused.
29
+ 5. Known limits: what could not be verified from actual wired/wireless clients.
30
+
31
+ Stop with the report. Any future implementation needs separate approval.
@@ -14,32 +14,31 @@ arguments:
14
14
  required: true
15
15
  ---
16
16
 
17
- Build an **isolated guest network** on this MikroTik device. Guests must reach the
18
- internet but must NOT reach the LAN or the router's management. Plan the whole
19
- change first, show it to the user, then apply it under Safe Mode.
17
+ Plan an **isolated guest network** on the explicitly selected MikroTik device.
18
+ Guests may use approved internet/services, but not local devices or administration.
19
+ Start read-only, show the complete plan and request approval before any writes.
20
20
 
21
21
  Guest subnet: {{subnet}}
22
22
  Guest VLAN ID: {{vlan_id}}
23
23
  WAN interface: {{wan_interface}}
24
24
 
25
- Proposed build (adapt to what you discover with `list_interfaces`,
26
- `list_ip_addresses`, `list_filter_rules`):
27
-
28
- 1. **Segment** — if a VLAN is requested, `create_vlan_interface` (vlan_id
29
- {{vlan_id}}) on the LAN bridge/trunk; otherwise pick a dedicated interface.
30
- 2. **Gateway IP** — `add_ip_address` using the first usable address of {{subnet}}.
31
- 3. **DHCP** — `create_dhcp_pool`, `create_dhcp_network` (gateway + DNS), and
32
- `create_dhcp_server` bound to the guest interface.
33
- 4. **NAT** — ensure a `create_nat_rule` masquerade exists for {{subnet}} out
34
- {{wan_interface}}.
35
- 5. **Isolation (the important part)** — in the `forward` chain via
36
- `create_filter_rule`:
37
- - allow {{subnet}} → WAN (established/related + new),
38
- - **drop {{subnet}} → LAN subnets (RFC1918)**,
39
- and in the `input` chain drop {{subnet}} → router except DHCP/DNS. Consider an
40
- `add_address_list_entry` list named `guest` to keep the rules tidy.
41
- 6. **Verify** — re-list the rules and confirm ordering; `enable_safe_mode` before
42
- applying, test, then `commit_safe_mode`.
43
-
44
- Present the plan as an ordered list of exact tool calls with arguments before
45
- executing anything.
25
+ 1. Discover port roles, AP VLAN support and Wi-Fi package, bridge membership,
26
+ existing addressing, policy routing and IPv4/IPv6 firewall order with `find_tools`.
27
+ 2. Plan the SSID-to-VLAN mapping on AP and uplink, access PVID/admission, trunk
28
+ membership and bridge/CPU gateway access. Without VLANs, require a genuinely
29
+ separate L2 interface/bridge; a second subnet on the same LAN is not isolation.
30
+ 3. Check subnet overlap and assign a valid gateway/pool excluding reserved hosts.
31
+ Identify working DNS and egress. Reuse existing NAT where appropriate; never
32
+ add unscoped masquerade. NAT does not allow traffic through a forward firewall.
33
+ 4. Plan INPUT management protection and FORWARD isolation in BOTH IPv4 and IPv6.
34
+ RFC1918-only drops miss local public addresses, remote/VPN subnets and IPv6.
35
+ Scope essential DHCP/DNS/ICMPv6 allowances; put approved service exceptions
36
+ before denies and denies before conflicting broad accepts. Do not blindly append.
37
+ 5. Treat guest-to-guest isolation as an additional AP/switch requirement. Prove
38
+ it separately; routed rules cannot prevent all same-VLAN communication.
39
+ 6. Show exact changes, an independent recovery path and backup/rollback plan.
40
+ After approval only, stage under the suitable safe execution workflow, enable
41
+ VLAN filtering LAST and canary one client before migrating everyone.
42
+ 7. Test DHCP, DNS, allowed internet, denied local/management access and guest peer
43
+ isolation from actual clients over both families. Read-back alone is insufficient.
44
+ Commit only if verification succeeds and the approval covers this exact change.
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: setup-routeros-container
3
+ title: Plan and safely deploy a RouterOS container
4
+ description: Version-aware image, storage, isolated VETH network and lifecycle workflow with explicit approval and application verification.
5
+ arguments:
6
+ - name: device
7
+ description: Exact configured router; omit to discover and ask.
8
+ required: false
9
+ - name: image
10
+ description: Reviewed image and pinned version/digest, or uploaded image archive.
11
+ required: false
12
+ - name: requirements
13
+ description: Application, client access, ports, persistent data and downtime constraints.
14
+ required: false
15
+ ---
16
+
17
+ Target {{device}}; image {{image}}; requirements {{requirements}}.
18
+ Start with READ-ONLY discovery following the shared container guide. Ask for
19
+ missing workload/access requirements. Verify architecture, package/device-mode,
20
+ storage, syntax and resources before proposing any command.
21
+
22
+ Prepare an explicit plan with image trust, volume backup, dedicated VETH/bridge or
23
+ VLAN, dual-stack allowed-flow matrix, positive WAN egress, shared-list consumers,
24
+ management preservation and recovery. No changes until the operator approves it.
25
+ Package/reboot/physical-confirmation steps require separate approval and scheduling.
26
+
27
+ Use describe_tool for the actual schema, including list vs legacy name and
28
+ envlists vs envlist. Do not guess a modern inline mount expression from Docker
29
+ examples. Keep secrets outside reports and Memory. Back up approved router changes
30
+ and application volumes separately; Safe Mode is not filesystem rollback.
31
+
32
+ After an approved add, poll a bounded number of times until fully stopped, then
33
+ start the exact .id. If a command times out, inspect before retrying. Test the
34
+ service from an intended client, deny an unintended source, and check both IP
35
+ families. Only then enable start-on-boot if approved. Report every pending/unknown
36
+ check; do not perform a reboot merely to test persistence without permission.
@@ -1,207 +1,81 @@
1
1
  ---
2
2
  name: setup-v2ray-container-proxy
3
- title: Run V2Ray/Xray (VLESS·Reality·VMess·Trojan·Shadowsocks) in a MikroTik container and route traffic through it
4
- description: Deploy an Xray / V2Ray / sing-box client inside a RouterOS /container, wire its VETH into the router, and selectively (or fully) route LAN traffic through the encrypted VLESS-Reality / VMess / Trojan / Shadowsocks / Hysteria tunnel — with device-mode, disk, MTU, DNS-leak and kill-switch handling. For lawful privacy / censorship circumvention on networks you are authorized to use.
3
+ title: Plan a V2Ray/Xray or sing-box container gateway on RouterOS
4
+ description: Audit prerequisites, then plan an isolated proxy container with explicit approval, dual-stack policy, bounded lifecycle checks and end-to-end verification.
5
5
  arguments:
6
6
  - name: device
7
- description: Which configured MikroTik to run the proxy container on (config key or label from list_mikrotik_devices). Omit to discover and choose.
7
+ description: Exact configured router; omit to discover and ask.
8
8
  required: false
9
9
  - name: protocol
10
- description: V2Ray-family protocol the tunnel will use — vless-reality (recommended), vless-vision, vmess, trojan, shadowsocks, or (sing-box) hysteria2/tuic. This is configured INSIDE the container image, not on RouterOS.
10
+ description: Desired protocol supported by the selected image and remote server.
11
11
  required: false
12
12
  - name: image
13
- description: Container image to run (e.g. gritsenko/xray-mikrotik:latest, or a sing-box image). Omit to let you recommend one matching the device architecture and chosen protocol.
13
+ description: Reviewed architecture-compatible image and pinned version/digest.
14
14
  required: false
15
15
  - name: scope
16
- description: What to route through the tunnel — "selective" (only domains/IPs on an address-list, default and recommended) or "all" (default route via the tunnel, with a kill-switch).
16
+ description: Selective destinations or all traffic for explicitly selected clients.
17
17
  required: false
18
18
  ---
19
19
 
20
- You are deploying a **V2Ray / Xray-core (or sing-box) client inside a MikroTik
21
- RouterOS `/container`** and routing LAN traffic through its encrypted tunnel. This
22
- is the _native-RouterOS_ way to run the modern censorship-resistant protocols —
23
- **VLESS (+Vision/XTLS), VLESS + Reality, VMess, Trojan, Shadowsocks**, and (with a
24
- sing-box image) **Hysteria2 / TUIC** — that RouterOS has no built-in support for.
25
- The router runs the client; a remote V2Ray/Xray **server (a VPS you control)** is
26
- the other end. This flow configures the RouterOS side; the tunnel's crypto
27
- parameters live in the container image's config/env.
28
-
29
- **Legality & scope.** This is for **lawful privacy and accessibility** on networks
30
- and services you are authorized to use — comply with local law and provider terms.
31
- Confirm the user understands this before proceeding. Treat the remote server
32
- address, UUIDs, keys and short-ids as **secrets** — never log or echo them back in
33
- full; mask them in your reports.
34
-
35
- Target device: {{device}}
36
- Protocol: {{protocol}}
37
- Image: {{image}}
38
- Routing scope: {{scope}}
39
-
40
- ---
41
-
42
- ## Back up before the first write
43
-
44
- Before your FIRST configuration change in this workflow — the tunnel/interface, keys/peers, addresses, routes, NAT, or any mangle or firewall filter rule — ASK the user "Create a local backup first?" and, on yes, call `create_local_backup` for each device you are about to change. It saves a host-side `.rsc` restore point you can `restore_local_backup` if the change cuts the link. Discovery and the read-only fact-gathering steps below need no backup — do it once, right before you start writing. Tunnel creation always warrants a backup; you may skip it only for a minor, non-critical mangle/filter tweak the user explicitly waves off.
45
-
46
- ## 0. Discover the device and confirm it CAN run containers (do this FIRST)
47
-
48
- - Call `list_mikrotik_devices`; resolve `{{device}}` (never substitute a similar
49
- name). If omitted, present the inventory and ask which router. Pass `device=` on
50
- every subsequent call.
51
- - **Prerequisite check (read-only)** — containers have hard requirements; verify all
52
- before proposing changes:
53
- - `get_system_resources` (`device=<name>`) — confirm **architecture** is `arm`,
54
- `arm64`, or `x86` (**MIPS/SMIPS cannot run containers** — stop and say so), and
55
- that there is spare **RAM/CPU**.
56
- - `list_containers` — if it errors, the **`container` package isn't installed**.
57
- - Confirm an **external disk** (USB/NVMe, ext4) exists for the container root-dir —
58
- running container images off internal flash wears it out fast. Check with
59
- `run_routeros_command` `/disk print`.
60
- - **Two prerequisites need out-of-band action — flag, do NOT silently attempt:**
61
- 1. **device-mode = container=yes.** Enabling it (`/system/device-mode/update
62
- mode=advanced container=yes`) requires **physical confirmation** (press the
63
- reset button or power-cycle within the timeout). You cannot complete this
64
- remotely — tell the user they must do the physical step.
65
- 2. **Installing the `container` package** requires uploading the `.npk` and
66
- `/system/package/apply-changes` (7.18+) which **reboots** the router. Get
67
- explicit approval; note the device will drop offline during reboot.
68
-
69
- Do not proceed to container creation until architecture, disk, package, and
70
- device-mode are all satisfied.
71
-
72
- ## 1. Choose image and protocol
73
-
74
- - **Protocol** (`{{protocol}}`): recommend **VLESS + Reality** as the default —
75
- Reality forges the TLS handshake of a real public site (no certificate to obtain,
76
- no domain to burn, strongest anti-DPI of the family). VLESS+Vision/XTLS, VMess,
77
- Trojan, and Shadowsocks are alternatives; sing-box images add Hysteria2/TUIC
78
- (QUIC-based, good on lossy/throttled links). The choice is realised in the
79
- container's config — RouterOS just carries the encapsulated traffic.
80
- - **Image** (`{{image}}`): pick one matching the device architecture (map:
81
- `arm→linux/arm/v7`, `arm64→linux/arm64`, `x86→linux/amd64`). Community images
82
- (e.g. `gritsenko/xray-mikrotik`) bundle **xray-core + tun2socks** so the
83
- container's VETH acts directly as a routable gateway — simplest. Otherwise the
84
- **two-container** pattern (below) is the general form. **Read the specific image's
85
- README for its exact env-var names** — they differ per image; do not assume.
86
- - **RouterOS local-import caveat:** `add_container remote_image=` pulls from a
87
- registry (needs `set_container_config registry-url=... tmpdir=disk1/pull` and
88
- internet). A local `.tar` must be **single-layer, uncompressed, Docker-v1** — most
89
- people pull from a registry.
90
-
91
- ## 2. Two deployment shapes (pick one, explain to the user)
92
-
93
- **A — All-in-one image (recommended, simplest).** One container running xray-core +
94
- tun2socks. Its VETH IP becomes the gateway you route through. Example env schema
95
- (gritsenko/xray-mikrotik — verify against the image):
96
- `SERVER_ADDRESS`, `SERVER_PORT`, `USER_ID`, `ENCRYPTION`, `FINGERPRINT_FP`,
97
- `SERVER_NAME_SNI`, `PUBLIC_KEY_PBK`, `SHORT_ID_SID`.
98
-
99
- **B — Two-container (general, more control).** Container 1 = xray-core exposing a
100
- **SOCKS5** inbound (e.g. `172.17.0.2:1080`); Container 2 = **tun2socks /
101
- hev-socks5-tunnel** turning that SOCKS5 into a routable gateway on its own VETH.
102
- Typical env — xray: `REMOTE_ADDRESS,REMOTE_PORT,ID,FLOW,PUBLIC_KEY,SHORT_ID,
103
- SERVER_NAME`; tun: `SOCKS5_ADDR=172.17.0.2,SOCKS5_PORT=1080,LOCAL_ROUTE` (so LAN
104
- subnets return via the router, not the tunnel). _Note: original tun2socks has arm64
105
- issues — use an arm64-built image._
106
-
107
- ## 3. Container networking (VETH + NAT + DNS)
108
-
109
- There is **no dedicated VETH tool** — create it with `run_routeros_command`
110
- (approve each raw command). Example for shape A on a /30:
111
-
112
- - `/interface veth add name=veth-xray address=172.18.20.6/30 gateway=172.18.20.5`
113
- - `add_ip_address` `address=172.18.20.5/30 interface=veth-xray` (router side).
114
- - `create_nat_rule` `chain=srcnat action=masquerade out-interface=veth-xray` (so the
115
- container reaches the internet / the remote server).
116
- - Container `dns` = the router's veth IP (`172.18.20.5`) or a resolver you trust.
117
- (Shape B: put both VETHs on a `containers` bridge, `172.17.0.1/24` gateway.)
118
-
119
- ## 4. Create and start the container
120
-
121
- - If pulling from a registry: `set_container_config` `registry-url=https://registry-1.docker.io tmpdir=disk1/pull`.
122
- - Env vars: either inline via `add_container` `env="SERVER_ADDRESS=...,USER_ID=..."`
123
- (7.21+) or as a named list with `add_container_env` (`envlists=`). **Mask the
124
- secret values in anything you print back.**
125
- - `add_container` (`device=<name>`) — `remote_image={{image}}`, `interface=veth-xray`,
126
- `root_dir=disk1/xray`, `dns=172.18.20.5`, `logging=yes`, `start_on_boot=yes`,
127
- `hostname=xray`, and the env.
128
- - `start_container`; then `get_container` / `list_containers` until it shows
129
- **running**, and read startup output with the container-log (it must show a
130
- successful outbound handshake to your server before routing anything through it).
131
-
132
- ## 5. Route traffic through the tunnel
133
-
134
- **Selective (`scope=selective`, recommended)** — only chosen destinations go through
135
- the proxy; everything else uses the normal WAN (fast, low-risk, defeats geo-blocks
136
- for the sites that need it):
137
-
138
- 1. `add_address_list_entry` — build a list `via_proxy` of the domains/IPs to tunnel
139
- (RouterOS resolves domain entries to IPs automatically).
140
- 2. `add_routing_table` — `name=proxy fib`.
141
- 3. `create_mangle_rule` — `chain=prerouting action=mark-routing
142
- new-routing-mark=proxy dst-address-list=via_proxy passthrough=no`
143
- (add `src-address=<LAN>` to scope to LAN clients; exclude the router's own/ the
144
- container subnet to avoid loops).
145
- 4. `add_route` — `dst-address=0.0.0.0/0 gateway=172.18.20.6 routing-table=proxy`
146
- (gateway = the container's VETH IP, shape A; the tun container's IP, shape B).
147
-
148
- **All traffic (`scope=all`)** — default route via the tunnel. Same routing table but
149
- mark all LAN traffic (or set the container gateway as the main default). **Mandatory
150
- kill-switch:** add a low-priority `forward` **drop** for the LAN when the tunnel
151
- interface is down, so a container crash can't silently leak traffic out the clear
152
- WAN. Also pin a **higher-priority route to the remote server's IP via the real WAN**
153
- so the tunnel's own packets don't recurse into itself.
154
-
155
- ## 6. DNS-leak & MTU handling
156
-
157
- - **DNS leaks:** if clients query a public resolver directly, the destination is
158
- exposed even though the payload is tunnelled. Redirect LAN DNS (dst-nat UDP/TCP 53
159
- to the router or the container's resolver) so lookups for proxied domains resolve
160
- through the tunnel, or run the resolver inside/behind the container.
161
- - **MTU/MSS:** encapsulation shrinks usable MTU — add a `create_mangle_rule`
162
- `chain=forward action=change-mss new-mss=clamp-to-pmtu tcp-flags=syn` (and/or lower
163
- the veth MTU). This is the #1 "handshake works, big pages hang" cause.
164
-
165
- ## 7. Firewall — safely
166
-
167
- Under Safe Mode (`enable_safe_mode` `device=<name>` → edits → verify →
168
- `commit_safe_mode`): allow the container subnet outbound, keep the masquerade from
169
- step 3, and (scope=all) install the kill-switch drop. Do not expose the container's
170
- SOCKS5 port to the WAN.
171
-
172
- ## 8. Verify end to end
173
-
174
- - `get_container` shows **running**; the container log shows a completed handshake to
175
- your server (no repeated dial errors).
176
- - From a **marked** LAN source, check the **egress IP** changed: fetch an "what is my
177
- IP" service from a proxied client (or `run_routeros_command` a `/tool fetch` bound
178
- to the proxy path) — it should show the **VPS** IP, not the local WAN IP.
179
- - Confirm a **non-proxied** destination still exits the normal WAN (selective scope).
180
- - `ping`/`traceroute` a proxied target; test a large HTTPS page (MTU sanity).
181
- - Reboot-persistence: `start_on_boot=yes` and the routing rules survive a reboot.
182
-
183
- ## 9. Family notes, hardening & honest caveats
184
-
185
- - **VLESS + Reality**: no cert/domain needed; set a believable `SERVER_NAME_SNI`
186
- (a real, unrelated HTTPS site the censor won't block) and matching public-key/
187
- short-id from the server. Strongest default against active-probing DPI.
188
- - **VMess/Trojan/Shadowsocks**: pair with TLS/WebSocket/gRPC transports on 443 for
189
- camouflage; plain Shadowsocks is weaker against modern DPI.
190
- - **Hysteria2/TUIC** (sing-box image): QUIC/UDP — great on lossy or throttled links,
191
- but blocked where UDP is throttled.
192
- - **Trust**: you are running a third-party image with your keys and all your traffic.
193
- Prefer images you can inspect/build; pin a digest; keep it updated.
194
- - **Reality/DPI is an arms race** — never present it as a guarantee. Keep a fallback
195
- (a second protocol/port, or an SSTP/OpenVPN-443 transport per
196
- `setup-sstp-tunnel-between-sites`).
197
- - **Resource reality**: containers are RAM/CPU/disk heavy on small routers; on very
198
- low-end boards run the client on a VPS/box and point the router at it instead.
199
-
200
- ---
201
-
202
- Report: device, architecture, image + protocol, VETH/NAT, container status, the
203
- routing-table + mangle + route rules and the address-list scope, DNS/MTU/kill-switch
204
- handling, and the verification results (egress-IP proof) — with **all secrets
205
- masked**, and a note of every `run_routeros_command` step used (VETH, device-mode).
206
- Flag the physical device-mode step and any reboot explicitly. Never apply changes the
207
- user hasn't approved.
20
+ Plan a lawful, authorized proxy deployment on {{device}}.
21
+ Protocol: {{protocol}}. Image: {{image}}. Client routing scope: {{scope}}.
22
+ Start READ-ONLY. Use the shared container guide below as the safety baseline.
23
+ An audit or a request for advice is not permission to change router configuration.
24
+
25
+ ## Discover and choose
26
+
27
+ Resolve the exact device. Inspect version/architecture/CPU variant, container
28
+ package, device-mode, storage and available resources. A command failure is not
29
+ proof the package is missing. Treat unknown prerequisites as blockers to writes.
30
+ Enabling container=yes needs operator physical confirmation; do not change the
31
+ whole device-mode or silently install packages, reboot, format or Netinstall.
32
+ Inspect existing management, LAN/VPN, IPv4/IPv6 policy and other containers first.
33
+
34
+ Ask for the remote server, protocol, intended clients and access constraints.
35
+ Verify the image publisher, protocol documentation, required env KEY names,
36
+ architecture/variant, privilege/device requirements and pinned image identity.
37
+ Never promise DPI evasion or speed improvement. Keep credentials out of reports.
38
+
39
+ A SOCKS5 proxy alone cannot serve as an IP gateway. An all-in-one TUN image or
40
+ an explicitly designed proxy plus TUN gateway can do so only if IP forwarding,
41
+ return routes and startup ordering are verified. Do not assume eth0 inside the
42
+ image. Discover available tools with find_tools/describe_tool before raw commands.
43
+
44
+ ## Plan, approve and protect
45
+
46
+ Show the complete plan and obtain approval before writes. Back up approved router
47
+ configuration AND application data; eligible Safe Mode rollback does not restore
48
+ container images, files or volumes. Agree an independent recovery path.
49
+
50
+ Use a dedicated container bridge/VLAN and verified non-overlapping subnet.
51
+ Assign the router gateway to that bridge and a distinct address to the VETH.
52
+ Do not assign the same IP to both ends or add containers to trusted LAN by default.
53
+ Container internet source NAT, if needed, uses its source subnet and the positive
54
+ real WAN egress, not out-interface=veth. Restrict published ports by source,
55
+ destination and ingress; never expose an unauthenticated SOCKS/admin listener.
56
+
57
+ For selective routing, explicitly scope clients/destinations and exclude router
58
+ management, container traffic and the remote server to avoid loops. Preserve the
59
+ remote server route through the real WAN and the return path to LAN/VPN clients.
60
+ For all-traffic routing, design fail-closed behavior for both IP families, including
61
+ existing connections, rule ordering and FastTrack. A low-priority drop after broad
62
+ accepts is not a kill switch. Do not silently replace the router's main default.
63
+
64
+ ## Deploy and verify, only after approval
65
+
66
+ Use the target's verified env/mount syntax; current list=/envlists/mountlists and
67
+ legacy name=/envlist/mounts are not interchangeable. Protect secrets in inputs.
68
+ Add exactly one image source and a unique name, VETH and dedicated root path.
69
+ After add, poll with a deadline for positive fully-stopped evidence before start.
70
+ Use the fresh stable .id. A timeout may have applied: inspect before retrying.
71
+
72
+ Confirm process state, sanitized application handshake and health separately.
73
+ Test DNS/IPv4/IPv6 egress from a representative selected LAN client, not only
74
+ router-originated fetch. Verify an unselected client remains on its intended path
75
+ and unauthorized access is denied. Test the approved failure scenario without
76
+ disrupting unrelated clients. Measure PMTU before MTU/MSS changes; do not assume
77
+ encapsulation is the only cause of a stalled download.
78
+
79
+ Enable start-on-boot only after checks and approval. Schedule a reboot test
80
+ separately. Report applied changes, observed results, pending/unknown tests and
81
+ recovery steps with secrets masked; no claim of success from running alone.
@@ -1,47 +1,41 @@
1
1
  ---
2
2
  name: setup-vlan-network
3
- title: Design and deploy VLAN segments
4
- description: Create isolated VLAN segments with gateway addressing, DHCP, and inter-VLAN firewall policy — previewed before apply.
3
+ title: Design a safe dual-stack VLAN migration
4
+ description: Audit the existing topology and plan VLAN ports, SSIDs, management access, IPv4/IPv6 policy and staged verification before any approved change.
5
5
  arguments:
6
6
  - name: vlans
7
7
  description: Describe the VLANs you need — e.g. "management=10, staff=20, IoT=30, guest=40" (name=VLAN-ID).
8
8
  required: true
9
9
  - name: trunk_interface
10
- description: The interface to use as a VLAN trunk (e.g. "ether1", "bridge"). If omitted, the main bridge is used.
10
+ description: Optional proposed physical trunk. If omitted, discover and confirm the port map; never assume a bridge or WAN port is the trunk.
11
11
  required: false
12
12
  ---
13
13
 
14
- Design and deploy a VLAN-segmented network on this MikroTik device. Each VLAN
15
- gets its own subnet, gateway IP, DHCP server, and firewall isolation. All changes
16
- are previewed before applying.
14
+ Plan a VLAN-segmented network on the explicitly selected MikroTik device.
15
+ Start read-only. A design request is NOT permission to apply it.
17
16
 
18
17
  VLANs requested: {{vlans}}
19
18
  Trunk interface: {{trunk_interface}}
20
19
 
21
- Follow these steps — confirm the plan before applying any changes:
22
-
23
- 1. **Understand the current layout.** Call `list_interfaces`, `list_bridges`,
24
- `list_ip_addresses`, and `list_dhcp_servers` to understand what exists.
25
-
26
- 2. **Design each VLAN segment.** For each VLAN in {{vlans}}, call
27
- `design_network_segment` in **preview mode** with:
28
- - VLAN ID and name.
29
- - A subnet (auto-assigned or specified — e.g. 10.10.{vlan_id}.0/24).
30
- - Gateway address (.1 in the subnet).
31
- - DHCP pool range.
32
- - Isolation policy (whether this VLAN can reach others).
33
-
34
- 3. **Review the plan.** Present a summary table:
35
- - VLAN ID, name, subnet, gateway, DHCP range.
36
- - Firewall rules that will be created for inter-VLAN isolation.
37
- - Bridge/trunk configuration changes.
38
-
39
- 4. **Apply.** With user approval, run `design_network_segment` again with apply
40
- mode for each VLAN.
41
-
42
- 5. **Verify.** Call `list_vlan_interfaces` to confirm VLANs are created,
43
- `list_ip_addresses` for gateway IPs, `list_dhcp_servers` for DHCP, and
44
- `list_filter_rules` for the isolation firewall rules.
45
-
46
- Report the complete VLAN map and any follow-ups (e.g. switch port VLAN
47
- assignments, wireless SSID-to-VLAN mappings).
20
+ 1. Discover the current bridge, ports, CPU membership, Wi-Fi package/SSID mapping,
21
+ addresses, DHCP, IPv6, both firewall families and routing dependencies using
22
+ `find_tools`. Resolve management/recovery access and ambiguous port roles first.
23
+ 2. Present a per-device VLAN map: role, ID, subnet, gateway, DHCP pool, IPv6 /64,
24
+ SSID, access ports/PVIDs, allowed trunk VLANs and bridge/CPU membership. Do not
25
+ allocate conflicting subnets or assume every role needs its own VLAN.
26
+ 3. Show an IPv4/IPv6 INPUT and FORWARD service matrix and exact rule placement.
27
+ Include remote-site return routes and VPN allowed-addresses only if affected.
28
+ Flag policy routing, NAT, FastTrack, queues and scripts tied to old interfaces.
29
+ 4. Present ordered steps, prerequisites, backup/rollback and canary tests. Enable
30
+ filtering LAST; do not disable existing filtering during migration. Do not
31
+ silently renumber the working LAN or expose management to every trusted client.
32
+ 5. `design_network_segment` may preview partial IPv4 scaffolding only. It is NOT
33
+ a full migration or isolation engine. Discover its schema and account for all
34
+ omitted L2/SSID/INPUT/IPv6/routing work; do not apply it once per VLAN blindly.
35
+ 6. Stop for approval of the exact changes. For approved dependent multi-router
36
+ writes, use the coordinated transaction workflow if available and suitable.
37
+ Never run transaction verification during a read-only audit: it performs writes.
38
+ 7. After approved changes, read back and test real wired and wireless clients for
39
+ intended allows AND denies over both families. List unverified tests explicitly;
40
+ configuration creation alone is not proof of isolation. Clean up only after
41
+ validation and dependency review, with separate approval for removals.