mt-wall 0.1.0

data/lib/mt/wall/dsl/nat_builder.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for the `nat` verb inside a `device` block (Layer B — the
+      # box's own NAT table). Opened by DeviceBuilder#nat. Each verb appends a
+      # Model::NatRule. IPv4-only for v1 (see Model::NatRule).
+      #
+      #   device "edge-1", host: "10.0.0.1" do
+      #     nat do
+      #       # srcnat: hide the LAN behind the WAN address
+      #       masquerade out_interface: "ether1-wan"
+      #
+      #       # dstnat: publish an internal service (port-forward)
+      #       dst_nat protocol: :tcp, dst_port: 443,
+      #               to_addresses: "10.0.0.5", to_ports: 8443,
+      #               in_interface: "ether1-wan"
+      #     end
+      #   end
+      #
+      # CORE verbs only (v1): masquerade / dst_nat / src_nat — one rule each,
+      # taking native match keywords (protocol:, dst_port:, src_port:,
+      # in_interface:, out_interface:, src:, dst:, comment:) plus SPLIT
+      # translation targets (to_addresses:, to_ports:) where the action uses
+      # them. `src:` / `dst:` reference a Layer-A host/group by name; an unknown
+      # name is a fail-fast error at compile time. No `port_forward` helper and
+      # no combined "host:port" target string in v1 (YAGNI).
+      #
+      # VALIDATION (fail-fast):
+      #   * SCOPING IS REQUIRED — a fully-unscoped NAT rule is dangerous and
+      #     rejected: `masquerade` requires `out_interface:`; `dst_nat` requires
+      #     `in_interface:` OR `dst:`. A rule lacking its required scope raises
+      #     ConfigurationError.
+      #   * `dst_nat`/`src_nat` require `to_addresses`; `masquerade` must NOT
+      #     carry translation targets;
+      #   * ports are 1..65535; addresses parse as IPv4 via IPAddr (an IPv6
+      #     target is rejected in v1).
+      class NatBuilder
+        def initialize
+          @rules = []
+        end
+
+        # --- core verbs -----------------------------------------------------
+
+        # srcnat masquerade. Translation target is implicit (the out-interface
+        # address), so to_addresses/to_ports must be omitted. `out_interface:` is
+        # REQUIRED — an unscoped masquerade would NAT every egress path.
+        # @param out_interface [String] the egress (e.g. WAN) interface
+        # @return [void]
+        def masquerade(out_interface:, **match)
+          normalized, comment = build_match(match)
+          normalized[:out_interface] = Validators.validate_name!(out_interface, label: "out_interface")
+
+          @rules << Model::NatRule.new(chain: :srcnat, action: :masquerade,
+                                       match: normalized, comment: comment)
+        end
+
+        # dstnat (port-forward): redirect matched traffic to an internal host.
+        # REQUIRES scoping — `in_interface:` OR `dst:` must be present (else
+        # ConfigurationError) so the rule does not hijack arbitrary traffic.
+        # @param to_addresses [String, Array<String>] internal target address(es)
+        # @param to_ports     [Integer, Array, Range, nil] internal target port(s)
+        # @return [void]
+        def dst_nat(to_addresses:, to_ports: nil, **match)
+          normalized, comment = build_match(match)
+          unless normalized.key?(:in_interface) || normalized.key?(:dst)
+            raise ConfigurationError, "dst_nat requires `in_interface:` or `dst:` scoping"
+          end
+
+          addresses = validated_targets(to_addresses, to_ports, verb: "dst_nat")
+          @rules << Model::NatRule.new(chain: :dstnat, action: :dst_nat, match: normalized,
+                                       to_addresses: addresses, to_ports: to_ports, comment: comment)
+        end
+
+        # srcnat to a specific source address (static NAT / one-to-one egress).
+        # @param to_addresses [String, Array<String>]
+        # @param to_ports     [Integer, Array, Range, nil]
+        # @return [void]
+        def src_nat(to_addresses:, to_ports: nil, **match)
+          normalized, comment = build_match(match)
+          addresses = validated_targets(to_addresses, to_ports, verb: "src_nat")
+
+          @rules << Model::NatRule.new(chain: :srcnat, action: :src_nat, match: normalized,
+                                       to_addresses: addresses, to_ports: to_ports, comment: comment)
+        end
+
+        # The Model::NatRule list collected for this device.
+        # @return [Array<Model::NatRule>]
+        attr_reader :rules
+
+        private
+
+        # Split a match Hash into [normalized_match, comment]. NAT is IPv4-only
+        # and stateless, so `state:` is rejected by normalize_match.
+        def build_match(match)
+          match = match.dup
+          comment = match.delete(:comment)
+          [Validators.normalize_match(match, allow_state: false), comment]
+        end
+
+        # Validate the (required) translation targets for dst_nat / src_nat.
+        def validated_targets(to_addresses, to_ports, verb:)
+          addresses = Array(to_addresses)
+          raise ConfigurationError, "#{verb} requires `to_addresses:`" if addresses.empty?
+
+          addresses.each { |address| Validators.validate_ipv4!(address) }
+          Validators.validate_ports!(to_ports) unless to_ports.nil?
+          addresses
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/policy_scope.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # The `policy` verb: the default action for a firewall chain (its trailing
+      # rule). Shared by RootBuilder (global defaults) and DeviceBuilder
+      # (per-device overrides), so the same syntax works in both scopes.
+      #
+      #   policy :forward, :drop
+      #   policy :forward, :drop, log: true, log_prefix: "fwd-drop"
+      #
+      # `log:`/`log_prefix:` log packets hitting the chain default; `disabled:`
+      # keeps the default-policy rule in git but inactive. These are rule
+      # attributes (excluded from the identity tag).
+      #
+      # Includers MUST provide the storage hook:
+      #   #record_policy(Model::Policy)
+      module PolicyScope
+        # @param chain  [Symbol] :input, :forward or :output
+        # @param action [Symbol] :accept or :drop
+        # @return [void]
+        def policy(chain, action, comment: nil, **flags)
+          record_policy(Model::Policy.new(chain: Validators.validate_chain!(chain),
+                                          action: Validators.validate_policy_action!(action),
+                                          comment: comment, **Validators.rule_flags(**flags)))
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/root_builder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Top-level DSL context. The public methods here are the verbs users
+      # write in firewall config files / blocks. Each verb validates its
+      # arguments and records a Model::* value object on the Configuration.
+      #
+      # `rule` (Layer-A access grants) comes from RuleScope; `policy` (chain
+      # defaults) comes from PolicyScope, shared with DeviceBuilder so the same
+      # syntax sets a global default here and overrides it inside a `device`
+      # block. The `device` block itself configures Layer-B box firewall and
+      # does NOT take `rule`.
+      #
+      # Target DSL (not yet implemented):
+      #
+      #   host "web" do
+      #     address "10.0.0.5"
+      #     address "10.0.1.0/24"
+      #     member_of "web-prod", "web-wordpress"
+      #   end
+      #   host "db", address: "10.0.2.10"   # one-line shorthand
+      #   host "web", "web-prod", "web-wordpress",
+      #        address: ["10.0.0.5", "10.0.1.0/24"]                     # + groups
+      #
+      #   group "frontend" do
+      #     member "web"
+      #   end
+      #
+      #   service "mysql", protocol: :tcp, ports: [3306]
+      #
+      #   rule "frontend" do              # grants grouped by source
+      #     to "db", "mysql"              # allow (default)
+      #     to "db", "mysql", :deny
+      #   end
+      #
+      #   policy :forward, :drop          # global default
+      #
+      #   device "edge-1", host: "10.0.0.1", transport: :rest_api do
+      #     policy :input, :drop          # override for this box
+      #     input do                      # the box's own firewall
+      #       allow_established
+      #       drop_invalid
+      #       accept protocol: :tcp, dst_port: 22, src: "admin"
+      #     end
+      #   end
+      class RootBuilder
+        include RuleScope
+        include PolicyScope
+
+        def initialize(configuration)
+          @configuration = configuration
+        end
+
+        # A named address object (host). Trailing positional args after the
+        # name are group names this host joins (same as `member_of` in the
+        # block form); addresses come from the `address:` shorthand (a single
+        # string or an array, normalized via Array()) or an `address` block.
+        #
+        # AUTO-CREATE is NARROW: a group referenced HERE (host-side membership)
+        # is created on demand, because the host contributes real addresses to
+        # it. Groups referenced from `rule` / `src:` / `dst:` are NOT
+        # auto-created — an empty/undeclared group there is a fail-fast error in
+        # the Compiler.
+        #
+        # FAIL-FAST validation:
+        #   * a positional `groups` token that parses as an IP/CIDR via IPAddr
+        #     raises ConfigurationError ("looks like an address — did you mean
+        #     address:?") — guards the common `host "web", "10.0.0.5"` slip;
+        #   * a host that ends up with NO addresses raises ConfigurationError;
+        #   * `name` and every group token must match `\A[\w.-]+\z`.
+        #
+        #   host "web", "web-prod", address: "10.0.0.5"
+        #   host "web", "web-prod", address: ["10.0.0.5", "10.0.1.0/24"]
+        #
+        # @param groups [Array<String>] group names to fold this host into
+        # @yield a HostBuilder context
+        # @return [void]
+        def host(name, *groups, address: nil, comment: nil, &block)
+          memberships = groups.map { |token| Validators.validate_group_token!(token) }
+
+          builder = HostBuilder.new(name, comment: comment)
+          builder.instance_eval(&block) if block
+          Array(address).each { |entry| builder.address(entry) }
+
+          object = builder.to_object
+          @configuration.add_object(object)
+
+          (memberships + builder.memberships).uniq.each do |group_name|
+            @configuration.add_membership(object.name, group_name)
+          end
+        end
+
+        # @yield a GroupBuilder context (declares members)
+        # @return [void]
+        def group(name, comment: nil, &block)
+          builder = GroupBuilder.new(name, comment: comment)
+          builder.instance_eval(&block) if block
+          group = builder.to_group
+          @configuration.declare_group(group.name, group.members, group.comment)
+        end
+
+        # A named protocol/port definition. Accepts a single `protocol:` (legacy)
+        # OR multiple `protocols:` (e.g. DNS = tcp+udp). Ports keep their spec
+        # form (Integer/Array/Range/"a-b"), so a range round-trips as a range.
+        # @return [void]
+        def service(name, protocol: nil, protocols: nil, ports: [])
+          list = protocols || protocol
+          raise ConfigurationError, "service #{name.inspect} needs protocol: or protocols:" if list.nil?
+
+          validated = Array(list).map { |proto| Validators.validate_protocol!(proto) }
+          @configuration.add_service(
+            Model::Service.new(name: Validators.validate_name!(name, label: "service"),
+                               protocols: validated,
+                               ports: Validators.validate_ports!(ports))
+          )
+        end
+
+        # @yield a DeviceBuilder context (per-device policies and rules)
+        # @return [void]
+        def device(name, host:, transport: :rest_api, **options, &block)
+          builder = DeviceBuilder.new(name, host: host, transport: transport, **options)
+          builder.instance_eval(&block) if block
+          @configuration.add_device(builder.to_device)
+        end
+
+        # RuleScope storage hooks (record onto the Configuration).
+        # @return [void]
+        def record_rule(rule)
+          @configuration.add_rule(rule)
+        end
+
+        # @return [void]
+        def record_policy(policy)
+          @configuration.add_global_policy(policy)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/rule_builder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for the `rule` verb. The source is fixed for the whole
+      # block (passed in); each `to` call adds one grant from that source to a
+      # destination, producing a Model::Rule.
+      #
+      #   rule "admin" do
+      #     to "edge-1-mgmt", "ssh"          # allow (default action)
+      #     to "edge-2-mgmt", "ssh", :deny   # explicit action
+      #   end
+      #
+      # `to` takes a destination host/group, an optional service name (omitted
+      # = :any), and an optional action (:allow / :deny, default :allow). Action
+      # is positional and last, so to set it you must give a service (or :any):
+      # `to "x", :any, :deny`. The DSL action maps to RouterOS accept/drop in
+      # the resulting Model::Rule.
+      class RuleBuilder
+        # DSL actions, and the tokens that trigger the service-slot footgun.
+        ACTIONS = %i[allow deny].freeze
+        ACTION_TOKENS = [:allow, :deny, "allow", "deny"].freeze
+        # DSL action -> RouterOS / Model::Rule action.
+        ACTION_MAP = { allow: :accept, deny: :drop }.freeze
+
+        def initialize(source)
+          @source = source
+          @rules = []
+        end
+
+        # One grant: @source -> destination, optional service, optional action.
+        #
+        # FAIL-FAST on the positional footgun: `action` MUST be one of
+        # {:allow, :deny}. If the SERVICE slot (arg 2) is given as `:allow` or
+        # `:deny`, that is treated as the ACTION (service defaults to :any) so
+        # `to "x", :deny` cannot silently degrade into "service named :deny".
+        # Any other non-{:allow,:deny} symbol/string in the action slot raises
+        # ConfigurationError with a clear message.
+        #
+        # `log:`/`log_prefix:` enable RouterOS logging on the emitted rule(s);
+        # `disabled:` keeps the grant in git but inactive. Both are rule
+        # attributes (excluded from the identity tag, so a toggle is an :update).
+        #
+        # @param destination [String]      name of the destination host/group
+        # @param service     [String, Symbol] service name, or :any
+        # @param action      [Symbol]      :allow or :deny
+        # @param log         [Boolean]     log matched packets (log=yes)
+        # @param log_prefix  [String, nil] optional log-prefix label
+        # @param disabled    [Boolean]     emit the rule(s) disabled
+        # @return [void]
+        def to(destination, service = :any, action = :allow, comment: nil, **flags)
+          Validators.validate_name!(destination, label: "destination")
+          service, action = resolve_service_and_action(service, action)
+          service_name = service == :any ? nil : Validators.validate_name!(service, label: "service")
+
+          @rules << Model::Rule.new(source: @source, destination: destination.to_s,
+                                    service: service_name, action: ACTION_MAP.fetch(action),
+                                    comment: comment, **Validators.rule_flags(**flags))
+        end
+
+        # The Model::Rule list collected from this block.
+        # @return [Array<Model::Rule>]
+        attr_reader :rules
+
+        private
+
+        # Resolve the service-slot footgun (`to "x", :deny`) and validate the
+        # action. @return [[service, Symbol]] the (service, action) pair.
+        def resolve_service_and_action(service, action)
+          if ACTION_TOKENS.include?(service)
+            action = service
+            service = :any
+          end
+
+          action = action.to_sym
+          unless ACTIONS.include?(action)
+            raise ConfigurationError, "rule action must be :allow or :deny, got #{action.inspect}"
+          end
+
+          [service, action]
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/rule_scope.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # The `rule` verb: abstract, device-agnostic access grants (Layer A).
+      # Only the global (root) scope declares these — they compile to the
+      # forward chain of every managed device. Device-local box firewall config
+      # is a different concern (see DeviceBuilder / ChainBuilder).
+      #
+      # Includers MUST provide the storage hook:
+      #   #record_rule(Model::Rule)
+      #
+      # `rule` groups access grants by source: the source (a host or group) is
+      # the block header, and each `to` line inside is one grant from that
+      # source. The action defaults to :allow and may be omitted.
+      #
+      #   rule "admin" do
+      #     to "edge-1-mgmt", "ssh"          # allow (default action)
+      #     to "edge-2-mgmt", "ssh", :deny   # explicit action
+      #     to "edge-3-mgmt"                 # no service = any
+      #   end
+      module RuleScope
+        # @param source [String] name of the source host/group
+        # @yield a RuleBuilder context (one `to` per grant)
+        # @return [void]
+        def rule(source, &block)
+          builder = RuleBuilder.new(Validators.validate_name!(source, label: "source"))
+          builder.instance_eval(&block) if block
+          builder.rules.each { |grant| record_rule(grant) }
+        end
+      end
+    end
+  end
+end