mt-wall 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75da164184f13565293e6f92906f5049a4257cac787331c8ad1e9187e2b68eb8
+  data.tar.gz: cadfbf29f23fe5fc074e637173750d8a0b0caf4fc80a5c0e36336771e0d427f7
+SHA512:
+  metadata.gz: 103cb312a753cf8577ca46fb04dc6c42a5223bb7e4a1ae29f80ec2c205f318ce107456e46e1e5f2a1c45a134a12be7b329e634210b1933a458255f3ede774d19
+  data.tar.gz: c126a11f5197265a9750b06134e2c11aca60a36dc07800566120fcb892ff2643dca90a34f1981df426ed0bc31d3aadf74749ea36e3583c0fe112a2c5d1abeee9

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-27
+
+First usable release: a complete DSL → plan/apply pipeline for MikroTik
+(RouterOS v7+) firewalls, GitOps-ready and stdlib-only (no runtime gem
+dependencies).
+
+### Added
+
+- **Two-layer DSL** (`Mt::Wall.define { … }` / `Mt::Wall.load(*paths)`):
+  - **Layer A — portable access policy**: `host` (named addresses / CIDR /
+    IP ranges), `group` (flattened at compile time — RouterOS lists are not
+    nestable), `service` (single- or multi-protocol + ports), `rule …/to …`
+    access grants, and global `policy` chain defaults.
+  - **Layer B — per-box firewall**: `device` with nested `policy` overrides,
+    `management`, `input`/`output`/`forward` chain blocks
+    (`accept`/`drop`/`reject` + `allow_established`/`drop_invalid` helpers), and
+    a `nat` block.
+- **Compiler** producing a normalized, diffable `DesiredState` keyed by RouterOS
+  path:
+  - family-specific **safe chain** (IPv4 stateful preamble + suppressible
+    fasttrack; IPv6 ICMPv6/NDP/PMTUD/DHCPv6 essentials), input-only
+    management-protection with lockout fail-fast, and the trailing default-policy
+    rule.
+  - **IPv6 dual-stack**: per-address family inference, per-family address-list
+    partitioning, and auto-scoping of unscoped rules to the families their
+    references resolve in (explicit `family:` keeps a strict check).
+  - **IPv4 NAT** (`masquerade`/`dst_nat`/`src_nat`) with mandatory scoping.
+  - content-only `mt-wall:` **identity tags** so `log`/`disabled` toggles are
+    in-place updates, never delete+create churn.
+- **Firewall primitives**: `log`/`log_prefix`/`disabled` rule attributes,
+  interface-list matches (`in_interface_list:`/`out_interface_list:`), IP ranges,
+  multi-protocol services, and the reserved **`"any"`** match-all
+  source/destination (omits the address-list field, imposes no family
+  constraint; distinct from the `:any` service slot; `"any"` is reserved as a
+  host/group name).
+- **Plan/diff** with create/update/delete/**move** operations matched by
+  `(tag, ordinal)`; per-table ownership (filter/nat wholesale, address-lists by
+  managed list names and `(list, address)`).
+- **REST transport** (RouterOS v7+) with credentials from ENV (never the DSL),
+  TLS-by-default and credential redaction, and device-side **commit-confirm**
+  (arm auto-revert → apply → health-check → confirm) for fail-safe apply. An
+  offline **`.rsc`** rendering adapter is also included.
+- **CLI** `mt-wall validate | plan | apply` for the GitOps loop, with fleet
+  selection, `--json` output, and `--auto-approve`.
+- **Fail-fast validation** at the DSL/model boundary (names, addresses, ports,
+  protocols, flags, `log_prefix` charset) to catch typos early and neutralize
+  `.rsc` / JSON injection.
+
+[0.1.0]: https://github.com/wojcieszonek/mt-wall/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Piotr Wojcieszonek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# mt-wall
+
+**Firewall-as-code for MikroTik RouterOS v7+.** Describe your firewall as a
+declarative Ruby DSL, keep it in git, and reconcile it onto devices with a
+Terraform-style **plan / apply** workflow: run `plan` on a pull request to see
+the diff, run `apply` on merge to converge each device. mt-wall owns the
+filter/NAT tables wholesale, tags every rule it manages, and applies changes
+under a device-side commit-confirm envelope that auto-reverts if an apply locks
+you out — so a bad merge heals itself instead of stranding a router.
+
+```ruby
+host "web", address: "10.0.10.5"
+host "db",  address: "10.0.20.10"
+group "frontend" do
+  member "web"
+end
+service "mysql", protocol: :tcp, ports: [3306]
+
+rule "frontend" do
+  to "db", "mysql"          # frontend -> db over mysql (allow)
+end
+
+policy :forward, :drop      # default-drop the forward chain
+
+device "edge-1", host: "192.0.2.1", transport: :rest_api do
+  policy :input, :drop
+  management src: "admin", service: "ssh"
+  input do
+    allow_established
+    drop_invalid
+    accept protocol: :tcp, dst_port: 22, src: "admin"
+  end
+end
+```
+
+## 60-second quickstart
+
+```console
+$ git clone <your firewall-config repo> && cd it
+$ bundle install
+
+# 1. Validate the DSL — compiles every device, no network access.
+$ bundle exec mt-wall validate config/
+OK: configuration is valid (2 device(s) compiled).
+
+# 2. Plan — read-only diff against each live device.
+$ export MT_WALL_EDGE_1_USER=ci MT_WALL_EDGE_1_PASSWORD=…
+$ bundle exec mt-wall plan config/
+Device edge-1 (192.0.2.1):
+  /ip/firewall/filter
+    + create input accept (ssh mgmt)
+    …
+  Plan: 12 to create.
+Devices: 1  |  with changes: 1  |  no-change: 0  |  failed: 0
+
+# 3. Apply — converge the fleet (prompts for 'yes'; --auto-approve in CI).
+$ bundle exec mt-wall apply config/
+```
+
+A ready-to-run sample fleet lives in [`examples/`](examples/) — try
+`bundle exec mt-wall validate examples/config`.
+
+## The two-layer mental model
+
+mt-wall separates *what may talk to what* from *how each box is firewalled*.
+
+- **Layer A — portable access policy.** `host`, `group`, `service` and
+  `rule … to …` describe a device-agnostic policy: named address objects and the
+  grants between them. The Compiler injects every grant into the **forward**
+  chain of *every* managed device. Write it once; it applies fleet-wide.
+- **Layer B — the per-box firewall.** The `device` block configures one
+  router's own `input` / `output` / `forward` chains, its `nat` table, chain
+  `policy` defaults, and the `management` carve-out. This is where
+  box-specific interfaces, NAT and logging live.
+
+See [docs/dsl-reference.md](docs/dsl-reference.md) for every verb.
+
+## Key safety properties
+
+- **Full-table ownership with identity tags.** mt-wall owns the
+  `/ip/firewall/filter`, `/ipv6/firewall/filter` and `/ip/firewall/nat` tables
+  *wholesale* — apply replaces them in full, including RouterOS default-config
+  rules. Every managed rule carries a content-only `mt-wall:<hash>` tag in its
+  comment, so the diff matches rules by content + position, never by volatile
+  device `.id`. Address-lists are owned only for the *names* mt-wall emits;
+  foreign/static lists are never touched.
+- **Fail-safe ordering.** Each chain is assembled with stateful handling first
+  (`accept established,related` → `drop invalid`), management-protection on the
+  input chain, then operator/grant rules, and the default-drop **last** — the
+  Compiler fails fast if a locked input chain would lock out management.
+- **Device-side commit-confirm auto-revert.** `apply` backs up the managed
+  tables *on the device* and schedules a self-restore; it then applies, runs a
+  manager-side health-check, and only confirms (cancels the revert) if the box
+  is still reachable. If the link drops, the device reverts itself at timeout.
+- **Secrets only in ENV.** The DSL references a host + transport, never
+  credentials. The REST transport reads `MT_WALL_<DEVICE>_USER` /
+  `MT_WALL_<DEVICE>_PASSWORD`, refuses plaintext HTTP without a loud opt-in, and
+  redacts passwords from every log, error and rendered artifact. See
+  [docs/security.md](docs/security.md).
+
+## Install
+
+mt-wall is a Ruby gem with **no runtime dependencies** (REST over stdlib
+`net/http`, CLI over `optparse`). Ruby 3.x or newer.
+
+```ruby
+# Gemfile
+gem "mt-wall"
+```
+
+```console
+$ bundle install
+$ bundle exec mt-wall --help
+```
+
+Or build/install from this checkout:
+
+```console
+$ gem build mt-wall.gemspec && gem install mt-wall-*.gem
+```
+
+## CLI at a glance
+
+| Command                      | What it does                                            |
+| ---------------------------- | ------------------------------------------------------- |
+| `mt-wall validate <paths>`   | Load + compile the DSL. No device access. Exit 0 / 1.   |
+| `mt-wall plan <paths>`       | Read-only per-device diff. Exit 0 (no changes) / 2 (changes) / 1 (error). |
+| `mt-wall apply <paths>`      | Converge the fleet under commit-confirm. Exit 0 / 1.    |
+
+`<paths>` are `*.rb` files and/or directories (a directory loads every `*.rb`
+under it, recursively, in sorted order). Flags: `--device NAME` (repeatable;
+target a subset, default all), `--json` (machine-readable `plan`/`validate`),
+`--auto-approve` (non-interactive `apply` for CI). Full GitOps wiring in
+[docs/gitops.md](docs/gitops.md).
+
+## Status — v1 scope
+
+**Feature-complete and validated on RouterOS 7.16.2.** The full pipeline (DSL →
+compile → plan → apply), the firewall primitives (hosts/groups/services/grants,
+per-box chains, NAT, dual-stack IPv4/IPv6, logging) and the DevOps ergonomics
+(fleet, JSON, exit codes, commit-confirm) all work end to end.
+
+**Deferred to a future release:**
+
+- **FQDN address-list entries** — addresses are IP / CIDR / IP-range only.
+- **Managing `/interface/list`** — `in_interface_list:` / `out_interface_list:`
+  *reference* operator-defined lists on the box; mt-wall does not create them.
+- **IPv6 NAT** — the `nat` block is IPv4-only (no `/ipv6/firewall/nat`).
+- **Transports beyond REST + offline `.rsc`** — `BinaryApi` / `Ssh` are future
+  adapters.
+
+## Documentation
+
+- [docs/dsl-reference.md](docs/dsl-reference.md) — every verb, signature,
+  example and what it compiles to in RouterOS.
+- [docs/gitops.md](docs/gitops.md) — repo layout, plan-on-PR / apply-on-merge,
+  fleets, JSON, exit codes.
+- [docs/security.md](docs/security.md) — credentials, TLS, commit-confirm,
+  least-privilege users, ownership implications.
+- [examples/](examples/) — a runnable 2-device sample fleet.
+- [.github/workflows/mt-wall.yml](.github/workflows/mt-wall.yml) — a working CI
+  pipeline.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/docs/dsl-reference.md

@@ -0,0 +1,388 @@
+# DSL reference
+
+The mt-wall DSL is plain Ruby, evaluated either from a block
+(`Mt::Wall.define { … }`) or from files/directories (`Mt::Wall.load(*paths)`,
+which the CLI uses). Every value passes through fail-fast validators, so typos
+and unsafe input surface loudly at load/compile time rather than on a device.
+
+The verbs fall into **two layers**:
+
+- **Layer A — portable access policy** (`host`, `group`, `service`, `rule`,
+  `policy`): a device-agnostic model of named addresses and the grants between
+  them. Grants compile into the **forward** chain of *every* managed device.
+- **Layer B — the per-box firewall** (`device` and its nested `policy`,
+  `input` / `output` / `forward`, `nat`, `management`): one router's own chains
+  and NAT table.
+
+Top-level verbs: [`host`](#host) · [`group`](#group) · [`service`](#service) ·
+[`rule`](#rule) · [`policy`](#policy-global) · [`device`](#device).
+
+---
+
+## host
+
+A named address object: one or more IPs, CIDR subnets, or IP ranges. Compiles
+to entries in `/ip firewall address-list` (IPv4) and/or `/ipv6 firewall
+address-list` (IPv6). Family is inferred **per address** via stdlib `IPAddr`, so
+one host may mix v4 and v6.
+
+```ruby
+# Signature: host(name, *groups, address: nil, comment: nil) { ... }
+
+host "db", address: "10.0.2.10"                    # one-line shorthand
+host "web", address: ["10.0.0.5", "10.0.1.0/24"]   # array
+host "pool", address: "10.0.0.1-10.0.0.10"         # IP range (same family)
+
+host "web" do                                      # block form
+  address "10.0.0.5"
+  address "10.0.1.0/24"
+  member_of "web-prod", "web-wordpress"            # join groups, host-side
+end
+
+# Trailing positional args after the name are group names to join (sugar for
+# member_of). Referenced groups are created on demand.
+host "web", "web-prod", address: ["10.0.0.5", "10.0.1.0/24"]
+```
+
+- **Compiles to:** one address-list entry per address, under the list named
+  after the host. One address may belong to many hosts (many list memberships).
+- **`member_of` / positional groups** record membership on the *group* (the
+  single source of truth), not on the host. A group referenced only from the
+  host side is **auto-created**.
+- **Fail-fast:** a host with no addresses raises; a positional group token that
+  parses as an IP/CIDR raises (`"looks like an address — did you mean
+  address:?"`), guarding the `host "web", "10.0.0.5"` slip.
+
+## group
+
+Bundles hosts (and/or other groups) under one name. RouterOS address-lists are
+**not nestable**, so groups are **flattened** at compile time into the
+de-duplicated union of their members' addresses (recursively).
+
+```ruby
+# Signature: group(name, comment: nil) { member(name); ... }
+
+group "frontend" do
+  member "web"
+  member "api"
+end
+```
+
+- **Compiles to:** address-list entries under the group's name, one per address
+  across all (recursively flattened) members.
+- Membership may be declared group-side (`member`) or host-side (`member_of` /
+  positional args on `host`); both fold together.
+- Hosts and groups **share one name space** (both become address-list names), so
+  a host and a group may not share a name — the Compiler fails fast on a clash.
+- **Fail-fast:** a membership cycle, or a member that is neither a declared host
+  nor group, raises at compile time.
+
+## service
+
+A protocol (or protocols) plus ports, referenced by name from `rule … to`.
+
+```ruby
+# Signature: service(name, protocol: nil, protocols: nil, ports: [])
+
+service "mysql", protocol: :tcp, ports: [3306]
+service "ssh",   protocol: :tcp, ports: [22]
+service "dns",   protocols: %i[tcp udp], ports: [53]    # -> two filter rules
+service "highports", protocol: :tcp, ports: ["8000-8100"]  # range stays a range
+```
+
+- Use **`protocol:`** for one protocol or **`protocols:`** for several. A
+  multi-protocol service compiles to **one filter rule per protocol**.
+- **Ports** accept an Integer, Array, Range, or `"a-b"` / `"n"` String (nested
+  arrays allowed). They keep their spec form, so a range round-trips as
+  `dst-port=8000-8100` rather than exploding into a list.
+- **Compiles to:** the `protocol` + `dst-port` fields of the grant rules that
+  reference it.
+
+## rule
+
+Device-agnostic access grants (Layer A), grouped by source. Only the top level
+declares these; they compile onto the **forward** chain of every managed device.
+
+```ruby
+# Signature: rule(source) { to(dest, service = :any, action = :allow, **) ; ... }
+
+rule "frontend" do
+  to "db", "mysql"                 # frontend -> db over mysql (allow, default)
+  to "cache", "redis"
+  to "trusted-resolvers", "dns"    # multi-protocol service -> one rule per proto
+end
+
+rule "monitoring" do
+  to "backend", "ssh", :deny, log: true, log_prefix: "mon-ssh-deny", disabled: false
+  to "edge-3-mgmt"                 # no service = any
+end
+
+# "any" is a RESERVED match-all source/destination.
+rule "any" do
+  to "db", "https", :deny          # from anywhere -> db (no src-address-list)
+end
+rule "admin" do
+  to "any"                         # admin -> anywhere (no dst-address-list)
+end
+```
+
+> **Reserved `"any"` source/destination.** As a `rule` source, a `to`
+> destination, or a chain rule's `src:`/`dst:`, the name `"any"` is a *match-all*:
+> the compiled filter rule **omits** the corresponding
+> `src-address-list` / `dst-address-list` (RouterOS treats an absent list as
+> "match any"). It imposes **no family constraint** — the *other* (concrete)
+> endpoint decides the families (subject to an explicit `family:`); `any -> any`
+> emits into **both** v4 and v6. This is **distinct from the service slot
+> `:any`** (`to "frontend", :any`), which means *any protocol/port*. No host or
+> group may be named `"any"` — declaring one fails fast.
+
+**`to(destination, service = :any, action = :allow, comment:, log:, log_prefix:,
+disabled:)`**
+
+- `destination` — a host or group name.
+- `service` — a Service name, or `:any` (omit it). Omitting it matches any
+  protocol/port.
+- `action` — `:allow` (default) or `:deny`. It is the **last positional arg**,
+  so to set it you must give a service or `:any`: `to "db", :any, :deny`. The
+  footgun is guarded: `to "db", :deny` treats `:deny` as the action (service
+  stays `:any`); any other non-`:allow`/`:deny` symbol in the action slot raises.
+- `log:` / `log_prefix:` — log matched packets. `disabled:` — keep the grant in
+  git but inactive. These are rule **attributes** (see [rule
+  attributes](#rule-attributes-log--log_prefix--disabled)).
+- **Compiles to:** `/ip firewall filter` (and/or `/ipv6 firewall filter`) rules
+  on the `forward` chain, using `src-address-list` / `dst-address-list` from the
+  source/destination, plus `protocol` / `dst-port` from the service. `:allow` →
+  RouterOS `accept`, `:deny` → `drop`.
+
+## policy (global)
+
+A chain default — the trailing rule of a chain. Declared at the top level it is
+a global default; inside a `device` block the same verb **overrides** it for
+that box.
+
+```ruby
+# Signature: policy(chain, action, comment:, log:, log_prefix:, disabled:)
+
+policy :forward, :drop
+policy :input,   :drop
+policy :forward, :drop, log: true, log_prefix: "fwd-drop"   # log the default
+```
+
+- `chain` — `:input`, `:output` or `:forward`. `action` — `:accept` or `:drop`.
+- **Compiles to:** the trailing default rule of that chain on every device
+  (unless overridden per device).
+
+## device
+
+Configures one router's own firewall (Layer B). The Layer-A grants are injected
+into its forward chain automatically — they are **not** declared here.
+
+```ruby
+# Signature: device(name, host:, transport: :rest_api, **options) { ... }
+
+device "edge-1", host: "192.0.2.1", transport: :rest_api do
+  policy :input,   :drop                         # override a global default
+  policy :forward, :drop, log: true, log_prefix: "fwd-drop"
+
+  management src: "admin", service: "ssh"         # lockout protection
+
+  input   do … end                                # the box's own chains
+  output  do … end
+  forward do … end
+
+  nat do … end                                    # the box's NAT table
+end
+```
+
+- `name` — also drives the credential ENV prefix (see
+  [docs/security.md](security.md)).
+- `host` — the device address/hostname the transport connects to.
+- `transport` — `:rest_api` (default, RouterOS v7+ REST) or `:rsc` (offline
+  `.rsc` rendering). Credentials are **never** here.
+- **`**options`** — non-secret connection/behavior options, passed through to
+  the transport and Compiler:
+
+  | option            | effect                                                           |
+  | ----------------- | ---------------------------------------------------------------- |
+  | `insecure_http:`  | loud opt-in to plaintext HTTP (lab only); default port becomes 80 |
+  | `port:`           | override the REST port (default 443, or 80 with `insecure_http`)  |
+  | `verify_tls:`     | TLS cert verification (default `true`)                           |
+  | `ca_file:`        | CA bundle / pinned cert path                                    |
+  | `tls_fingerprint:`| pinned server-cert SHA-256 fingerprint                          |
+  | `fasttrack:`      | set `false` to suppress the default IPv4 forward fasttrack rule  |
+  | `revert_timeout:` | seconds the device-side auto-revert waits (default 120)          |
+
+### policy (per-device)
+
+Same verb as the global `policy`; overrides that chain's default for this box.
+
+### management
+
+Declares the management traffic the safe chain must keep open (the **input**
+chain only), so an apply can never lock the operator out.
+
+```ruby
+# Signature: management(src: nil, service: nil, port: nil)
+
+management src: "admin", service: "ssh"     # host/group + named Service
+management src: "admin", port: 8291         # host/group + raw port
+
+# REPEATABLE — each call adds another protected path; the union is emitted.
+management src: "admin", service: "ssh"     # human admins over SSH
+management src: "ci",    port: 443          # CI runner applying over REST/HTTPS
+```
+
+- `src` — a host/group name → `src-address-list`. `service` — a Service name (or
+  a built-in: `winbox` 8291, `ssh` 22, `api` 8728, `rest` 80/443). `port` — a
+  raw port when no Service is used.
+- **REPEATABLE.** Each call adds one protected path (it no longer overwrites the
+  previous one); the Compiler emits the **union** of all of them — useful when a
+  box must stay reachable for both a human admin (SSH/WinBox from the office) and
+  a CI runner (REST from another source).
+- **REQUIRED (non-empty)** whenever the device locks its input chain
+  (`policy :input, :drop`): the Compiler fails fast if NO path is declared. If
+  omitted entirely on an *unlocked* device, the Compiler infers a best-effort
+  backstop opening the full built-in mgmt set. Any explicit path disables the
+  inferred backstop.
+- **Compiles to:** `accept` rules at the front of the input chain (one per
+  declared path × service protocol).
+
+### input / output / forward — chain blocks
+
+Each opens a chain context whose verbs append rules to that chain.
+
+```ruby
+input do
+  allow_established                                  # helper
+  drop_invalid                                       # helper
+  accept protocol: :icmp
+  accept protocol: :tcp, dst_port: 22, src: "admin", comment: "ssh mgmt"
+  drop in_interface_list: "WAN", log: true, log_prefix: "wan-drop"
+end
+```
+
+**Core verbs:** `accept(**match)`, `drop(**match)`, `reject(**match)` — one rule
+each. `drop` silently discards; `reject` replies with an ICMP/TCP-reset.
+
+**Helpers** (sugar over the core verbs):
+
+| helper             | expands to                              |
+| ------------------ | --------------------------------------- |
+| `allow_established`| `accept state: %i[established related]` |
+| `drop_invalid`     | `drop state: :invalid`                  |
+
+**Match keys** (all optional; unknown keys fail fast):
+
+| key                                    | meaning / RouterOS field                          |
+| -------------------------------------- | ------------------------------------------------- |
+| `state:`                               | connection state(s): `:established`, `:related`, `:invalid`, `:new`, `:untracked` → `connection-state` |
+| `protocol:`                            | one protocol (allowlisted, see below) → `protocol`|
+| `dst_port:` / `src_port:`              | port spec (Integer/Array/Range/`"a-b"`) → `dst-port` / `src-port` |
+| `in_interface:` / `out_interface:`     | a literal interface name → `in-interface` / `out-interface` |
+| `in_interface_list:` / `out_interface_list:` | an operator-defined `/interface/list` name (mt-wall does not manage the list) → `in-interface-list` / `out-interface-list` |
+| `src:` / `dst:`                        | a Layer-A host/group name → `src-address-list` / `dst-address-list`; the reserved `"any"` matches all (omits the field, no family constraint) |
+| `family:`                              | `:ip4` or `:ip6` — pin the rule to one stack (see [family](#family--dual-stack)) |
+| `comment:`                             | an operator note, merged with the identity tag    |
+| `log:` / `log_prefix:` / `disabled:`   | rule attributes (see below)                       |
+
+- **Compiles to:** a `/ip firewall filter` and/or `/ipv6 firewall filter` rule
+  on the named chain.
+- Referencing an unknown `src:`/`dst:` name fails fast at compile time.
+
+### nat — the box's NAT table
+
+IPv4-only in v1. Opened inside a `device` block.
+
+```ruby
+nat do
+  masquerade out_interface: "ether1-wan"                       # srcnat
+  src_nat to_addresses: "203.0.113.9", out_interface: "ether1-wan"
+  dst_nat protocol: :tcp, dst_port: 443,                       # port-forward
+          in_interface: "ether1-wan",
+          to_addresses: "10.0.0.5", to_ports: 8443
+end
+```
+
+| verb         | chain    | required scope                       | translation targets               |
+| ------------ | -------- | ------------------------------------ | --------------------------------- |
+| `masquerade` | `srcnat` | `out_interface:`                     | none (implicit; must NOT be given)|
+| `dst_nat`    | `dstnat` | `in_interface:` **or** `dst:`        | `to_addresses:` (req.), `to_ports:` |
+| `src_nat`    | `srcnat` | — (but takes the same match keys)    | `to_addresses:` (req.), `to_ports:` |
+
+- **Match keys:** `protocol:`, `dst_port:`, `src_port:`, `in_interface:`,
+  `out_interface:`, `src:`, `dst:`, `comment:` (no `state:` — NAT is stateless
+  here). `src:`/`dst:` reference a Layer-A host/group.
+- **Compiles to:** `/ip firewall nat` rows on the `srcnat` / `dstnat` chain.
+- **Fail-fast:** a fully-unscoped rule raises; `dst_nat`/`src_nat` without
+  `to_addresses:` raises; `masquerade` carrying translation targets raises; an
+  IPv6 NAT target raises (IPv4-only in v1).
+
+---
+
+## Rule attributes: `log:` / `log_prefix:` / `disabled:`
+
+Valid on any core chain verb, on a `to` grant, and on a `policy`:
+
+- `log: true` — log matched packets. `log_prefix: "label"` — prefix the log
+  lines (charset-restricted: word chars, space, `. : / -`, ≤ 64 chars).
+- `disabled: true` — emit the rule but keep it inactive.
+
+These describe *how* a rule behaves, not *which* packets it matches, so they are
+**excluded from the identity tag**. Toggling `log`/`disabled` is an in-place
+`:update` — never a delete + re-create — which keeps change-management diffs
+clean.
+
+## family / dual-stack
+
+Family is inferred per address; there are no separate v4/v6 verbs. A
+host/group may hold a mix of families.
+
+- **Layer-A grants** compile to v4 rules for their v4 endpoints and v6 rules for
+  their v6 endpoints.
+- **Layer-B chain rules auto-scope:**
+  - an **unscoped** rule with **no** `src:`/`dst:` (pure protocol/interface
+    match, e.g. `accept protocol: :icmp`) emits into **both** families;
+  - an **unscoped** rule **with** `src:`/`dst:` emits only into the families its
+    references actually resolve in (their intersection) — a v4-only host does
+    not force a spurious v6 error;
+  - an **explicit** `family: :ip4 | :ip6` pins the rule to one stack and keeps a
+    strict check (a reference with no address in the pinned family fails fast).
+- The reserved **`"any"`** source/destination contributes *all* families to the
+  intersection (a no-op), so the concrete endpoint scopes the rule; `any -> any`
+  emits into both stacks.
+- **Zero-resolution fails fast** (`ConfigurationError`) for every rule kind — a
+  grant or rule that would yield no rule in any family never silently produces
+  nothing.
+- The Compiler adds an **IPv6 ICMPv6 essentials** preamble (NDP 133–136 with a
+  hop-limit guard, packet-too-big/PMTUD, drop bad src/dst, DHCPv6-client) ahead
+  of operator rules on the v6 input/forward chains.
+
+## Validation & fail-fast rules
+
+Everything is checked at the DSL/model boundary (this both catches typos early
+and neutralizes `.rsc` / JSON injection through values):
+
+- **Names** (host/group/service/interface/device) must match `\A[\w.-]+\z`.
+- **Addresses** parse via `IPAddr`, and also accept an IP **range** (`low-high`,
+  both endpoints the same family). FQDNs are not supported in v1.
+- **Ports** are `1..65535` (ranges allowed).
+- **Protocols** are checked against an allowlist: `tcp`, `udp`, `icmp`,
+  `icmpv6`, `igmp`, `gre`, `esp`, `ah`, `sctp`, `ospf`, `vrrp`, `pim`,
+  `ipsec-esp`, `ipsec-ah`, `l2tp`, `ipencap`, `ddp`, `udplite`.
+- **`log:` / `disabled:`** must be booleans; **`log_prefix:`** is
+  charset-restricted; **`family:`** must be `:ip4` / `:ip6`.
+- **Compile-time:** unknown `src:`/`dst:`/`rule`/`service`/member references,
+  group cycles, host/group name clashes, a locked input chain without
+  `management`, and zero-family resolution all raise `ConfigurationError`.
+
+### Footguns to know
+
+- `to "db", :deny` sets the **action**, not a service named `:deny` (guarded).
+- `"any"` is the reserved match-all source/destination (omits the address-list,
+  no family constraint) — not the same as the `:any` **service** slot; no
+  host/group may be named `"any"`.
+- `host "web", "10.0.0.5"` is rejected — `"10.0.0.5"` looks like an address; use
+  `address:`.
+- A device with `policy :input, :drop` **must** declare `management`.
+- `masquerade` requires `out_interface:`; `dst_nat` requires `in_interface:` or
+  `dst:`. NAT is IPv4-only.