mt-wall 0.1.0

data/lib/mt/wall/transport/rest_api.rb

@@ -0,0 +1,464 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "openssl"
+
+module Mt
+  module Wall
+    module Transport
+      # RouterOS v7+ REST API adapter -- the primary transport.
+      #
+      # Talks to https://<host>/rest/<path> over HTTP Basic auth. Verified
+      # RouterOS v7 REST mapping (Plan::Operation -> REST verb):
+      #   * fetch        GET    /rest/<path>            (list rows)
+      #   * :create      PUT    /rest/<path>            (place-before in body)
+      #   * :update      PATCH  /rest/<path>/<.id>
+      #   * :delete      DELETE /rest/<path>/<.id>
+      #   * :move        POST   /rest/<path>/move       (reorder by .id)
+      # `<path>` is the DesiredState key with the leading slash, e.g.
+      # `/ip/firewall/filter` -> `/rest/ip/firewall/filter`; IPv6 maps to
+      # `/rest/ipv6/firewall/...`. Requires RouterOS v7+ with the REST service
+      # enabled.
+      #
+      # NORMALIZATION: RouterOS returns booleans/numbers as STRINGS
+      # ("true"/"yes"/"443"); fetch normalizes them so Plan.diff compares like
+      # for like, and rows flagged `dynamic` are excluded from the fetched
+      # state (never diffed or deleted).
+      #
+      # ── SECURITY DEFAULTS ──────────────────────────────────────────────────
+      # * Credentials are read from ENV, never from the DSL. Canonical, collision
+      #   -checked derivation: a device named "edge-1" uses MT_WALL_EDGE_1_USER /
+      #   MT_WALL_EDGE_1_PASSWORD (see {.credentials_for}); a missing expected
+      #   var is a fail-fast TransportError.
+      # * PLAINTEXT HTTP IS REFUSED by default. Talking to a device requires
+      #   TLS; downgrading needs a loud, explicit opt-in (`insecure_http: true`
+      #   option or MT_WALL_INSECURE_HTTP env) — absent that, http raises
+      #   TransportError.
+      # * TLS verification is ON. Prefer pinning via `ca_file:` / `tls_fingerprint:`
+      #   over a blanket `verify_tls: false`; disabling verification requires an
+      #   explicit opt-out and is discouraged.
+      # * CREDENTIAL REDACTION is centralized: the password MUST NOT appear in
+      #   any URL, log, exception message, or rendered .rsc. (A test asserts the
+      #   password never surfaces in plan/error/.rsc output.)
+      class RestApi < Base # rubocop:disable Metrics/ClassLength
+        # The standard cleartext HTTP port; targeting it requires an explicit
+        # plaintext opt-in (Basic-auth creds would otherwise travel in clear).
+        PLAINTEXT_PORT = 80
+
+        # Connection timeouts (seconds).
+        OPEN_TIMEOUT = 10
+        READ_TIMEOUT = 30
+
+        # Net::HTTP request classes per logical verb.
+        REQUEST_CLASSES = {
+          get: Net::HTTP::Get, put: Net::HTTP::Put, patch: Net::HTTP::Patch,
+          delete: Net::HTTP::Delete, post: Net::HTTP::Post
+        }.freeze
+
+        # Network-layer failures we translate into a (redacted) TransportError.
+        NETWORK_ERRORS = [
+          SocketError, IOError, SystemCallError, Timeout::Error,
+          OpenSSL::SSL::SSLError, Net::OpenTimeout, Net::ReadTimeout,
+          Net::ProtocolError
+        ].freeze
+
+        ID_KEY = Plan::ID_KEY
+
+        # @param host             [String]
+        # @param user             [String, nil] omitted -> derived from ENV
+        # @param password         [String, nil] omitted -> derived from ENV
+        # @param port             [Integer]
+        # @param verify_tls       [Boolean]     TLS cert verification (default on)
+        # @param ca_file          [String, nil] CA bundle / pinned cert path
+        # @param tls_fingerprint  [String, nil] pinned server cert fingerprint
+        # @param insecure_http    [Boolean]     loud opt-in to plaintext HTTP
+        # @param http_client      [#request, nil] injected connection (test seam)
+        def initialize(host:, user: nil, password: nil, port: 443, verify_tls: true, # rubocop:disable Metrics/ParameterLists
+                       ca_file: nil, tls_fingerprint: nil, insecure_http: false,
+                       http_client: nil)
+          super()
+          @host = host
+          @user = user
+          @password = password
+          @port = port
+          @verify_tls = verify_tls
+          @ca_file = ca_file
+          @tls_fingerprint = tls_fingerprint
+          @insecure_http = insecure_http
+          @http_client = http_client
+        end
+
+        # Build a RestApi for a Model::Device, reading credentials from ENV and
+        # non-secret connection options from `device.options`.
+        # @param device [Model::Device]
+        # @param http_client [#request, nil]
+        # @return [RestApi]
+        def self.for_device(device, http_client: nil)
+          creds = credentials_for(device.name)
+          opts = device.options
+          insecure = opts.fetch(:insecure_http, false)
+          new(host: device.host, user: creds[:user], password: creds[:password],
+              port: opts.fetch(:port) { insecure ? PLAINTEXT_PORT : 443 },
+              verify_tls: opts.fetch(:verify_tls, true),
+              ca_file: opts[:ca_file], tls_fingerprint: opts[:tls_fingerprint],
+              insecure_http: insecure, http_client: http_client)
+        end
+
+        # Canonical ENV var prefix for a device name: upcased, every run of
+        # non-[A-Z0-9] collapsed to a single "_". "edge-1" -> "MT_WALL_EDGE_1".
+        # @param device_name [String]
+        # @return [String]
+        def self.env_prefix(device_name)
+          slug = device_name.to_s.upcase.gsub(/[^A-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "")
+          "MT_WALL_#{slug}"
+        end
+
+        # Derive the canonical ENV var names and read credentials for a device.
+        # "edge-1" -> MT_WALL_EDGE_1_USER / MT_WALL_EDGE_1_PASSWORD. A missing or
+        # empty expected var fails fast with TransportError.
+        #
+        # @param device_name [String]
+        # @return [Hash{Symbol=>String}] { user:, password: }
+        def self.credentials_for(device_name)
+          prefix = env_prefix(device_name)
+          user = ENV.fetch("#{prefix}_USER", nil)
+          password = ENV.fetch("#{prefix}_PASSWORD", nil)
+          missing = []
+          missing << "#{prefix}_USER" if user.nil? || user.empty?
+          missing << "#{prefix}_PASSWORD" if password.nil? || password.empty?
+          unless missing.empty?
+            raise TransportError, "missing credentials for device #{device_name.inspect}: set #{missing.join(' and ')}"
+          end
+
+          { user: user, password: password }
+        end
+
+        # Guard: distinct device names must not collapse to the same ENV prefix,
+        # which would silently share one set of credentials. Fails fast.
+        # @param device_names [Array<String>]
+        # @return [void]
+        def self.assert_unique_env_prefixes!(device_names)
+          by_prefix = device_names.group_by { |name| env_prefix(name) }
+          collisions = by_prefix.select { |_prefix, names| names.uniq.size > 1 }
+          return if collisions.empty?
+
+          detail = collisions.map { |prefix, names| "#{names.uniq.inspect} -> #{prefix}" }.join("; ")
+          raise TransportError, "device names collide on credential ENV prefix: #{detail}"
+        end
+
+        # ── REST key mapping (the one place underscore<->hyphen is resolved) ──
+
+        # Ruby underscore symbol -> RouterOS hyphenated REST key.
+        # @return [String]
+        def self.rest_key(symbol)
+          symbol.to_s.tr("_", "-")
+        end
+
+        # RouterOS hyphenated REST key -> Ruby underscore symbol.
+        # @return [Symbol]
+        def self.ruby_key(string)
+          string.to_s.tr("-", "_").to_sym
+        end
+
+        # @param paths [Array<String>]
+        # @param managed_list_names [Array<String>]
+        # @return [DesiredState]
+        def fetch(paths, managed_list_names: [])
+          raw = paths.to_h { |path| [path, get_rows(path)] }
+          DesiredState.from_current(raw, managed_list_names: managed_list_names)
+        end
+
+        # @param operations [Array<Plan::Operation>]
+        # @return [void]
+        def apply(operations)
+          @id_index = build_id_index(operations)
+          operations.each { |operation| dispatch(operation) }
+          nil
+        ensure
+          @id_index = nil
+        end
+
+        # Back up the box and arm a device-side scheduler that restores the
+        # backup after `timeout`. The backup is taken BEFORE the scheduler/script
+        # are created, so a fired revert (which reboots into the backup) also
+        # discards the revert machinery itself. Returns the scheduler name.
+        # @param snapshot [Object] managed paths (informational; full backup used)
+        # @param timeout  [Integer] seconds
+        # @return [String] handle (scheduler name)
+        def arm_auto_revert(_snapshot, timeout:)
+          name = revert_name
+          request(:post, rest_path("/system/backup/save"), { name: name })
+          request(:put, rest_path("/system/script"),
+                  { name: name, "dont-require-permissions": "yes", source: revert_source(name) })
+          request(:put, rest_path("/system/scheduler"),
+                  { name: name, interval: "#{timeout}s", "start-time": "startup", "on-event": name })
+          name
+        end
+
+        # Cancel an armed revert: delete the scheduler and its restore script.
+        # Idempotent — missing rows are ignored.
+        # @param handle [String]
+        # @return [void]
+        def confirm(handle)
+          delete_named("/system/scheduler", handle)
+          delete_named("/system/script", handle)
+          nil
+        end
+
+        # Redacted representation — the password is NEVER rendered.
+        # @return [String]
+        def inspect
+          "#<#{self.class.name} host=#{@host.inspect} port=#{@port} " \
+            "user=#{@user.inspect} secure=#{secure?}>"
+        end
+        alias to_s inspect
+
+        private
+
+        # ── fetch helpers ────────────────────────────────────────────────────
+
+        def get_rows(path)
+          response = request(:get, rest_path(path))
+          return [] if response.code.to_i == 404
+
+          body = response.body.to_s
+          return [] if body.empty?
+
+          Array(JSON.parse(body)).map { |row| symbolize(row) }
+        rescue JSON::ParserError
+          raise TransportError, "invalid JSON in REST response for #{path}"
+        end
+
+        def symbolize(row)
+          row.each_with_object({}) { |(key, value), out| out[self.class.ruby_key(key)] = value }
+        end
+
+        # ── apply helpers ────────────────────────────────────────────────────
+
+        def dispatch(operation)
+          case operation.action
+          when :create then create_row(operation)
+          when :update then update_row(operation)
+          when :delete then delete_row(operation)
+          when :move   then move_row(operation)
+          else raise TransportError, "unsupported operation #{operation.action.inspect}"
+          end
+        end
+
+        def create_row(operation)
+          request(:put, rest_path(operation.path), create_body(operation))
+        end
+
+        def update_row(operation)
+          request(:patch, id_path(operation), update_body(operation))
+        end
+
+        def delete_row(operation)
+          request(:delete, id_path(operation))
+        end
+
+        def move_row(operation)
+          request(:post, "#{rest_path(operation.path)}/move", move_body(operation))
+        end
+
+        def create_body(operation)
+          body = hyphenate(without_internal(operation.payload))
+          anchor = resolve_position(operation)
+          body["place-before"] = anchor if anchor
+          body
+        end
+
+        def update_body(operation)
+          hyphenate(without_internal(operation.payload))
+        end
+
+        def move_body(operation)
+          body = { "numbers" => row_id(operation) }
+          destination = resolve_position(operation)
+          body["destination"] = destination if destination
+          body
+        end
+
+        # Resolve a place-before/move anchor to a device .id. The anchor is the
+        # successor row's `(tag, ordinal)` key (or already a literal `.id`),
+        # looked up from a fresh fetch of the current ids. nil => append at tail.
+        def resolve_position(operation)
+          position = operation.position
+          return nil if position.nil?
+          return position if position.is_a?(String)
+
+          tag, ordinal = position
+          @id_index[[operation.path, tag, ordinal]]
+        end
+
+        # Index current device rows of every full table touched by `operations`
+        # by `[path, tag, ordinal]` (the same identity key Plan matches on) so a
+        # `(tag, ordinal)` anchor resolves to the row's device `.id`.
+        def build_id_index(operations)
+          paths = operations.map(&:path).uniq.select { |path| DesiredState::FULL_TABLE_PATHS.include?(path) }
+          paths.each_with_object({}) { |path, index| index_rows(path, index) }
+        end
+
+        def index_rows(path, index)
+          counts = Hash.new(0)
+          get_rows(path).each do |row|
+            tag = Compiler.tag_in_comment(row[:comment])
+            index[[path, tag, counts[tag]]] = row[ID_KEY]
+            counts[tag] += 1
+          end
+        end
+
+        def row_id(operation)
+          id = operation.payload[ID_KEY]
+          raise TransportError, "operation #{operation.action} on #{operation.path} is missing #{ID_KEY}" if id.nil?
+
+          id
+        end
+
+        def without_internal(payload)
+          payload.reject { |key, _| key == ID_KEY }
+        end
+
+        def hyphenate(payload)
+          payload.to_h { |key, value| [self.class.rest_key(key), value] }
+        end
+
+        def id_path(operation)
+          "#{rest_path(operation.path)}/#{row_id(operation)}"
+        end
+
+        # ── auto-revert helpers ──────────────────────────────────────────────
+
+        def revert_name
+          "mt-wall-revert-#{Time.now.to_i}"
+        end
+
+        def revert_source(name)
+          %(/system backup load name="#{name}" password="")
+        end
+
+        def delete_named(path, name)
+          row = get_rows(path).find { |entry| entry[:name] == name }
+          return if row.nil?
+
+          request(:delete, "#{rest_path(path)}/#{row[ID_KEY]}")
+        end
+
+        # ── HTTP plumbing ────────────────────────────────────────────────────
+
+        def request(method, request_path, body = nil)
+          assert_transport_allowed!
+          assert_credentials!
+          response = connection.request(build_request(method, request_path, body))
+          ensure_success!(response, method, request_path)
+          response
+        rescue TransportError
+          raise
+        rescue *NETWORK_ERRORS => e
+          raise TransportError, "REST #{method.to_s.upcase} #{request_path} failed (#{e.class})"
+        end
+
+        def build_request(method, request_path, body)
+          request = REQUEST_CLASSES.fetch(method).new(request_path)
+          request.basic_auth(@user, @password)
+          if body
+            request["Content-Type"] = "application/json"
+            request.body = JSON.generate(body)
+          end
+          request
+        end
+
+        def ensure_success!(response, method, request_path)
+          code = response.code.to_i
+          return if code.between?(200, 299)
+          return if code == 404 && method == :get
+
+          raise TransportError, "REST #{method.to_s.upcase} #{request_path} returned HTTP #{response.code}"
+        end
+
+        def connection
+          @connection ||= start_connection
+        end
+
+        def start_connection
+          return @http_client if @http_client
+
+          conn = Net::HTTP.new(@host, @port)
+          configure_tls(conn) if secure?
+          conn.open_timeout = OPEN_TIMEOUT
+          conn.read_timeout = READ_TIMEOUT
+          conn.start
+          conn
+        end
+
+        def configure_tls(conn)
+          conn.use_ssl = true
+          if @tls_fingerprint
+            configure_pinning(conn)
+          elsif @ca_file
+            conn.ca_file = @ca_file
+            conn.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          else
+            conn.verify_mode = @verify_tls ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+          end
+        end
+
+        def configure_pinning(conn)
+          expected = normalize_fingerprint(@tls_fingerprint)
+          conn.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          conn.verify_callback = proc { |_preverify_ok, store_ctx| pinned?(store_ctx, expected) }
+        end
+
+        # Accept the chain iff the leaf certificate's SHA-256 fingerprint matches
+        # the pin; intermediates are deferred (return true) so the leaf decides.
+        def pinned?(store_ctx, expected)
+          return true unless store_ctx.error_depth.zero?
+
+          cert = store_ctx.current_cert
+          !cert.nil? && OpenSSL::Digest::SHA256.hexdigest(cert.to_der).casecmp?(expected)
+        end
+
+        def normalize_fingerprint(fingerprint)
+          fingerprint.to_s.delete(": \t\n").downcase
+        end
+
+        def assert_transport_allowed!
+          return if insecure_http?
+          return unless @port == PLAINTEXT_PORT
+
+          raise TransportError,
+                "refusing plaintext HTTP for #{@host}:#{@port} (credentials would travel in clear text); " \
+                "pass insecure_http: true or set MT_WALL_INSECURE_HTTP to override"
+        end
+
+        def assert_credentials!
+          return unless blank?(@user) || blank?(@password)
+
+          raise TransportError,
+                "no credentials configured for #{@host}; build via RestApi.for_device or pass user:/password:"
+        end
+
+        def blank?(value)
+          value.nil? || value.empty?
+        end
+
+        def secure?
+          !insecure_http?
+        end
+
+        def insecure_http?
+          @insecure_http || truthy_env?("MT_WALL_INSECURE_HTTP")
+        end
+
+        def truthy_env?(name)
+          %w[1 true yes].include?(ENV.fetch(name, "").strip.downcase)
+        end
+
+        def rest_path(path)
+          "/rest#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/transport/rsc.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Transport
+      # Offline transport: renders a Plan into a RouterOS script (.rsc)
+      # instead of touching a live device. Useful for GitOps review (the
+      # rendered script is a diffable artifact) and for environments where
+      # deployment is a separate, manually approved step.
+      #
+      # Because there is no device to read from, #fetch returns an empty
+      # current state, so a Plan against this transport is always a full
+      # render of the desired configuration. The commit-confirm hooks
+      # (arm/confirm) are no-ops: there is no live link to protect, and a nil
+      # handle signals the Reconciler to skip the health-check/confirm cycle.
+      class Rsc < Base
+        # Keys that are internal to the diff machinery and must never be
+        # rendered as RouterOS command arguments.
+        INTERNAL_KEYS = [Plan::ID_KEY].freeze
+
+        # Boolean DIFF values are carried as the REST-style strings "true"/"false"
+        # (so desired matches the device readback). RouterOS SCRIPT syntax,
+        # however, uses the yes/no idiom — so this is the one place we translate
+        # back when WRITING a .rsc command. Applied only to exact whole-value
+        # matches (e.g. `disabled=true` -> `disabled=yes`); non-boolean values are
+        # untouched.
+        ROS_BOOLEAN = { "true" => "yes", "false" => "no" }.freeze
+
+        def initialize(io: $stdout)
+          super()
+          @io = io
+        end
+
+        # No live device: current state is empty.
+        # @return [DesiredState]
+        def fetch(_paths, managed_list_names: [])
+          DesiredState.new
+        end
+
+        # Writes the operations as RouterOS CLI commands to @io. The Plan is
+        # already sorted per the apply-order invariants, so the rendered script
+        # is safe to run top-to-bottom.
+        # @param operations [Array<Plan::Operation>]
+        # @return [void]
+        def apply(operations)
+          @io.puts("# Generated by mt-wall — RouterOS script (.rsc)")
+          operations.each { |operation| @io.puts(render(operation)) }
+          nil
+        end
+
+        # Offline render has no device to protect: no auto-revert is armed.
+        # A nil handle tells the Reconciler to skip health-check/confirm.
+        # @return [nil]
+        def arm_auto_revert(_snapshot, timeout:)
+          nil
+        end
+
+        # No-op: nothing was armed.
+        # @return [void]
+        def confirm(_handle); end
+
+        private
+
+        def render(operation)
+          case operation.action
+          when :create then "#{operation.path} add #{render_fields(operation.payload)}"
+          when :update then "#{operation.path} set #{find_clause(operation)} #{render_fields(operation.payload)}"
+          when :delete then "#{operation.path} remove #{find_clause(operation)}"
+          when :move   then "#{operation.path} move #{find_clause(operation)}"
+          else "# unsupported operation: #{operation.action}"
+          end
+        end
+
+        def find_clause(operation)
+          id = operation.payload[Plan::ID_KEY]
+          id ? %([find where .id="#{id}"]) : "[find]"
+        end
+
+        def render_fields(payload)
+          payload.except(*INTERNAL_KEYS)
+                 .map { |key, value| "#{RestApi.rest_key(key)}=#{quote(rsc_value(value))}" }
+                 .join(" ")
+        end
+
+        # Map a REST-style boolean string ("true"/"false") to the RouterOS script
+        # idiom ("yes"/"no"); pass any other value through unchanged.
+        def rsc_value(value)
+          ROS_BOOLEAN.fetch(value.to_s, value)
+        end
+
+        # Quote values that contain whitespace or RouterOS-significant characters.
+        def quote(value)
+          string = value.to_s
+          string.match?(/[\s"=;]/) ? %("#{string.gsub('"', '\\"')}") : string
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    VERSION = "0.1.0"
+  end
+end

data/lib/mt/wall.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "wall/version"
+require_relative "wall/errors"
+
+require_relative "wall/model/address_object"
+require_relative "wall/model/group"
+require_relative "wall/model/service"
+require_relative "wall/model/rule"
+require_relative "wall/model/filter_rule"
+require_relative "wall/model/nat_rule"
+require_relative "wall/model/policy"
+require_relative "wall/model/device"
+
+require_relative "wall/configuration"
+require_relative "wall/dsl"
+require_relative "wall/dsl/validators"
+require_relative "wall/dsl/rule_scope"
+require_relative "wall/dsl/policy_scope"
+require_relative "wall/dsl/rule_builder"
+require_relative "wall/dsl/host_builder"
+require_relative "wall/dsl/group_builder"
+require_relative "wall/dsl/chain_builder"
+require_relative "wall/dsl/nat_builder"
+require_relative "wall/dsl/device_builder"
+require_relative "wall/dsl/root_builder"
+
+require_relative "wall/desired_state"
+require_relative "wall/compiler"
+require_relative "wall/plan"
+
+require_relative "wall/transport/base"
+require_relative "wall/transport/rest_api"
+require_relative "wall/transport/rsc"
+
+require_relative "wall/reconciler"
+require_relative "wall/cli"
+
+module Mt
+  # Top-level namespace and public entry points for the mt-wall gem.
+  module Wall
+    module_function
+
+    # Build a Configuration from a DSL block.
+    # @return [Configuration]
+    def define(&block)
+      DSL.build(&block)
+    end
+
+    # Load a Configuration from one or more DSL files (a GitOps repo).
+    # @return [Configuration]
+    def load(*paths)
+      DSL.load(*paths)
+    end
+  end
+end