mt-wall 0.1.0

data/docs/gitops.md

@@ -0,0 +1,173 @@
+# GitOps workflow
+
+mt-wall is built for a Terraform-style loop: your firewall lives as DSL in git,
+**plan runs on every pull request** (read-only), and **apply runs on merge to
+the main branch**. The CLI's exit codes and `--json` output are designed to wire
+straight into CI.
+
+## Recommended repo layout
+
+The CLI loads a directory **recursively**, picking up every `*.rb` under it in
+deterministic sorted order and folding them into **one** Configuration. Split
+the config by concern:
+
+```
+firewall-repo/
+├── config/
+│   ├── objects.rb          # hosts + groups (Layer A)
+│   ├── services.rb         # named protocol/port definitions
+│   ├── policy.rb           # access grants + global chain defaults
+│   └── devices/
+│       ├── edge-1.rb       # per-box firewall (Layer B)
+│       └── edge-2.rb
+├── Gemfile                 # gem "mt-wall"
+└── .github/workflows/mt-wall.yml
+```
+
+Then every command targets the directory:
+
+```console
+$ mt-wall validate config/
+$ mt-wall plan     config/
+$ mt-wall apply    config/
+```
+
+A complete working example is in [`../examples/`](../examples/).
+
+> Load order is deterministic: files passed directly load in the order given;
+> a directory's `*.rb` files load in lexicographic order. Because all files
+> fold into one Configuration, hosts/services/grants defined in one file are
+> visible to device blocks in another.
+
+## The loop
+
+### On a pull request — validate + plan (read-only)
+
+```console
+$ mt-wall validate config/      # compiles every device; no network access
+$ mt-wall plan config/          # diffs each device against its live state
+```
+
+`validate` never touches a device — it only loads and compiles the DSL, so it
+catches typos, unknown references, cycles, lockout risks and zero-resolution
+errors. `plan` is **read-only**: it fetches current state and prints the diff,
+but mutates nothing. Both are safe to run on untrusted PR branches.
+
+### On merge to main — apply
+
+```console
+$ mt-wall apply --auto-approve config/
+```
+
+`apply` converges each changed device under the device-side commit-confirm
+envelope (see [security.md](security.md)). Run it only on the trusted path
+(merge to main), with credentials available as CI secrets.
+
+## Fleets and targeting
+
+`plan` and `apply` operate on **every device** in the loaded Configuration by
+default, printing a per-device section followed by a rollup line:
+
+```
+Devices: 3  |  with changes: 1  |  no-change: 2  |  failed: 0
+```
+
+Use `--device NAME` to target a subset; it is **repeatable**:
+
+```console
+$ mt-wall plan  --device edge-1 config/
+$ mt-wall apply --device edge-1 --device edge-2 --auto-approve config/
+```
+
+An unknown device name fails fast. During a fleet run, a transport failure on
+one device is captured (reported as `failed`) so the rest of the fleet is still
+planned/applied.
+
+## Posting the plan to a PR — `--json`
+
+`plan --json` and `validate --json` emit machine-readable output instead of
+text — ideal for posting the plan as a PR comment or gating a downstream step.
+
+`plan --json` produces a top-level object keyed by device name; each carries its
+host, a `changed` flag, summary counts, and the per-path operations:
+
+```json
+{
+  "edge-1": {
+    "host": "192.0.2.1",
+    "changed": true,
+    "summary": { "create": 12, "update": 0, "move": 0, "delete": 0, "total": 12 },
+    "operations": [
+      { "action": "create", "path": "/ip/firewall/filter",
+        "identity": "input accept (ssh mgmt)", "comment": "mt-wall:… | ssh mgmt",
+        "payload": { "chain": "input", "action": "accept", "...": "..." } }
+    ]
+  }
+}
+```
+
+`validate --json` emits `{ "valid": true, "devices": [...] }` (or `valid:
+false` with per-device `errors`). Exit codes are identical to text mode.
+
+A typical PR step runs `mt-wall plan --json config/ > plan.json` and posts it as
+a comment with your CI's GitHub API helper.
+
+## Exit codes
+
+Aggregated across the fleet, Terraform-style:
+
+| code | meaning                                                              |
+| ---- | ------------------------------------------------------------------- |
+| `0`  | success / no device has pending changes                             |
+| `2`  | **`plan` only** — success, but at least one device has changes      |
+| `1`  | error: invalid DSL, unknown device, transport/plan failure, bad args, apply aborted/refused, or any device failed during apply |
+
+CI uses these directly:
+
+- **PR gate:** run `mt-wall validate` then `mt-wall plan`. Exit `1` fails the
+  build; exit `2` means "there is work to apply" (surface it, don't fail);
+  exit `0` means in sync.
+- **Apply gate:** run `mt-wall apply --auto-approve`. Exit `0` = converged,
+  `1` = something failed (the device-side auto-revert protects against lockout).
+
+## Non-interactive apply — `--auto-approve` and TTY behavior
+
+`apply` is gated by a confirmation prompt (Terraform-style):
+
+```
+Apply these changes to edge-1, edge-2? Only 'yes' will be accepted:
+```
+
+Only the exact string `yes` proceeds; anything else cancels (exit `1`, no
+changes made). In CI there is no TTY, so:
+
+- **without `--auto-approve` on a non-interactive stdin, apply is refused** —
+  it prints `Refusing to apply without a TTY; re-run with --auto-approve …` and
+  exits `1`. mt-wall never blocks waiting for input in a pipeline.
+- **`--auto-approve` skips the prompt** — use it for the merge-to-main job.
+
+If no device has pending changes, `apply` reports up-to-date and exits `0`
+without prompting.
+
+## Adapting to GitLab CI / others
+
+The contract is the CLI's exit codes and stdout/JSON — nothing GitHub-specific.
+A GitLab `.gitlab-ci.yml` mirrors the GitHub workflow:
+
+```yaml
+plan:
+  rules: [{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]
+  script:
+    - bundle exec mt-wall validate config/
+    - bundle exec mt-wall plan config/        # exit 2 = changes; allow it
+  allow_failure: { exit_codes: [2] }
+
+apply:
+  rules: [{ if: '$CI_COMMIT_BRANCH == "main"' }]
+  script:
+    - bundle exec mt-wall apply --auto-approve config/
+  # MT_WALL_EDGE_1_USER / _PASSWORD etc. set as masked CI/CD variables
+```
+
+See [.github/workflows/mt-wall.yml](../.github/workflows/mt-wall.yml) for the
+fully-commented GitHub Actions version.

data/docs/security.md

@@ -0,0 +1,142 @@
+# Security & safety
+
+mt-wall treats security as a first-class concern: credentials never live in the
+DSL, plaintext transport is refused by default, applies are protected by a
+device-side auto-revert, and the tool's ownership model is explicit about what
+it replaces.
+
+## Credentials live only in ENV — never in the DSL or git
+
+The `device` block references a host + transport. It does **not** carry
+credentials. The REST transport reads them from environment variables at apply
+time, using a canonical, collision-checked derivation from the device name.
+
+**Name derivation:** the device name is upcased, every run of non-`[A-Z0-9]`
+characters collapses to a single `_`, and leading/trailing `_` are stripped:
+
+| device name | ENV prefix          | variables read                                |
+| ----------- | ------------------- | --------------------------------------------- |
+| `edge-1`    | `MT_WALL_EDGE_1`    | `MT_WALL_EDGE_1_USER`, `MT_WALL_EDGE_1_PASSWORD` |
+| `core.fw`   | `MT_WALL_CORE_FW`   | `MT_WALL_CORE_FW_USER`, `MT_WALL_CORE_FW_PASSWORD` |
+| `dc1-edge`  | `MT_WALL_DC1_EDGE`  | `MT_WALL_DC1_EDGE_USER`, `MT_WALL_DC1_EDGE_PASSWORD` |
+
+A missing or empty expected variable **fails fast** with a `TransportError`
+naming the variable to set. If two distinct device names would collapse to the
+same prefix (silently sharing one credential), that is also a fail-fast error.
+
+`validate` and `plan` that don't reach a device need no credentials; `plan`
+against a live device and `apply` do.
+
+## Wiring credentials into CI
+
+Store each device's user/password as a **secret** in your CI provider and map it
+into the job's environment — never echo it, never commit it.
+
+```yaml
+# GitHub Actions (apply job)
+env:
+  MT_WALL_EDGE_1_USER: ${{ secrets.MT_WALL_EDGE_1_USER }}
+  MT_WALL_EDGE_1_PASSWORD: ${{ secrets.MT_WALL_EDGE_1_PASSWORD }}
+  MT_WALL_EDGE_2_USER: ${{ secrets.MT_WALL_EDGE_2_USER }}
+  MT_WALL_EDGE_2_PASSWORD: ${{ secrets.MT_WALL_EDGE_2_PASSWORD }}
+```
+
+mt-wall **redacts credentials centrally**: the password never appears in any
+URL, log line, exception message, or rendered `.rsc` artifact (a dedicated test
+enforces this). The transport's `inspect`/`to_s` prints host/port/user and a
+`secure?` flag only.
+
+## Transport security: TLS by default, plaintext refused
+
+The REST transport talks to `https://<host>/rest/…` over HTTP Basic auth.
+Because Basic-auth credentials would travel in clear text otherwise:
+
+- **Plaintext HTTP is refused.** Targeting port 80 raises a `TransportError`
+  unless you opt in *loudly* — either the device option `insecure_http: true`
+  or the env var `MT_WALL_INSECURE_HTTP` (`1`/`true`/`yes`). Reserve this for a
+  lab; it is never appropriate against a production device.
+- **TLS verification is on.** Prefer pinning over disabling verification:
+
+  | device option            | effect                                                |
+  | ------------------------ | ----------------------------------------------------- |
+  | `ca_file: "ca.pem"`      | verify against a specific CA bundle / pinned cert     |
+  | `tls_fingerprint: "ab:…"`| pin the server leaf cert's SHA-256 fingerprint        |
+  | `verify_tls: false`      | blanket-disable verification — discouraged, explicit opt-out |
+
+```ruby
+device "edge-1", host: "192.0.2.1", transport: :rest_api,
+                 tls_fingerprint: "AA:BB:CC:…" do
+  # …
+end
+```
+
+## Fail-safe apply: device-side commit-confirm
+
+mt-wall owns and *replaces* the whole filter/NAT table — over a network path
+that often runs **through that very firewall**. A client-side rollback is
+undeliverable if the link drops, and RouterOS REST has no firewall
+transaction/safe-mode. So `apply` uses a **device-side** commit-confirm
+envelope:
+
+1. **Arm.** The transport takes a full backup **on the device** and schedules a
+   `/system/scheduler` job that restores it after `revert_timeout` seconds
+   (default 120, per-device via `revert_timeout:`). The backup is taken *before*
+   the revert machinery is created, so a fired revert also discards itself.
+2. **Apply.** Operations run in fail-safe order (open access + management-protect
+   before tightening; create-before-delete; default-drop last — encoded by the
+   planner).
+3. **Health-check.** The manager re-reaches the device and confirms the input
+   chain still admits management traffic, retrying briefly to tolerate a
+   post-apply blip.
+4. **Confirm.** On success the transport cancels the scheduled revert. **If the
+   health-check fails or the link is lost, confirm never runs and the device
+   self-restores the backup at timeout** — a bad apply heals itself.
+
+The offline `:rsc` transport has no live link to protect, so it renders the
+script and skips the envelope.
+
+## Recommended least-privilege RouterOS user
+
+Create a dedicated user for mt-wall rather than reusing `admin`. It needs to
+read/write the firewall tables and operate the commit-confirm machinery
+(backup + scheduler/script), reachable over the REST service:
+
+- **Group permissions:** `api`, `rest-api`, `read`, `write`, `policy`, `test`,
+  and (for the auto-revert) `sensitive` to create the backup/scheduler/script.
+- **Restrict the source.** Limit the user (or the `www-ssl`/`api` service) to
+  the management subnet you declared via `management src:`, so the credential is
+  useless from anywhere else.
+- **Enable only the TLS REST service** (`www-ssl`) with a real certificate;
+  disable plaintext `www` if you are not in a lab.
+
+```routeros
+/user group add name=mt-wall policy=api,rest-api,read,write,policy,test,sensitive
+/user add name=mt-wall group=mt-wall password=… address=10.0.0.0/24
+/ip service set www-ssl disabled=no address=10.0.0.0/24
+/ip service set www disabled=yes
+```
+
+## Full-table ownership — know what apply replaces
+
+Ownership is **per-table, not uniform**:
+
+- **Filter & NAT tables** (`/ip/firewall/filter`, `/ipv6/firewall/filter`,
+  `/ip/firewall/nat`) are owned **wholesale**. `apply` makes the device's table
+  match the compiled desired state **in full** — including removing RouterOS
+  default-config rules and any rule mt-wall did not emit. Everything you want on
+  these chains must be expressed in the DSL.
+- **Address-lists** (`/ip/firewall/address-list`, `/ipv6/firewall/address-list`)
+  are owned **only for the list names mt-wall emits** from your hosts/groups.
+  Foreign/static lists (operator- or script-maintained) are never read into the
+  diff, never modified, never deleted. Address-list rows diff by the natural key
+  `(list, address)`.
+
+Every managed filter/NAT rule carries a content-only `mt-wall:<hash>` identity
+tag in its comment, so the diff matches rules by content + position rather than
+volatile device `.id`. RouterOS-generated `dynamic` rows are excluded from the
+fetched state and are never diffed or deleted.
+
+> **Implication:** before adopting mt-wall on a device with hand-built rules,
+> capture those rules into the DSL first — otherwise the first `apply` will
+> remove anything not represented. Use `plan` (read-only) to preview exactly
+> what would change.

data/examples/README.md

@@ -0,0 +1,67 @@
+# Example: a 2-device edge fleet
+
+A small, **runnable** mt-wall configuration for a two-router fleet (`edge-1`,
+`edge-2`). It exercises the full DSL surface: hosts/groups/services, Layer-A
+access grants, per-box chains, NAT, management carve-outs, logging, dual-stack
+rules and per-device options.
+
+## Layout
+
+```
+examples/config/
+├── objects.rb            # Layer A: hosts + groups (address objects)
+├── services.rb           # Layer A: named protocol/port definitions
+├── policy.rb             # Layer A: access grants + global chain defaults
+└── devices/
+    ├── edge-1.rb         # Layer B: primary edge — chains, NAT, management
+    └── edge-2.rb         # Layer B: branch edge — fasttrack off, output chain
+```
+
+All files fold into **one** Configuration when the directory is loaded, so the
+hosts/services/grants in the top three files are visible to both device blocks.
+
+## What it shows
+
+- **Layer A** (`objects.rb`, `services.rb`, `policy.rb`): hosts holding single
+  addresses, arrays and a CIDR; group membership both group-side (`member`) and
+  host-side (positional, auto-creating `trusted-resolvers`); a multi-protocol
+  service (`dns` = tcp+udp); a port range (`web-highports`); allow + an explicit
+  logged `:deny` grant; global `policy` defaults.
+- **edge-1** (`devices/edge-1.rb`): locked input chain with a required
+  `management` carve-out, IPv4 + pinned IPv6 rules, interface-list drop with
+  logging, a logged forward default, and a `nat` block (masquerade +
+  port-forward `dst_nat`).
+- **edge-2** (`devices/edge-2.rb`): per-device options (`fasttrack: false`,
+  `revert_timeout: 180`), a `reject` rule, an `output` chain, and a built-in
+  management service (`winbox`).
+
+## Run it
+
+From the gem checkout root:
+
+```console
+# Validate — compiles every device, no network access. Exits 0.
+$ bundle exec mt-wall validate examples/config
+OK: configuration is valid (2 device(s) compiled).
+
+# Machine-readable validation.
+$ bundle exec mt-wall validate --json examples/config
+```
+
+`plan` and `apply` would reach the (fictional) devices over REST and therefore
+need credentials in ENV — they won't connect to `192.0.2.x`, but this is the
+shape:
+
+```console
+$ export MT_WALL_EDGE_1_USER=ci MT_WALL_EDGE_1_PASSWORD=secret
+$ export MT_WALL_EDGE_2_USER=ci MT_WALL_EDGE_2_PASSWORD=secret
+$ bundle exec mt-wall plan examples/config              # read-only diff
+$ bundle exec mt-wall plan --device edge-1 examples/config
+$ bundle exec mt-wall apply --auto-approve examples/config
+```
+
+To render an offline RouterOS `.rsc` script instead of touching a device,
+switch a device's `transport:` to `:rsc`.
+
+See [../docs/dsl-reference.md](../docs/dsl-reference.md) for every verb and
+[../docs/gitops.md](../docs/gitops.md) for the CI loop.

data/examples/config/devices/edge-1.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Layer B — the per-box firewall for the primary edge router.
+#
+# The device block configures THIS router's own input/output/forward chains and
+# NAT. The Layer-A grants from policy.rb are injected into its forward chain
+# automatically. Credentials are NEVER here — the REST transport reads them from
+# MT_WALL_EDGE_1_USER / MT_WALL_EDGE_1_PASSWORD at apply time.
+device "edge-1", host: "192.0.2.1", transport: :rest_api do
+  policy :input,   :drop
+  policy :forward, :drop, log: true, log_prefix: "fwd-drop" # log the default
+
+  # Declare the mgmt traffic the safe chain must keep open so an apply can never
+  # lock you out. REQUIRED once the input chain is locked (policy :input, :drop).
+  # REPEATABLE: each call adds a protected path; the compiler emits their union.
+  management src: "admin", service: "ssh"   # human admins over SSH
+  management src: "ci",    port: 443        # CI runner applying over REST/HTTPS
+
+  input do
+    allow_established                                    # accept established,related
+    drop_invalid                                         # drop invalid
+    accept protocol: :icmp                               # IPv4 ping
+    accept protocol: :icmpv6, family: :ip6               # IPv6 ping (pinned)
+    accept protocol: :tcp, dst_port: 22,   src: "admin", comment: "ssh mgmt"
+    accept protocol: :tcp, dst_port: 8291, src: "admin", comment: "winbox mgmt"
+    # in_interface_list references an operator-defined /interface/list on the box
+    # (mt-wall does not manage /interface/list in v1).
+    drop in_interface_list: "WAN", log: true, log_prefix: "wan-input-drop"
+  end
+
+  forward do
+    allow_established
+    drop_invalid
+    # Layer-A grants are injected here, then the forward default policy.
+  end
+
+  nat do
+    masquerade out_interface: "ether1-wan"               # hide LAN behind WAN
+    dst_nat protocol: :tcp, dst_port: 443,               # publish web (port-fwd)
+            in_interface: "ether1-wan",
+            to_addresses: "10.0.10.5", to_ports: 8443,
+            comment: "publish web"
+  end
+end

data/examples/config/devices/edge-2.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Layer B — the per-box firewall for the branch edge router.
+#
+# Shows per-device options: `fasttrack: false` suppresses the default IPv4
+# forward fasttrack rule (so mangle/queues/IPsec see every packet), and
+# `revert_timeout:` tunes how long the device-side auto-revert waits before
+# self-restoring if an apply never confirms. Credentials come from
+# MT_WALL_EDGE_2_USER / MT_WALL_EDGE_2_PASSWORD.
+device "edge-2", host: "192.0.2.2", transport: :rest_api,
+                 fasttrack: false, revert_timeout: 180 do
+  policy :input,   :drop
+  policy :forward, :drop
+
+  management src: "admin", service: "winbox"
+
+  input do
+    allow_established
+    drop_invalid
+    accept protocol: :icmp
+    accept protocol: :tcp, dst_port: 8291, src: "admin", comment: "winbox mgmt"
+    # reject (sends an ICMP/TCP-reset) external DNS probing on the WAN list.
+    reject protocol: :udp, dst_port: 53, in_interface_list: "WAN",
+           comment: "reject external dns"
+    drop in_interface_list: "WAN", log: true, log_prefix: "wan-drop"
+  end
+
+  forward do
+    allow_established
+    drop_invalid
+    accept protocol: :icmpv6, family: :ip6
+  end
+
+  output do
+    accept comment: "allow all router-originated traffic"
+  end
+
+  nat do
+    masquerade out_interface: "ether1-wan", comment: "branch nat"
+  end
+end

data/examples/config/objects.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Layer A — portable address objects (hosts) and groups.
+#
+# A `host` is a named address object: one or more IPs / CIDR subnets / IP
+# ranges. It compiles to entries in /ip firewall address-list (IPv4) and/or
+# /ipv6 firewall address-list (IPv6); family is inferred per address.
+#
+# A `group` bundles hosts (and/or other groups) under one name. Groups have no
+# native RouterOS equivalent (address-lists are not nestable), so they are
+# FLATTENED at compile time into the union of their members' addresses.
+
+# The management network — operators / CI run from here.
+host "admin" do
+  address "10.0.0.0/24"
+end
+
+host "monitoring", address: "10.0.0.50"
+
+# The CI runner that applies the firewall over the REST transport. It reaches
+# the box from a different source than the human admins, so it needs its own
+# management carve-out (see edge-1.rb) or an apply would lock the runner out.
+host "ci", address: "198.51.100.10"
+
+# Frontend tier (one host may hold several addresses).
+host "web", address: ["10.0.10.5", "10.0.10.6"]
+host "api", address: "10.0.10.20"
+
+# Backend tier.
+host "db",    address: "10.0.20.10"
+host "cache", address: "10.0.20.11"
+
+# A host can join groups from its own side — trailing positional args after the
+# name are group names (here "trusted-resolvers" is created on demand).
+host "ext-dns", "trusted-resolvers", address: ["1.1.1.1", "8.8.8.8"]
+
+# Group membership can also be declared group-side; both sides are unioned.
+group "frontend" do
+  member "web"
+  member "api"
+end
+
+group "backend" do
+  member "db"
+  member "cache"
+end

data/examples/config/policy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Layer A — access grants and global chain defaults.
+#
+# Access grants are device-agnostic: the Compiler injects them into every
+# managed device's FORWARD chain. `rule <source>` opens a block of `to` lines;
+# each `to` is one grant to a destination, with an optional service (omitted =
+# any) and an optional action (:allow by default, or :deny).
+
+rule "frontend" do
+  to "db",    "mysql"            # frontend -> db over mysql (allow)
+  to "cache", "redis"
+  to "trusted-resolvers", "dns" # frontend -> upstream resolvers (tcp + udp)
+end
+
+rule "admin" do
+  to "frontend", :any           # admins reach the frontend over anything
+  to "backend",  "ssh"
+end
+
+# An explicit, logged deny. The action is the optional last positional arg, so
+# to set it you must also give a service (or :any).
+rule "monitoring" do
+  to "backend", "ssh", :deny, log: true, log_prefix: "mon-ssh-deny"
+end
+
+# Global chain defaults — the trailing default rule of each chain. Overridable
+# per device inside the `device` block.
+policy :forward, :drop
+policy :input,   :drop

data/examples/config/services.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Layer A — named protocol/port definitions, referenced by name from rules.
+#
+# `protocol:` (singular) and `protocols:` (multi) are both accepted. A
+# multi-protocol service (e.g. DNS = tcp + udp) compiles to ONE filter rule per
+# protocol. Ports keep their spec form (Integer / Array / Range / "a-b"), so a
+# range stays a range (dst-port=8000-8100) instead of exploding into a list.
+
+service "https", protocol: :tcp, ports: [443]
+service "http",  protocol: :tcp, ports: [80]
+service "ssh",   protocol: :tcp, ports: [22]
+
+service "mysql", protocol: :tcp, ports: [3306]
+service "redis", protocol: :tcp, ports: [6379]
+
+service "dns",   protocols: %i[tcp udp], ports: [53] # -> two filter rules
+
+service "web-highports", protocol: :tcp, ports: ["8000-8100"] # port range

data/exe/mt-wall

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mt/wall"
+
+exit(Mt::Wall::CLI.start(ARGV))