aikido-zen 1.0.2-aarch64-linux

data/docs/rails.md

@@ -0,0 +1,112 @@
+# Setting up Zen on a Ruby on Rails application
+
+To install Zen, add the gem:
+
+```sh
+bundle add aikido-zen
+```
+
+And require it before `Bundler.require` in `config/application.rb`:
+
+```ruby
+# config/application.rb
+require_relative "boot"
+
+require "rails/all"
+
+require "aikido-zen"
+Aikido::Zen.protect!
+
+# Require the gems listed in Gemfile, including any gems
+# you've limited to :test, :development, or :production.
+Bundler.require(*Rails.groups)
+
+...
+```
+
+That's it! Zen will start to run inside your app when it starts getting
+requests.
+
+## Rate limiting and user blocking
+
+If you want to add the rate limiting feature to your app, modify your code like this:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  private
+
+  def current_user
+    return unless session[:user_id]
+    User.find(session[:user_id])
+  end
+
+  def authenticate_user!
+    # Your authentication logic here
+    # ...
+    # Optional, if you want to use user based rate limiting or block specific users
+    Aikido::Zen.set_user(
+      id: current_user.id,
+      name: current_user.name
+    )
+  end
+end
+```
+
+## Configuration
+
+Zen exposes its configuration object to the Rails configuration, which you can
+modify in an initializer if desired:
+
+```ruby
+# config/initializers/zen.rb
+Rails.application.config.zen.option = value
+```
+
+You can access the configuration object both as `Aikido::Zen.config` or
+`Rails.configuration.zen`.
+
+See our [configuration guide](./config.md) for more details.
+
+## Using Rails encrypted credentials
+
+If you're using Rails' [encrypted credentials][creds], and prefer not storing
+sensitive values in your env vars, you can easily configure Zen for it. For
+example, assuming the following credentials structure:
+
+```yaml
+# config/credentials.yml.enc
+zen:
+  token: "AIKIDO_RUNTIME_..."
+```
+
+You can tell Zen to use it like so:
+
+```ruby
+# config/initializers/zen.rb
+Rails.application.config.zen.token = Rails.application.credentials.zen.token
+```
+
+[creds]: https://guides.rubyonrails.org/security.html#environmental-security
+
+## Blocking mode
+
+By default, Zen will only detect and log attacks, but will not block them. You
+can enable blocking mode by setting the `AIKIDO_BLOCK` environment variable
+to `true`.
+
+When in blocking mode, Zen will raise an exception when it detects an attack.
+These exceptions depend on the type of attack, but all inherit from
+`Aikido::Zen::UnderAttackError`, if you wish to handle these exceptions in any
+way.
+
+## Logging
+
+You can override the logger to integrate with your application logging strategy:
+
+```ruby
+# config/initializers/zen.rb
+Rails.application.config.zen.logger = ::Rails.logger
+```
+
+Zen expects an instance of Ruby's [Logger](https://github.com/ruby/logger) class.

data/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+If the Zen Firewall isn't working as expected, follow these steps in order to diagnose common issues.
+
+## Review installation steps
+
+Double-check your setup against the [installation guide](../README.md#installation).
+
+Make sure:
+- Your runtime and framework are supported (see [Supported libraries and frameworks](../README.md#supported-libraries-and-frameworks)).
+- The package installed successfully.
+- Your framework-specific integration matches the example in the docs (for Rails, see the example in [docs/rails.md](../docs/rails.md)).
+
+## Check connection to Aikido
+
+The firewall must be able to reach Aikido's API endpoints.
+
+Test connectivity from the same environment where your app runs, following the instructions on this page: https://help.aikido.dev/zen-firewall/miscellaneous/outbound-network-connections-for-zen
+
+## Check logs for errors
+
+Common places:
+- Local dev: `cat log/development.log` or `tail -f log/development.log`
+- Docker: `docker logs <your-app-container>`
+- systemd: `journalctl -u <your-app-service> --since "1 hour ago"`
+
+Tip: search logs for lines containing `Aikido` or `Zen`.
+
+For example:
+
+```sh
+grep -Ei 'aikido|zen' log/development.log
+```
+
+## Enable debug output temporarily
+
+If you use Rails, set the log level to `info` or `debug` while you investigate.
+
+```ruby
+# config/environments/development.rb or production.rb
+config.log_level = :info # use :debug if needed
+```
+
+If you have your own logger, make sure Zen logs go to stdout.
+
+You can enable Zen debugging mode as follows.
+
+```ruby
+# config/initializers/zen.rb
+Rails.application.config.zen.debugging = true
+```
+
+Or set `AIKIDO_DEBUG=true` in your environment.
+
+## Contact support
+
+If you still can't resolve the problem:
+
+- Use the in-app chat to reach our support team directly.
+- Or create an issue on [GitHub](https://github.com/AikidoSec/firewall-ruby/issues) with details about your setup, framework, and logs.
+
+Include as much context as possible; this helps us respond faster.

data/lib/aikido/zen/actor.rb

@@ -0,0 +1,146 @@
+# 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
+    def self.from_json(data)
+      new(
+        id: data[:id],
+        name: data[:name],
+        ip: data[:lastIpAddress],
+        first_seen_at: Time.at(data[:firstSeenAt] / 1000),
+        last_seen_at: Time.at(data[:lastSeenAt] / 1000)
+      )
+    end
+
+    # @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 first_seen_at [Time]
+    # @param last_seen_at [Time]
+    def initialize(
+      id:,
+      name: nil,
+      ip: Aikido::Zen.current_context&.request&.ip,
+      first_seen_at: Time.now.utc,
+      last_seen_at: first_seen_at
+    )
+      @id = id
+      @name = name
+      @ip = Concurrent::AtomicReference.new(ip)
+      @first_seen_at = first_seen_at
+      @last_seen_at = Concurrent::AtomicReference.new(last_seen_at)
+    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
+
+    # Merges the actor with another actor.
+    #
+    # @param other [Aikido::Zen::Actor]
+    # @return [Aikido::Zen::Actor]
+    def merge(other)
+      older = (first_seen_at < other.first_seen_at) ? self : other
+      newer = (last_seen_at > other.last_seen_at) ? self : other
+
+      self.class.new(
+        id: @id,
+        name: newer.name,
+        ip: newer.ip,
+        first_seen_at: older.first_seen_at,
+        last_seen_at: newer.last_seen_at
+      )
+    end
+    alias_method :|, :merge
+
+    # @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
+      }.compact
+    end
+  end
+end

data/lib/aikido/zen/agent/heartbeats_manager.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  # Handles scheduling the heartbeats we send to the Aikido servers, managing
+  # runtime changes to the heartbeat interval.
+  class Agent::HeartbeatsManager
+    def initialize(worker:, settings: Aikido::Zen.runtime_settings, config: Aikido::Zen.config)
+      @settings = settings
+      @config = config
+      @worker = worker
+
+      @timer = nil
+    end
+
+    # @return [Boolean]
+    def running?
+      !!@timer&.running?
+    end
+
+    # @return [Boolean] whether the currently running heartbeat matches the
+    #   expected interval in the runtime settings.
+    def stale_settings?
+      running? && @timer.execution_interval != interval
+    end
+
+    # Sets up the the timer to run the given block at the appropriate interval.
+    # Re-entrant, and does nothing if already running.
+    #
+    # @return [void]
+    def start(&task)
+      return if running?
+
+      if interval&.nonzero?
+        @config.logger.debug "Scheduling heartbeats every #{interval} seconds"
+        @timer = @worker.every(interval, run_now: false, &task)
+      else
+        @config.logger.warn(format("Heartbeat could not be set up (interval: %p)", interval))
+      end
+    end
+
+    # Cleans up the timer.
+    #
+    # @return [void]
+    def stop
+      return unless running?
+
+      @timer.shutdown
+      @timer = nil
+    end
+
+    # Resets the timer to start with any new settings, if needed.
+    #
+    # @return [void]
+    def restart(&task)
+      stop
+      start(&task)
+    end
+
+    # @api private
+    #
+    # @return [Integer] the current delay between events.
+    def interval
+      @settings.heartbeat_interval
+    end
+  end
+end

data/lib/aikido/zen/agent.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require_relative "event"
+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
+    # Initialize and start an agent instance.
+    #
+    # @return [Aikido::Zen::Agent]
+    def self.start(**opts)
+      new(**opts).tap(&:start!)
+    end
+
+    def initialize(
+      config: Aikido::Zen.config,
+      collector: Aikido::Zen.collector,
+      detached_agent: Aikido::Zen.detached_agent,
+      worker: Aikido::Zen::Worker.new(config: config),
+      api_client: Aikido::Zen::APIClient.new(config: config)
+    )
+      @started_at = nil
+
+      @config = config
+      @worker = worker
+      @api_client = api_client
+      @collector = collector
+      @detached_agent = detached_agent
+    end
+
+    def started?
+      !!@started_at
+    end
+
+    def start!
+      @config.logger.info("Starting Aikido agent v#{Aikido::Zen::VERSION}")
+
+      raise Aikido::ZenError, "Aikido Agent already started!" if started?
+      @started_at = Time.now.utc
+      @collector.start(at: @started_at)
+
+      if Aikido::Zen.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
+
+      at_exit { stop! if started? }
+
+      report(Events::Started.new(time: @started_at)) do |response|
+        updated_settings! if Aikido::Zen.runtime_settings.update_from_json(response)
+        @config.logger.info("Updated runtime settings.")
+      rescue => err
+        @config.logger.error(err.message)
+      end
+
+      poll_for_setting_updates
+
+      @config.initial_heartbeat_delays.each do |heartbeat_delay|
+        @worker.delay(heartbeat_delay) do
+          send_heartbeat
+          @config.logger.info("Executed initial heartbeat after #{heartbeat_delay} seconds")
+        end
+      end
+    end
+
+    # Clean up any ongoing threads, and reset the state. Called automatically
+    # when the process exits.
+    #
+    # @return [void]
+    def stop!
+      @config.logger.info("Stopping Aikido agent")
+      @started_at = nil
+      @worker.shutdown
+    end
+
+    # Respond to the runtime settings changing after being fetched from the
+    # Aikido servers.
+    #
+    # @return [void]
+    def updated_settings!
+      if !heartbeats.running?
+        heartbeats.start { send_heartbeat }
+      elsif heartbeats.stale_settings?
+        heartbeats.restart { send_heartbeat }
+      end
+    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 Aikido::Zen.blocking_mode?
+
+      @config.logger.error(
+        format("Zen has %s a %s: %s", attack.blocked? ? "blocked" : "detected", attack.humanized_name, attack.as_json.to_json)
+      )
+      report(Events::Attack.new(attack: attack)) if @api_client.can_make_requests?
+
+      @collector.track_attack(attack)
+      raise attack if attack.blocked?
+    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)
+      @worker.perform 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
+
+    # @api private
+    #
+    # Atomically flushes all the stats stored by the agent, and sends a
+    # heartbeat event. Scheduled to run automatically on a recurring schedule
+    # when reporting is enabled.
+    #
+    # @param at [Time] the event time. Defaults to now.
+    # @return [void]
+    # @see Aikido::Zen::RuntimeSettings#heartbeat_interval
+    def send_heartbeat(at: Time.now.utc)
+      return unless @api_client.can_make_requests?
+
+      heartbeat = @collector.flush
+      report(heartbeat) do |response|
+        updated_settings! if Aikido::Zen.runtime_settings.update_from_json(response)
+        @config.logger.info("Updated runtime settings after heartbeat")
+      end
+    end
+
+    # @api private
+    #
+    # Sets up the timer task that polls the Aikido Runtime API for updates to
+    # the runtime settings every minute.
+    #
+    # @return [void]
+    # @see Aikido::Zen::RuntimeSettings
+    def poll_for_setting_updates
+      @worker.every(@config.polling_interval) do
+        if @api_client.should_fetch_settings?
+          updated_settings! if Aikido::Zen.runtime_settings.update_from_json(@api_client.fetch_settings)
+          @config.logger.info("Updated runtime settings after polling")
+        end
+      end
+    end
+
+    private def heartbeats
+      @heartbeats ||= Aikido::Zen::Agent::HeartbeatsManager.new(
+        config: @config,
+        worker: @worker
+      )
+    end
+  end
+end
+
+require_relative "agent/heartbeats_manager"

data/lib/aikido/zen/api_client.rb

@@ -0,0 +1,145 @@
+# 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.realtime_endpoint
+      )
+
+      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)
+      event_type = if event.respond_to?(:type)
+        event.type
+      else
+        event[:type]
+      end
+
+      if @rate_limiter.throttle?(event_type)
+        @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 = if event.respond_to?(:as_json)
+        @config.json_encoder.call(event.as_json)
+      else
+        @config.json_encoder.call(event)
+      end
+
+      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_endpoint+.
+    #
+    # @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_endpoint)
+      Net::HTTP.start(base_url.host, base_url.port, http_settings(base_url)) 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(base_url)
+      @http_settings ||= {
+        use_ssl: base_url.scheme == "https",
+        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