aikido-zen 0.1.0.alpha4-x86_64-darwin

data/lib/aikido/zen/request/rails_router.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../route"
+require_relative "../request"
+
+module Aikido::Zen
+  # The Rails router relies on introspecting the routes defined in the Rails
+  # app to match the current request to the correct route, building Route
+  # objects that have the exact pattern defined by the developer, rather than
+  # a heuristic approximation.
+  #
+  # For example, given the following route definitions:
+  #
+  #   resources :posts do
+  #     resources :comments
+  #   end
+  #
+  # The router will map a request to "/posts/123/comments/234" to
+  # "/posts/:post_id/comments/:id(.:format)".
+  #
+  # @see Aikido::Zen::Router::HeuristicRouter
+  class Request::RailsRouter
+    def initialize(route_set)
+      @route_set = route_set
+    end
+
+    def recognize(request)
+      recognize_in_route_set(request, @route_set)
+    end
+
+    private def recognize_in_route_set(request, route_set, prefix: nil)
+      route_set.router.recognize(request) do |route, _|
+        app = route.app
+        next unless app.matches?(request)
+
+        if app.dispatcher?
+          return build_route(route, request, prefix: prefix)
+        end
+
+        if app.engine?
+          # If the SCRIPT_NAME has any path parameters, we want those to be
+          # captured by the router. (eg `mount API => "/api/:version/`)
+          prefix = ActionDispatch::Routing::RouteWrapper.new(route).path
+          return recognize_in_route_set(request, app.rack_app.routes, prefix: prefix)
+        end
+
+        if app.rack_app.respond_to?(:redirect?) && app.rack_app.redirect?
+          return build_route(route, request, prefix: prefix)
+        end
+
+        # At this point we're matching plain Rack apps, where Rails does not
+        # remove the SCRIPT_NAME from PATH_INFO, so we should avoid adding
+        # SCRIPT_NAME twice.
+        return build_route(route, request, prefix: nil)
+      end
+
+      nil
+    end
+
+    private def build_route(route, request, prefix: request.script_name)
+      Rails::Route.new(route, prefix: prefix, verb: request.request_method)
+    end
+  end
+
+  module Rails
+    class Route < Aikido::Zen::Route
+      attr_reader :verb
+
+      def initialize(rails_route, verb: rails_route.verb, prefix: nil)
+        @route = ActionDispatch::Routing::RouteWrapper.new(rails_route)
+        @verb = verb
+        @prefix = prefix
+      end
+
+      def path
+        if @prefix.present?
+          File.join(@prefix.to_s, @route.path).chomp("/")
+        else
+          @route.path
+        end
+      end
+    end
+  end
+end

data/lib/aikido/zen/request/schema/auth_discovery.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "auth_schemas"
+
+module Aikido::Zen
+  class Request::Schema
+    class AuthDiscovery
+      def initialize(context)
+        @context = context
+      end
+
+      def schemas
+        schemas = []
+        schemas << extract_from_authorization_header if headers["Authorization"]
+        schemas.concat(extract_from_headers)
+        schemas.concat(extract_from_cookies)
+
+        AuthSchemas.new(schemas)
+      end
+
+      private
+
+      def extract_from_authorization_header
+        type, _ = headers["Authorization"].to_s.split(/\s+/, 2)
+
+        if AUTHORIZATION_SCHEMES.include?(type.to_s.downcase)
+          AuthSchemas::Authorization.new(type)
+        else
+          AuthSchemas::ApiKey.new(:header, "Authorization")
+        end
+      end
+
+      def extract_from_headers
+        (headers.keys & COMMON_API_KEY_HEADERS)
+          .map { |header| AuthSchemas::ApiKey.new(:header, header) }
+      end
+
+      def extract_from_cookies
+        cookie_names = @context.payload_sources[:cookie].keys.map(&:downcase)
+
+        (cookie_names & COMMON_COOKIE_NAMES)
+          .map { |cookie| AuthSchemas::ApiKey.new(:cookie, cookie) }
+      end
+
+      def headers
+        @context.request.normalized_headers
+      end
+
+      AUTHORIZATION_SCHEMES = %w[
+        basic
+        bearer
+        digest
+        dpop
+        gnap
+        hoba
+        mutal
+        negotiate
+        privatetoken
+        scram-sha-1
+        scram-sha-256
+        vapid
+      ].freeze
+
+      COMMON_API_KEY_HEADERS = %w[
+        Apikey
+        Api-Key
+        Token
+        X-Api-Key
+        X-Token
+      ]
+
+      COMMON_COOKIE_NAMES = %w[
+        user_id
+        auth
+        session
+        jwt
+        token
+        sid
+        connect.sid
+        auth_token
+        access_token
+        refresh_token
+      ]
+    end
+  end
+end

data/lib/aikido/zen/request/schema/auth_schemas.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  class Request::Schema
+    class AuthSchemas
+      attr_reader :schemas
+
+      def initialize(schemas)
+        @schemas = schemas
+      end
+
+      def merge(other)
+        self.class.new((schemas + other.schemas).uniq)
+      end
+      alias_method :|, :merge
+
+      def as_json
+        @schemas.map(&:as_json) unless @schemas.empty?
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && schemas == other.schemas
+      end
+
+      NONE = new([])
+
+      Authorization = Struct.new(:scheme) do
+        def as_json
+          {type: "http", scheme: scheme.downcase}
+        end
+      end
+
+      ApiKey = Struct.new(:location, :name) do
+        def as_json
+          {type: "apiKey", in: location, name: name}.compact
+        end
+      end
+    end
+  end
+end

data/lib/aikido/zen/request/schema/builder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "definition"
+require_relative "empty_schema"
+require_relative "auth_discovery"
+
+module Aikido::Zen
+  class Request::Schema
+    # @api private
+    class Builder
+      def initialize(context: Aikido::Zen.current_context, config: Aikido::Zen.config)
+        @context = context
+        @config = config
+        @max_depth = @config.api_schema_collection_max_depth
+        @max_props = @config.api_schema_collection_max_properties
+      end
+
+      def schema
+        return unless @config.api_schema_collection_enabled?
+
+        Request::Schema.new(
+          content_type: body_data_type,
+          body_schema: body_schema,
+          query_schema: query_schema,
+          auth_schema: AuthDiscovery.new(@context).schemas
+        )
+      end
+
+      private
+
+      def new(definition)
+        Aikido::Zen::Request::Schema::Definition.new(definition)
+      end
+
+      def request
+        @context.request
+      end
+
+      def body_data_type
+        media_type = request.media_type.to_s
+
+        # If the media type includes any tree other than the standard (vnd., prs.,
+        # x., etc) and a suffix, then remove that bit and just keep the suffix,
+        # which should tell us what the underlying data structure is.
+        #
+        # application/json               => application/json
+        # application/vnd.github.v3+json => application/json
+        media_type = media_type.sub(%r{/.*\+}, "/") if media_type.include?("+")
+
+        DATA_TYPES.fetch(media_type, nil)
+      end
+
+      def query_schema
+        return EMPTY_SCHEMA if request.query_string.to_s.empty?
+
+        discover_schema(@context.payload_sources[:query])
+      end
+
+      def body_schema
+        return EMPTY_SCHEMA if request.content_length.to_i.zero?
+
+        discover_schema(sanitize_data(@context.payload_sources[:body]))
+      end
+
+      def discover_schema(object, depth: 0)
+        case object
+        when nil
+          new(type: "null")
+        when true, false
+          new(type: "boolean")
+        when String
+          new(type: "string")
+        when Integer
+          new(type: "integer")
+        when Numeric
+          new(type: "number")
+        when Array
+          # If the array has at least one item, we assume it's homogeneous for
+          # performance reasons, and so only inspect the type of the first one.
+          sub_schema = {items: discover_schema(object.first, depth: depth + 1)} unless object.empty?
+          new({type: "array"}.merge(sub_schema.to_h))
+        when Hash
+          object
+            .take(@max_props)
+            .each_with_object({type: "object", properties: {}}) { |(key, value), schema|
+              break schema if depth >= @max_depth
+              schema[:properties][key] = discover_schema(value, depth: depth + 1)
+            }
+            .then { |dfn| new(dfn) }
+        end
+      end
+
+      # By default, Rails' automatic decoding wraps non Hash inputs in a Hash
+      # with a _json key, so that the "params" object is always a Hash. So, for
+      # example, the request body: '["this","is","json"]' is transformed to
+      # '{"_json": ["this","is","json"]}' before being passed to the controller.
+      #
+      # We want to make sure to avoid this extra key when building the schema,
+      # since we won't be able to play back requests with it.
+      def sanitize_data(data)
+        return data unless @context.request.framework == "rails"
+        return data unless data.is_a?(Hash)
+
+        if data.is_a?(Hash) && data.keys == ["_json"]
+          data["_json"]
+        else
+          data
+        end
+      end
+
+      DATA_TYPES = {
+        "application/csp-report" => :json,
+        "application/x-json" => :json,
+        "application/json" => :json,
+
+        "application/x-www-form-urlencoded" => :"form-urlencoded",
+
+        "multipart/form-data" => :"form-data",
+
+        "application/xml" => :xml,
+        "text/xml" => :xml
+      }
+    end
+  end
+end

data/lib/aikido/zen/request/schema/definition.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "empty_schema"
+
+module Aikido::Zen
+  class Request::Schema
+    # @api private
+    #
+    # The "JSON Schema"-like implementation that we extract from looking at the
+    # request body and/or query string.
+    class Definition
+      extend Forwardable
+      def_delegators :definition, :deconstruct_keys
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # Recursively merges this schema definition with another one.
+      #
+      # * Properties missing in one or the other schemas are treated as optional.
+      # * Merging any property with a null schema results in an optional schema.
+      # * Number and Integer schemas are merged into Number schemas, since it's
+      #   the more permissive of the types.
+      #
+      # Other than that, everything else just results in additive merging,
+      # resulting in combining types together.
+      #
+      # @param other [Aikido::Zen::Request::Schema::Definition, nil]
+      # @return [Aikido::Zen::Request::Schema::Definition]
+      #
+      # @see https://cswr.github.io/JsonSchema/spec/introduction/
+      def merge(other)
+        case [self, other]
+
+        # Merging with itself or with nil results in just a copy
+        in [obj, ^obj | nil | EMPTY_SCHEMA]
+          dup
+
+        # objects where at least one of them has properties
+        in [{type: "object", properties: _}, {type: "object", properties: _}] |
+           [{type: "object", properties: _}, {type: "object"}] |
+           [{type: "object"}, {type: "object", properties: _}]
+          left, right = definition[:properties], other.definition[:properties]
+          merged_props = (left.keys.to_a | right.keys.to_a)
+            .map { |key| [key, left.fetch(key, NULL).merge(right.fetch(key, NULL))] }
+            .to_h
+          new(definition.merge(other.definition).merge(properties: merged_props))
+
+        # arrays where at least one of them has items
+        in [{type: "array", items: _}, {type: "array", items: _}] |
+           [{type: "array", items: _}, {type: "array"}] |
+           [{type: "array"}, {type: "array", items: _}]
+          items = [definition[:items], other.definition[:items]].compact.reduce(:merge)
+          new(definition.merge(other.definition).merge({items: items}.compact))
+
+        # x | x => x
+        in {type: type}, {type: ^type}
+          new(definition.merge(other.definition))
+
+        # any | null => any?
+        in {type: "null"}, {type: _}
+          new(other.definition.merge(optional: true))
+        in {type: _}, {type: "null"}
+          new(definition.merge(optional: true))
+
+        # number | integer => number
+        in [{type: "integer"}, {type: "number"}] |
+           [{type: "number"}, {type: "integer"}]
+          new(definition.merge(other.definition).merge(type: "number"))
+
+        # x | y => [x, y] if x != y
+        else
+          left_type, right_type = definition[:type], other.definition[:type]
+          types = [left_type, right_type].flatten.uniq.sort
+          new(definition.merge(other.definition).merge(type: types))
+
+        end
+      end
+      alias_method :|, :merge
+
+      def ==(other)
+        as_json == other.as_json
+      end
+
+      def as_json
+        definition
+          .transform_keys(&:to_s)
+          .transform_values do |val|
+            val.respond_to?(:as_json) ? val.as_json : val
+          end
+      end
+
+      def inspect
+        format("#<%s %p>", self.class, definition)
+      end
+
+      protected
+
+      attr_reader :definition
+
+      private
+
+      def new(definition)
+        self.class.new(definition)
+      end
+
+      NULL = new(type: "null") # used as a stand-in to merge missing object props
+    end
+  end
+end

data/lib/aikido/zen/request/schema/empty_schema.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  class Request::Schema
+    # @!visibility private
+    #
+    # Singleton used as a placeholder until we get a schema for a request.
+    # When "merged" it waits until a non-nil value is given and returns that.
+    EMPTY_SCHEMA = Object.new
+
+    class << EMPTY_SCHEMA
+      # @!visibility private
+      def merge(schema)
+        schema || self
+      end
+      alias_method :|, :merge
+
+      # @!visibility private
+      def as_json
+        nil
+      end
+
+      def inspect
+        "#<Aikido::Zen::Schema EMPTY>"
+      end
+    end
+  end
+end

data/lib/aikido/zen/request/schema.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Aikido::Zen
+  # Defines the shape of a request received by your application as seen by Zen.
+  # This is used to understand how requests are made against your app, so
+  # dynamic security testing on your API endpoints can take place.
+  #
+  # @see Aikido::Zen::Config#api_schema_collection_enabled?
+  class Request::Schema
+    # @return [Symbol, nil] an identifier for the Content-Type header of the
+    #   request, if sent.
+    attr_reader :content_type
+
+    # @return [Aikido::Zen::Request::Schema::Definition]
+    attr_reader :body_schema
+
+    # @return [Aikido::Zen::Request::Schema::Definition]
+    attr_reader :query_schema
+
+    # @return [Aikido::Zen::Request::Schema::AuthSchemas]
+    attr_reader :auth_schema
+
+    # Extracts the request information from the current Context (if configured)
+    # and builds a Schema out of it.
+    #
+    # @param context [Aikido::Zen::Context, nil]
+    # @return [Aikido::Zen::Request::Schema, nil]
+    def self.build(context = Aikido::Zen.current_context)
+      return if context.nil?
+
+      Request::Schema::Builder.new(context: context).schema
+    end
+
+    def initialize(content_type:, body_schema:, query_schema:, auth_schema:)
+      @content_type = content_type
+      @query_schema = query_schema
+      @body_schema = body_schema
+      @auth_schema = auth_schema
+    end
+
+    # @return [Hash]
+    def as_json
+      body = {type: content_type, schema: body_schema.as_json}.compact
+      body = nil if body.empty?
+
+      {body: body, query: query_schema.as_json, auth: auth_schema.as_json}.compact
+    end
+
+    # Merges the request specification with another request's specification.
+    #
+    # @param other [Aikido::Zen::Request::Schema, nil]
+    # @return [Aikido::Zen::Request::Schema]
+    def merge(other)
+      return self if other.nil?
+
+      self.class.new(
+        # TODO: this is currently overriding the content type with the new
+        # value, but we should support APIs that accept input in many types
+        # (e.g. JSON and XML)
+        content_type: other.content_type,
+        body_schema: body_schema.merge(other.body_schema),
+        query_schema: query_schema.merge(other.query_schema),
+        auth_schema: auth_schema.merge(other.auth_schema)
+      )
+    end
+    alias_method :|, :merge
+  end
+end
+
+require_relative "schema/builder"

data/lib/aikido/zen/request.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Aikido::Zen
+  # Wrapper around Rack::Request-like objects to add some behavior.
+  class Request < SimpleDelegator
+    # @return [String] identifier of the framework handling this HTTP request.
+    attr_reader :framework
+
+    # @return [Aikido::Zen::Router]
+    attr_reader :router
+
+    def initialize(delegate, framework:, router:)
+      super(delegate)
+      @framework = framework
+      @router = router
+      @body_read = false
+    end
+
+    def __setobj__(delegate) # :nodoc:
+      super
+      @body_read = false
+      @route = @normalized_header = @truncated_body = nil
+    end
+
+    # @return [Aikido::Zen::Route] the framework route being requested.
+    def route
+      @route ||= @router.recognize(self)
+    end
+
+    # @return [Aikido::Zen::Request::Schema, nil]
+    def schema
+      @schema ||= Aikido::Zen::Request::Schema.build
+    end
+
+    # Map the CGI-style env Hash into "pretty-looking" headers, preserving the
+    # values as-is. For example, HTTP_ACCEPT turns into "Accept", CONTENT_TYPE
+    # turns into "Content-Type", and HTTP_X_FORWARDED_FOR turns into
+    # "X-Forwarded-For".
+    #
+    # @return [Hash<String, String>]
+    def normalized_headers
+      @normalized_headers ||= env.slice(*BLESSED_CGI_HEADERS)
+        .merge(env.select { |key, _| key.start_with?("HTTP_") })
+        .transform_keys { |header|
+          name = header.sub(/^HTTP_/, "").downcase
+          name.split("_").map { |part| part[0].upcase + part[1..] }.join("-")
+        }
+    end
+
+    # @api private
+    #
+    # Reads the first 16KiB of the request body, to include in attack reports
+    # back to the Aikido server. This method should only be called if an attack
+    # is detected during the current request.
+    #
+    # If the underlying IO object has been partially (or fully) read before,
+    # this will attempt to restore the previous cursor position after reading it
+    # if possible, or leave if rewund if not.
+    #
+    # @param max_size [Integer] number of bytes to read at most.
+    #
+    # @return [String]
+    def truncated_body(max_size: 16384)
+      return @truncated_body if @body_read
+      return nil if body.nil?
+
+      begin
+        initial_pos = body.pos if body.respond_to?(:pos)
+        body.rewind
+        @truncated_body = body.read(max_size)
+      ensure
+        @body_read = true
+        body.rewind
+        body.seek(initial_pos) if initial_pos && body.respond_to?(:seek)
+      end
+    end
+
+    def as_json
+      {
+        method: request_method.downcase,
+        url: url,
+        ipAddress: ip,
+        userAgent: user_agent,
+        headers: normalized_headers.reject { |_, val| val.to_s.empty? },
+        body: truncated_body,
+        source: framework,
+        route: route&.path
+      }
+    end
+
+    BLESSED_CGI_HEADERS = %w[CONTENT_TYPE CONTENT_LENGTH]
+  end
+end
+
+require_relative "request/schema"

data/lib/aikido/zen/route.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Aikido::Zen
+  # Routes keep information about the mapping defined in the current web
+  # framework to go from a given HTTP request to the code that handles said
+  # request.
+  class Route
+    # @return [String] the HTTP verb used to request this route.
+    attr_reader :verb
+
+    # @return [String] the URL pattern used to match request paths. For
+    #   example "/users/:id".
+    attr_reader :path
+
+    def initialize(verb:, path:)
+      @verb = verb
+      @path = path
+    end
+
+    def as_json
+      {method: verb, path: path}
+    end
+
+    def ==(other)
+      other.is_a?(Route) &&
+        other.verb == verb &&
+        other.path == path
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [verb, path].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{verb} #{path.inspect}>"
+    end
+  end
+end