parry 0.1.0 → 0.2.0

data/config/routes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Parry::Engine.routes.draw do
+  resources :rules, except: [:show] do
+    collection do
+      get :export
+      get :import
+      post :import, action: :perform_import, as: :perform_import
+    end
+  end
+
+  resources :blocked_hosts, only: [:index] do
+    collection do
+      post :unblock
+    end
+  end
+
+  root to: "rules#index"
+end

data/lib/parry/blocked_host.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Parry
+  class BlockedHost
+    attr_reader :ip, :hits, :rule, :match_type, :path, :first_seen, :last_seen
+
+    def self.from_hash(ip, hash)
+      return nil if hash.nil? || hash.empty?
+
+      new(
+        ip: ip,
+        hits: hash["hits"].to_i,
+        rule: hash["rule"],
+        match_type: hash["match_type"],
+        path: hash["path"],
+        first_seen: hash["first_seen"],
+        last_seen: hash["last_seen"]
+      )
+    end
+
+    def initialize(ip:, hits: 0, rule: nil, match_type: nil, path: nil, first_seen: nil, last_seen: nil)
+      @ip = ip
+      @hits = hits.to_i
+      @rule = rule
+      @match_type = match_type
+      @path = path
+      @first_seen = to_time(first_seen)
+      @last_seen = to_time(last_seen)
+    end
+
+    def throttled?
+      match_type.to_s == "throttle"
+    end
+
+    def blocklisted?
+      match_type.to_s == "blocklist"
+    end
+
+    def caught?
+      match_type.to_s == "honeypot"
+    end
+
+    def to_param
+      ip
+    end
+
+    private
+
+    def to_time(value)
+      Time.at(value.to_i) if value
+    end
+  end
+end

data/lib/parry/caught_host.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Parry
+  class CaughtHost
+    attr_reader :ip, :rule_id, :rule, :path, :caught_at
+
+    def self.from_json(ip, json)
+      data = JSON.parse(json)
+      new(ip: ip, rule_id: data["rule_id"], rule: data["rule"], path: data["path"],
+        caught_at: data["caught_at"])
+    rescue JSON::ParserError
+      nil
+    end
+
+    def initialize(ip:, rule_id: nil, rule: nil, path: nil, caught_at: nil)
+      @ip = ip.to_s
+      @rule_id = rule_id
+      @rule = rule
+      @path = path
+      @caught_at = caught_at.nil? ? nil : Time.at(caught_at.to_i)
+    end
+
+    def to_h
+      {rule_id: rule_id, rule: rule, path: path, caught_at: caught_at&.to_i}
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/parry/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "redis"
+
+module Parry
+  # Runtime configuration for the engine.
+  #
+  #   Parry.configure do |config|
+  #     config.redis = Redis.new(url: ENV["PARRY_REDIS_URL"])
+  #     config.max_tracked_hosts = 5_000
+  #   end
+  class Configuration
+    attr_writer :redis
+
+    # URL used to build the default Redis client. Ignored when +redis+ is set.
+    attr_accessor :redis_url
+
+    # Prefix for every Redis key Parry writes.
+    attr_accessor :key_prefix
+
+    # Register the Rack::Attack hooks automatically when the engine boots.
+    attr_accessor :auto_install
+
+    # Record blocked/throttled requests so they show up under "Blocked hosts".
+    attr_accessor :track_events
+
+    # Maximum number of hosts kept in the blocked hosts list.
+    attr_accessor :max_tracked_hosts
+
+    # How long a honeypot regex may spend on one path before it is abandoned.
+    # Guards against a pattern that backtracks catastrophically.
+    attr_accessor :regex_timeout
+
+    def initialize
+      @redis_url = ENV["PARRY_REDIS_URL"] || ENV["REDIS_URL"]
+      @key_prefix = "parry"
+      @auto_install = true
+      @track_events = true
+      @max_tracked_hosts = 1000
+      @regex_timeout = 0.05
+    end
+
+    # A Redis client, or anything responding to +with+ (such as a
+    # ConnectionPool) that yields one.
+    def redis
+      @redis ||= redis_url ? Redis.new(url: redis_url) : Redis.new
+    end
+  end
+end

data/lib/parry/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Parry
+  class Engine < ::Rails::Engine
+    isolate_namespace Parry
+
+    config.parry = Parry.config
+
+    # Runs after the host application's initializers so a Rack::Attack cache
+    # store configured there is already in place.
+    initializer "parry.install", after: :load_config_initializers do
+      Parry.install! if Parry.config.auto_install
+    end
+  end
+end

data/lib/parry/honeypot_store.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Parry
+  class HoneypotStore
+    def all
+      raw = Parry.with_redis { |redis| redis.hgetall(caught_key) }
+      raw.filter_map { |ip, json| CaughtHost.from_json(ip, json) }
+    end
+
+    def to_h
+      all.each_with_object({}) { |host, index| index[host.ip] = host }
+    end
+
+    def find(ip)
+      json = Parry.with_redis { |redis| redis.hget(caught_key, ip.to_s) }
+      json && CaughtHost.from_json(ip.to_s, json)
+    end
+
+    def record(ip, rule: nil, path: nil, at: Time.now)
+      return false if ip.nil? || ip.to_s.empty?
+
+      host = CaughtHost.new(
+        ip: ip,
+        rule_id: rule&.id,
+        rule: rule&.label,
+        path: path,
+        caught_at: at.to_i
+      )
+
+      added = Parry.with_redis do |redis|
+        stored = redis.hsetnx(caught_key, host.ip, host.to_json)
+        redis.incr(version_key) if stored
+        stored
+      end
+      !!added
+    end
+
+    def release(ip)
+      removed = Parry.with_redis do |redis|
+        count = redis.hdel(caught_key, ip.to_s)
+        redis.incr(version_key) if count > 0
+        count
+      end
+      removed > 0
+    end
+
+    def caught?(ip)
+      Parry.with_redis { |redis| redis.hexists(caught_key, ip.to_s) }
+    end
+
+    def count
+      Parry.with_redis { |redis| redis.hlen(caught_key) }
+    end
+
+    def clear
+      Parry.with_redis do |redis|
+        redis.del(caught_key)
+        redis.incr(version_key)
+      end
+    end
+
+    def caught_key
+      "#{Parry.config.key_prefix}:caught"
+    end
+
+    private
+
+    def version_key
+      Parry.store.version_key
+    end
+  end
+end

data/lib/parry/rack_attack_adapter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "rack/attack"
+
+module Parry
+  # Bridges the rules stored in Redis into Rack::Attack.
+  #
+  # A safelist and a blocklist check are registered once; both consult the
+  # current snapshot of the rules. Throttles have to be registered as real
+  # Rack::Attack throttles, so the snapshot is refreshed whenever the version
+  # counter in Redis changes - that is what makes GUI edits visible to every
+  # process without a redeploy.
+  class RackAttackAdapter
+    SAFELIST_NAME = "parry/safelist"
+    BLOCKLIST_NAME = "parry/blocklist"
+    THROTTLE_PREFIX = "parry/throttle/"
+    THROTTLE_NAME_PATTERN = /\A#{Regexp.escape(THROTTLE_PREFIX)}(?<id>.+)\z/
+    # Set while a request is being checked, so the tracker can report which rule
+    # matched without looking it up again.
+    MATCHED_RULE_KEY = "parry.matched_rule"
+
+    def initialize
+      @mutex = Mutex.new
+      @rule_set = RuleSet.empty
+      @version = nil
+      @installed = false
+      @subscribed = false
+    end
+
+    def installed?
+      @installed
+    end
+
+    # The snapshot every request is checked against.
+    attr_reader :rule_set
+
+    # Registers the Rack::Attack hooks. Safe to call more than once.
+    def install!
+      return false if @installed
+
+      adapter = self
+
+      Rack::Attack.safelist(SAFELIST_NAME) do |request|
+        # Runs on every request, before any blocklist or throttle, which makes
+        # it the natural place to pick up rule changes.
+        adapter.sync!
+        adapter.rule_set.safelisted?(request.ip)
+      end
+
+      Rack::Attack.blocklist(BLOCKLIST_NAME) do |request|
+        adapter.blocked?(request)
+      end
+
+      subscribe!
+      @installed = true
+    end
+
+    # Refreshes the snapshot when the version counter changed. Redis problems
+    # must not take the application down, so the last known snapshot is kept.
+    def sync!(force: false)
+      current = Parry.store.version
+      return @rule_set if !force && @version == current
+
+      @mutex.synchronize do
+        return @rule_set if !force && @version == current
+
+        rule_set = Parry.store.rule_set
+        register_throttles(rule_set)
+        @rule_set = rule_set
+        @version = rule_set.version
+      end
+      @rule_set
+    rescue => e
+      Parry.logger.error("[parry] could not load rules: #{e.class}: #{e.message}")
+      @rule_set
+    end
+
+    # Decides whether the request is blocked, and springs any honeypot it walks
+    # into. Runs after the safelist check, so a safelisted host is never
+    # caught.
+    def blocked?(request)
+      ip = request.ip
+      snapshot = @rule_set
+
+      if (rule = snapshot.blocklist_rule_for(ip))
+        request.env[MATCHED_RULE_KEY] = "Blocklist: #{rule.label}"
+        return true
+      end
+
+      if (caught = snapshot.caught_host(ip))
+        request.env[MATCHED_RULE_KEY] = honeypot_label(caught.rule)
+        return true
+      end
+
+      if (rule = snapshot.honeypot_rule_for_path(request.path))
+        catch_host(ip, rule, request.path)
+        request.env[MATCHED_RULE_KEY] = honeypot_label(rule.label)
+        return true
+      end
+
+      false
+    end
+
+    # Removes the Parry blocklist rules covering +ip+, resets the throttle
+    # counters recorded against it and forgets it in the blocked hosts list.
+    def unblock(ip)
+      removed = Parry.store.delete_matching_ip(ip, kinds: ["blocklist"])
+      Parry.honeypots.release(ip)
+      reset_throttle_counters(ip)
+      Parry.tracker.forget(ip)
+      sync!(force: true)
+      removed
+    end
+
+    # Resets the current counter window of every registered throttle for +ip+,
+    # including throttles the host application defined itself.
+    def reset_throttle_counters(ip)
+      discriminator = normalize_discriminator(ip)
+      Rack::Attack.throttles.each do |name, throttle|
+        period = throttle.period
+        next if period.respond_to?(:call)
+
+        Rack::Attack.cache.reset_count("#{name}:#{discriminator}", period)
+      end
+      true
+    rescue => e
+      Parry.logger.warn("[parry] could not reset throttle counters for #{ip}: #{e.class}: #{e.message}")
+      false
+    end
+
+    # Records blocked and throttled requests so they show up in the GUI.
+    def subscribe!
+      return false if @subscribed || !Parry.config.track_events
+
+      adapter = self
+      ActiveSupport::Notifications.subscribe(/\.rack_attack\z/) do |name, _start, _finish, _id, payload|
+        adapter.handle_event(name.split(".").first, payload[:request])
+      end
+      @subscribed = true
+    end
+
+    def handle_event(match_type, request)
+      return unless %w[blocklist throttle].include?(match_type)
+      return if request.nil?
+
+      Parry.tracker.record(
+        ip: request.ip,
+        match_type: match_type,
+        rule: rule_label_for(match_type, request),
+        path: request.path
+      )
+    rescue => e
+      Parry.logger.warn("[parry] could not record blocked host: #{e.class}: #{e.message}")
+    end
+
+    # Forgets the registered hooks. Only useful in tests.
+    def reset!
+      @rule_set = RuleSet.empty
+      @version = nil
+      @installed = false
+    end
+
+    private
+
+    # Records the host, but a Redis failure must not let it through: the
+    # caller blocks the request either way.
+    def catch_host(ip, rule, path)
+      Parry.honeypots.record(ip, rule: rule, path: path)
+    rescue => e
+      Parry.logger.error("[parry] could not record caught host #{ip}: #{e.class}: #{e.message}")
+      false
+    end
+
+    def honeypot_label(label)
+      label.to_s.empty? ? "Honeypot" : "Honeypot: #{label}"
+    end
+
+    def rule_label_for(match_type, request)
+      known = request.env[MATCHED_RULE_KEY]
+      return known if known
+
+      matched = request.env["rack.attack.matched"]
+
+      case matched
+      when BLOCKLIST_NAME
+        rule = @rule_set.blocklist_rule_for(request.ip)
+        rule ? "Blocklist: #{rule.label}" : "Blocklist"
+      when THROTTLE_NAME_PATTERN
+        rule = @rule_set.throttle_rules.find { |candidate| candidate.id == $~[:id] }
+        rule ? "Throttle: #{rule.label}" : "Throttle"
+      else
+        matched.to_s
+      end
+    end
+
+    def register_throttles(rule_set)
+      Rack::Attack.throttles.delete_if { |name, _| name.start_with?(THROTTLE_PREFIX) }
+
+      rule_set.throttle_rules.each do |rule|
+        path_prefix = rule.path.to_s
+        Rack::Attack.throttle("#{THROTTLE_PREFIX}#{rule.id}", limit: rule.limit, period: rule.period) do |request|
+          request.ip if path_prefix.empty? || request.path.start_with?(path_prefix)
+        end
+      end
+    end
+
+    def normalize_discriminator(value)
+      normalizer = Rack::Attack.throttle_discriminator_normalizer
+      normalizer ? normalizer.call(value) : value
+    end
+  end
+end

data/lib/parry/rule.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "json"
+require "securerandom"
+require "active_model"
+
+module Parry
+  class Rule
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    KINDS = %w[honeypot blocklist safelist throttle].freeze
+    IP_KINDS = %w[blocklist safelist].freeze
+    PATH_MATCHES = %w[prefix regex].freeze
+
+    attribute :id, :string
+    attribute :kind, :string, default: "honeypot"
+    attribute :value, :string
+    attribute :name, :string
+    attribute :limit, :integer
+    attribute :period, :integer
+    attribute :path, :string
+    attribute :path_match, :string, default: "prefix"
+    attribute :created_at, :integer
+
+    attr_accessor :persisted
+
+    validates :kind, inclusion: {in: KINDS, message: "is not a valid rule type"}
+    validates :value, presence: true, if: :ip_rule?
+    validate :value_is_an_ip_or_cidr, if: -> { ip_rule? && value.present? }
+    validates :name, presence: true, if: :throttle?
+    validates :limit, numericality: {only_integer: true, greater_than: 0}, if: :throttle?
+    validates :period, numericality: {only_integer: true, greater_than: 0}, if: :throttle?
+    validate :name_is_unique_among_throttles, if: -> { throttle? && name.present? }
+    validates :path, presence: true, if: :honeypot?
+    validates :path_match, inclusion: {in: PATH_MATCHES, message: "is not a valid way to match a path"},
+      if: :honeypot?
+    validate :path_is_absolute, if: -> { honeypot? && prefix_match? && path.present? }
+    validate :path_is_a_valid_regexp, if: -> { honeypot? && regex_match? && path.present? }
+
+    class << self
+      def from_json(json)
+        attrs = JSON.parse(json)
+        rule = new(attrs.slice(*attribute_names))
+        rule.persisted = true
+        rule
+      rescue JSON::ParserError
+        nil
+      end
+
+      def kinds
+        KINDS
+      end
+    end
+
+    def ip_rule?
+      IP_KINDS.include?(kind)
+    end
+
+    def throttle?
+      kind == "throttle"
+    end
+
+    def honeypot?
+      kind == "honeypot"
+    end
+
+    def regex_match?
+      honeypot? && path_match.to_s == "regex"
+    end
+
+    def prefix_match?
+      !regex_match?
+    end
+
+    def persisted?
+      !!persisted
+    end
+
+    def to_key
+      id ? [id] : nil
+    end
+
+    def to_param
+      id
+    end
+
+    def label
+      return name if name.present?
+      return value if value.present?
+
+      path.to_s
+    end
+
+    def created_at_time
+      Time.at(created_at) if created_at
+    end
+
+    def matches_ip?(ip)
+      range = ip_range
+      return false if range.nil? || ip.nil? || ip.to_s.empty?
+
+      range.include?(IPAddr.new(ip.to_s))
+    rescue IPAddr::Error
+      false
+    end
+
+    def matches_path?(candidate)
+      return false if path.to_s.empty? || candidate.nil?
+
+      if regex_match?
+        matcher = path_regexp
+        !matcher.nil? && matcher.match?(candidate.to_s)
+      else
+        candidate.to_s.start_with?(path)
+      end
+    rescue Regexp::TimeoutError
+      # A bad pattern shouldn't hurt the request.
+      Parry.logger.error("[parry] the regex of rule #{id} timed out matching #{candidate}")
+      false
+    end
+
+    def path_regexp
+      return @path_regexp if defined?(@path_regexp)
+
+      @path_regexp = begin
+        Regexp.new(path.to_s, timeout: Parry.config.regex_timeout) if regex_match? && path.present?
+      rescue RegexpError
+        nil
+      end
+    end
+
+    def ip_range
+      return @ip_range if defined?(@ip_range)
+
+      @ip_range = begin
+        IPAddr.new(value.to_s) if ip_rule? && value.present?
+      rescue IPAddr::Error
+        nil
+      end
+    end
+
+    def normalize!
+      self.value = value.strip if value.is_a?(String)
+      self.name = name.strip if name.is_a?(String)
+      self.path = path.strip.presence if path.is_a?(String)
+      self.path_match = "prefix" unless PATH_MATCHES.include?(path_match)
+
+      if throttle?
+        self.value = nil
+        self.path_match = "prefix"
+      elsif honeypot?
+        self.value = nil
+        self.limit = nil
+        self.period = nil
+      else
+        self.limit = nil
+        self.period = nil
+        self.path = nil
+        self.path_match = "prefix"
+      end
+
+      remove_instance_variable(:@ip_range) if defined?(@ip_range)
+      remove_instance_variable(:@path_regexp) if defined?(@path_regexp)
+      self
+    end
+
+    def to_h
+      attributes.symbolize_keys
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    def value_is_an_ip_or_cidr
+      IPAddr.new(value.to_s)
+    rescue IPAddr::Error
+      errors.add(:value, "is not a valid IP address or CIDR range")
+    end
+
+    def path_is_absolute
+      errors.add(:path, "has to start with /") unless path.to_s.start_with?("/")
+    end
+
+    def path_is_a_valid_regexp
+      Regexp.new(path.to_s)
+    rescue RegexpError => e
+      errors.add(:path, "is not a valid regular expression (#{e.message.lines.first.to_s.strip})")
+    end
+
+    def name_is_unique_among_throttles
+      taken = Parry.store.where(kind: "throttle").any? { |other| other.name == name && other.id != id }
+      errors.add(:name, "is already used by another throttle") if taken
+    rescue => e
+      Parry.logger.warn("[parry] could not verify throttle name uniqueness: #{e.class}: #{e.message}")
+    end
+  end
+end