aikido-zen 0.1.0.alpha4

data/README.md

@@ -0,0 +1,40 @@
+# Aikido::Firewall
+
+TODO: Write me :)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add aikido-firewall
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install aikido-firewall
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome [on GitHub][repo]. This project is
+intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the [code of conduct][coc].
+
+## Code of Conduct
+
+Everyone interacting in the `Aikido::Firewall` project's codebases, issue
+trackers, chat rooms and mailing lists is expected to follow the [code of
+conduct][coc].
+
+[repo]: https://github.com/aikidosec/firewall-ruby
+[coc]: https://github.com/aikidosec/firewall-ruby/blob/main/CODE_OF_CONDUCT.md

data/Rakefile

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+require "rake/clean"
+
+load "tasklib/libzen.rake"
+
+namespace :build do
+  desc "Ensure Gemfile.lock is up-to-date"
+  task "update_gem_lockfile" do
+    sh "bundle check >/dev/null || bundle"
+  end
+end
+task build: ["build:update_gem_lockfile", "libzen:download:all"]
+
+# Build all the native gems as well
+Rake::Task["build"].enhance(["libzen:gems"])
+
+# rake release wants to tag the commit and push the tag, but we run the release
+# workflow after creating the tag, and so we don't need another one.
+Rake::Task["release:source_control_push"].clear
+task "release:source_control_push" do
+  # do nothing
+end
+
+# Push all the native gems before the libzen-less one.
+task "release:rubygem_push" => "libzen:release"
+
+Pathname.glob("sample_apps/*").select(&:directory?).each do |dir|
+  namespace :build do
+    desc "Ensure Gemfile.lock is up-to-date in the #{dir.basename} sample app"
+    task "update_#{dir.basename}_lockfile" do
+      Dir.chdir(dir) { sh "bundle check >/dev/null || bundle" }
+    end
+  end
+
+  task build: "build:update_#{dir.basename}_lockfile"
+end
+
+Minitest::TestTask.create do |test_task|
+  test_task.test_globs = FileList["test/**/{test_*,*_test}.rb"]
+    .exclude("test/e2e/**/*.rb")
+end
+task test: "libzen:download:current"
+
+Pathname.glob("test/e2e/*").select(&:directory?).each do |dir|
+  namespace :e2e do
+    desc "Run e2e tests for the #{dir.basename} sample app"
+    task dir.basename do
+      Dir.chdir(dir) do
+        sh "rake ci:setup"
+        sh "rake test"
+      end
+    end
+  end
+
+  desc "Run all e2e tests"
+  task e2e: "e2e:#{dir.basename}"
+end
+
+task default: %i[test standard]

data/lib/aikido/zen/actor.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require_relative "config"
+
+module Aikido::Zen
+  # Converts an object into an Actor for reporting back to the Aikido Dashboard.
+  #
+  # @overload Actor(actor)
+  #   @param actor [#to_aikido_actor] anything that implements #to_aikido_actor
+  #     will have that method called and its value returned.
+  #   @return Aikido::Zen::Actor
+  #
+  # @overload Actor(data)
+  #   @param data [Hash<Symbol, String>]
+  #   @option data [String] :id a unique identifier for this user.
+  #   @option data [String, nil] :name an optional name to display in the UI.
+  #   @return Aikido::Zen::Actor
+  def self.Actor(data)
+    return if data.nil?
+    return data.to_aikido_actor if data.respond_to?(:to_aikido_actor)
+
+    attrs = {}
+    if data.respond_to?(:to_hash)
+      attrs = data.to_hash
+        .slice("id", "name", :id, :name)
+        .compact
+        .transform_keys(&:to_sym)
+        .transform_values(&:to_s)
+    else
+      return nil
+    end
+
+    return nil if attrs[:id].nil? || attrs[:id].to_s.strip.empty?
+
+    Actor.new(**attrs)
+  end
+
+  # Represents someone connecting to the application and making requests.
+  class Actor
+    # @return [String] a unique identifier for this user.
+    attr_reader :id
+
+    # @return [String, nil] an optional name to display in the Aikido UI.
+    attr_reader :name
+
+    # @return [Time]
+    attr_reader :first_seen_at
+
+    # @param id [String]
+    # @param name [String, nil]
+    # @param ip [String, nil]
+    # @param seen_at [Time]
+    def initialize(
+      id:,
+      name: nil,
+      ip: Aikido::Zen.current_context&.request&.ip,
+      seen_at: Time.now.utc
+    )
+      @id = id
+      @name = name
+      @first_seen_at = seen_at
+      @last_seen_at = Concurrent::AtomicReference.new(seen_at)
+      @ip = Concurrent::AtomicReference.new(ip)
+    end
+
+    # @return [Time]
+    def last_seen_at
+      @last_seen_at.get
+    end
+
+    # @return [String, nil] the IP address last used by this user, if available.
+    def ip
+      @ip.get
+    end
+
+    # Atomically update the last IP used by the user, and the last time they've
+    # been "seen" connecting to the app.
+    #
+    # @param ip [String, nil] the last-seen IP address for the user. If +nil+
+    #   and we had a non-empty value before, we won't update it. Defaults to
+    #   the current HTTP request's IP address, if any.
+    # @param seen_at [Time] the time at which we're making the update. We will
+    #   always keep the most recent time if this conflicts with the current
+    #   value.
+    # @return [void]
+    def update(seen_at: Time.now.utc, ip: Aikido::Zen.current_context&.request&.ip)
+      @last_seen_at.try_update { |last_seen_at| [last_seen_at, seen_at].max }
+      @ip.try_update { |last_ip| [ip, last_ip].compact.first }
+    end
+
+    # @return [self]
+    def to_aikido_actor
+      self
+    end
+
+    def ==(other)
+      other.is_a?(Actor) && id == other.id
+    end
+    alias_method :eql?, :==
+
+    def hash
+      id.hash
+    end
+
+    def as_json
+      {
+        id: id,
+        name: name,
+        lastIpAddress: ip,
+        firstSeenAt: first_seen_at.to_i * 1000,
+        lastSeenAt: last_seen_at.to_i * 1000
+      }
+    end
+  end
+end

data/lib/aikido/zen/agent.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require_relative "event"
+require_relative "stats"
+require_relative "config"
+require_relative "system_info"
+
+module Aikido::Zen
+  # Handles the background processes that communicate with the Aikido servers,
+  # including managing the runtime settings that keep the app protected.
+  class Agent
+    # @return [Aikido::Zen::Stats] the statistics collected by the agent.
+    attr_reader :stats
+
+    def initialize(
+      stats: Aikido::Zen::Stats.new,
+      config: Aikido::Zen.config,
+      info: Aikido::Zen.system_info,
+      api_client: Aikido::Zen::APIClient.new
+    )
+      @started_at = nil
+
+      @stats = stats
+      @info = info
+      @config = config
+      @api_client = api_client
+      @timer_tasks = []
+      @delayed_tasks = []
+      @reporting_pool = nil
+      @heartbeats = nil
+    end
+
+    def started?
+      !!@started_at
+    end
+
+    # Given an Attack, report it to the Aikido server, and/or block the request
+    # depending on configuration.
+    #
+    # @param attack [Attack] a detected attack.
+    # @return [void]
+    #
+    # @raise [Aikido::Zen::UnderAttackError] if the firewall is configured
+    #   to block requests.
+    def handle_attack(attack)
+      attack.will_be_blocked! if @config.blocking_mode?
+
+      @config.logger.error("[ATTACK DETECTED] #{attack.log_message}")
+      report(Events::Attack.new(attack: attack)) if @api_client.can_make_requests?
+
+      stats.add_attack(attack, being_blocked: @config.blocking_mode?)
+      raise attack if @config.blocking_mode?
+    end
+
+    # Asynchronously reports an Event of any kind to the Aikido dashboard. If
+    # given a block, the API response will be passed to the block for handling.
+    #
+    # @param event [Aikido::Zen::Event]
+    # @yieldparam response [Object] the response from the reporting API in case
+    #   of a successful request.
+    #
+    # @return [void]
+    def report(event)
+      reporting_pool.post do
+        response = @api_client.report(event)
+        yield response if response && block_given?
+      rescue Aikido::Zen::APIError, Aikido::Zen::NetworkError => err
+        @config.logger.error(err.message)
+      end
+    end
+
+    def start!
+      @config.logger.info "Starting Aikido agent"
+
+      raise Aikido::ZenError, "Aikido Agent already started!" if started?
+      @started_at = Time.now.utc
+
+      stats.start(@started_at)
+
+      if @config.blocking_mode?
+        @config.logger.info "Requests identified as attacks will be blocked"
+      else
+        @config.logger.warn "Non-blocking mode enabled! No requests will be blocked."
+      end
+
+      if @api_client.can_make_requests?
+        @config.logger.info "API Token set! Reporting has been enabled."
+      else
+        @config.logger.warn "No API Token set! Reporting has been disabled."
+        return
+      end
+
+      # Subscribe to firewall setting changes so we can correctly re-configure
+      # the heartbeat process.
+      Aikido::Zen.runtime_settings.add_observer(self, :setup_heartbeat)
+
+      at_exit { stop! if started? }
+
+      report(Events::Started.new(time: @started_at)) do |response|
+        Aikido::Zen.runtime_settings.update_from_json(response)
+        @config.logger.info "Updated runtime settings."
+      end
+
+      poll_for_setting_updates
+    end
+
+    def send_heartbeat
+      return unless @api_client.can_make_requests?
+
+      flushed_stats = stats.reset
+      report(Events::Heartbeat.new(stats: flushed_stats)) do |response|
+        Aikido::Zen.runtime_settings.update_from_json(response)
+        @config.logger.info "Updated runtime settings after heartbeat"
+      end
+    end
+
+    def poll_for_setting_updates
+      timer_task(every: @config.polling_interval) do
+        if @api_client.should_fetch_settings?
+          Aikido::Zen.runtime_settings.update_from_json(@api_client.fetch_settings)
+          @config.logger.info "Updated runtime settings after polling"
+        end
+      end
+    end
+
+    def setup_heartbeat(settings)
+      return unless @api_client.can_make_requests?
+
+      # If the desired interval changed, then clear the current heartbeat timer
+      # and set up a new one.
+      if @heartbeats&.running? && @heartbeats.execution_interval != settings.heartbeat_interval
+        @heartbeats.shutdown
+        @heartbeats = nil
+        setup_heartbeat(settings)
+
+      # If the heartbeat timer isn't running but we know how often it should run, schedule it.
+      elsif !@heartbeats&.running? && settings.heartbeat_interval&.nonzero?
+        @config.logger.debug "Scheduling heartbeats every #{settings.heartbeat_interval} seconds"
+        @heartbeats = timer_task(every: settings.heartbeat_interval, run_now: false) do
+          send_heartbeat
+        end
+
+      elsif !@heartbeats&.running?
+        @config.logger.debug(format("Heartbeat could not be setup (interval: %p)", settings.heartbeat_interval))
+      end
+
+      # If the server hasn't received any stats, we want to also run a one-off
+      # heartbeat request in a minute.
+      if !settings.received_any_stats
+        delay(@config.initial_heartbeat_delay) { send_heartbeat if stats.any? }
+      end
+    end
+
+    def stop!
+      @started_at = nil
+
+      @config.logger.info "Stopping Aikido agent"
+
+      @timer_tasks.each { |task| task.shutdown }
+      @delayed_tasks.each { |task| task.cancel if task.pending? }
+
+      @reporting_pool&.shutdown
+      @reporting_pool&.wait_for_termination(30)
+    end
+
+    private def reporting_pool
+      @reporting_pool ||= Concurrent::SingleThreadExecutor.new
+    end
+
+    private def delay(delay, &task)
+      Concurrent::ScheduledTask.execute(delay, executor: reporting_pool, &task)
+        .tap { |task| @delayed_tasks << task }
+    end
+
+    private def timer_task(every:, **opts, &block)
+      Concurrent::TimerTask.execute(
+        run_now: true,
+        interval_type: :fixed_rate,
+        execution_interval: every,
+        executor: reporting_pool,
+        **opts,
+        &block
+      ).tap { |task| @timer_tasks << task }
+    end
+  end
+end

data/lib/aikido/zen/api_client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "rate_limiter"
+
+module Aikido::Zen
+  # Implements all communication with the Aikido servers.
+  class APIClient
+    def initialize(
+      config: Aikido::Zen.config,
+      rate_limiter: Aikido::Zen::RateLimiter::Breaker.new,
+      system_info: Aikido::Zen.system_info
+    )
+      @config = config
+      @system_info = system_info
+      @rate_limiter = rate_limiter
+    end
+
+    # @return [Boolean] whether we have a configured token.
+    def can_make_requests?
+      @config.api_token.to_s.size > 0
+    end
+
+    # Checks with the Aikido Runtime API the timestamp of the last settings
+    # update, and compares against the given value.
+    #
+    # @param last_updated_at [Time]
+    #
+    # @return [Boolean]
+    # @raise (see #request)
+    def should_fetch_settings?(last_updated_at = Aikido::Zen.runtime_settings.updated_at)
+      @config.logger.debug("Polling for new runtime settings to fetch")
+
+      return false unless can_make_requests?
+      return true if last_updated_at.nil?
+
+      response = request(
+        Net::HTTP::Get.new("/config", default_headers),
+        base_url: @config.runtime_api_base_url
+      )
+
+      new_updated_at = Time.at(response["configUpdatedAt"].to_i / 1000)
+      new_updated_at > last_updated_at
+    end
+
+    # Fetches the runtime settings from the server. In case of a timeout or
+    # other low-lever error, the request will be automatically retried up to two
+    # times, after which it will raise an error.
+    #
+    # @return [Hash] decoded JSON response from the server with the runtime
+    #   settings.
+    # @raise (see #request)
+    def fetch_settings
+      @config.logger.debug("Fetching new runtime settings")
+
+      request(Net::HTTP::Get.new("/api/runtime/config", default_headers))
+    end
+
+    # @overload report(event)
+    #   Reports an event to the server.
+    #
+    #   @param event [Aikido::Zen::Event]
+    #   @return [void]
+    #   @raise (see #request)
+    #
+    # @overload report(settings_updating_event)
+    #   Reports an event that responds with updated runtime settings, and
+    #   requires us to update settings afterwards.
+    #
+    #   @param settings_updating_event [Aikido::Zen::Events::Started,
+    #     Aikido::Zen::Events::Heartbeat]
+    #   @return (see #fetch_settings)
+    #   @raise (see #request)
+    def report(event)
+      if @rate_limiter.throttle?(event)
+        @config.logger.error("Not reporting #{event.type.upcase} event due to rate limiting")
+        return
+      end
+
+      @config.logger.debug("Reporting #{event.type.upcase} event")
+
+      req = Net::HTTP::Post.new("/api/runtime/events", default_headers)
+      req.content_type = "application/json"
+      req.body = @config.json_encoder.call(event.as_json)
+
+      request(req)
+    rescue Aikido::Zen::RateLimitedError
+      @rate_limiter.open!
+      raise
+    end
+
+    # Perform an HTTP request against one of our API endpoints, and process the
+    # response.
+    #
+    # @param request [Net::HTTPRequest]
+    # @param base_url [URI] which API to use. Defaults to +Config#api_base_url+.
+    #
+    # @return [Object] the result of decoding the JSON response from the server.
+    #
+    # @raise [Aikido::Zen::APIError] in case of a 4XX or 5XX response.
+    # @raise [Aikido::Zen::NetworkError] if an error occurs trying to make the
+    #   request.
+    private def request(request, base_url: @config.api_base_url)
+      Net::HTTP.start(base_url.host, base_url.port, http_settings) do |http|
+        response = http.request(request)
+
+        case response
+        when Net::HTTPSuccess
+          @config.json_decoder.call(response.body)
+        when Net::HTTPTooManyRequests
+          raise RateLimitedError.new(request, response)
+        else
+          raise APIError.new(request, response)
+        end
+      end
+    rescue Timeout::Error, IOError, SystemCallError, OpenSSL::OpenSSLError => err
+      raise NetworkError.new(request, err)
+    end
+
+    private def http_settings
+      @http_settings ||= {use_ssl: true, max_retries: 2}.merge(@config.api_timeouts)
+    end
+
+    private def default_headers
+      @default_headers ||= {
+        "Authorization" => @config.api_token,
+        "Accept" => "application/json",
+        "User-Agent" => "#{@system_info.library_name} v#{@system_info.library_version}"
+      }
+    end
+  end
+end

data/lib/aikido/zen/attack.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  # Attack objects gather information about a type of detected attack.
+  # They can be used in a few ways, like for reporting an attack event
+  # to the Aikido server, or can be raised as errors to block requests
+  # if blocking_mode is on.
+  class Attack
+    attr_reader :context
+    attr_reader :operation
+    attr_accessor :sink
+
+    def initialize(context:, sink:, operation:)
+      @context = context
+      @operation = operation
+      @sink = sink
+      @blocked = false
+    end
+
+    def will_be_blocked!
+      @blocked = true
+    end
+
+    def blocked?
+      @blocked
+    end
+
+    def log_message
+      raise NotImplementedError, "implement in subclasses"
+    end
+
+    def as_json
+      raise NotImplementedError, "implement in subclasses"
+    end
+
+    def exception(*)
+      raise NotImplementedError, "implement in subclasses"
+    end
+  end
+
+  module Attacks
+    class SQLInjectionAttack < Attack
+      attr_reader :query
+      attr_reader :input
+      attr_reader :dialect
+
+      def initialize(query:, input:, dialect:, **opts)
+        super(**opts)
+        @query = query
+        @input = input
+        @dialect = dialect
+      end
+
+      def log_message
+        format(
+          "SQL Injection: Malicious user input «%s» detected in %s query «%s»",
+          @input, @dialect, @query
+        )
+      end
+
+      def as_json
+        {
+          kind: "sql_injection",
+          blocked: blocked?,
+          metadata: {sql: @query},
+          operation: @operation
+        }.merge(@input.as_json)
+      end
+
+      def exception(*)
+        SQLInjectionError.new(self)
+      end
+    end
+
+    class SSRFAttack < Attack
+      attr_reader :input
+      attr_reader :request
+
+      def initialize(request:, input:, **opts)
+        super(**opts)
+        @input = input
+        @request = request
+      end
+
+      def log_message
+        format(
+          "SSRF: Request to user-supplied hostname «%s» detected in %s (%s).",
+          @input, @operation, @request
+        ).strip
+      end
+
+      def exception(*)
+        SSRFDetectedError.new(self)
+      end
+
+      def as_json
+        {
+          kind: "ssrf",
+          metadata: {host: @request.uri.hostname, port: @request.uri.port},
+          blocked: blocked?,
+          operation: @operation
+        }.merge(@input.as_json)
+      end
+    end
+
+    # Special case of an SSRF attack where we don't have a context—we're just
+    # detecting a request to a particularly sensitive address.
+    class StoredSSRFAttack < Attack
+      attr_reader :hostname
+      attr_reader :address
+
+      def initialize(hostname:, address:, **opts)
+        super(**opts)
+        @hostname = hostname
+        @address = address
+      end
+
+      def log_message
+        format(
+          "Stored SSRF: Request to sensitive host «%s» (%s) detected from unknown source in %s",
+          @hostname, @address, @operation
+        )
+      end
+
+      def exception(*)
+        SSRFDetectedError.new(self)
+      end
+
+      def as_json
+        {
+          kind: "ssrf",
+          blocked: blocked?,
+          operation: @operation
+        }
+      end
+    end
+  end
+end