ronin-web-session_cookie 0.1.0.rc1

data/lib/ronin/web/session_cookie/django.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-session_cookie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-web-session_cookie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-web-session_cookie.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/session_cookie/cookie'
+require 'ronin/support/encoding/base64'
+require 'ronin/support/encoding/base62'
+
+require 'python/pickle'
+
+module Ronin
+  module Web
+    module SessionCookie
+      #
+      # Represents a Django signed session cookie (JSON or Pickle serialized).
+      #
+      # ## Examples
+      #
+      # Parse a Django JSON session cookie:
+      #
+      #     Ronin::Web::SessionCookie.parse('sessionid=eyJmb28iOiJiYXIifQ:1pQcTx:UufiSnuPIjNs7zOAJS0UpqnyvRt7KET7BVes0I8LYbA')
+      #     # =>
+      #     # #<Ronin::Web::SessionCookie::Django:0x00007f29bb9c6b70
+      #     #  @hmac=
+      #     #   "R\xE7\xE2J{\x8F\"3l\xEF3\x80%-\x14\xA6\xA9\xF2\xBD\e{(D\xFB\x05W\xAC\xD0\x8F\va\xB0",
+      #     #  @params={"foo"=>"bar"},
+      #     #  @salt=1676070425>
+      #
+      # Parse a Django Pickled session cookie:
+      #
+      #     Ronin::Web::SessionCookie.parse('sessionid=gAWVEAAAAAAAAAB9lIwDZm9vlIwDYmFylHMu:1pQcay:RjaK8DKN4xXQ_APIXXWEyFS08Q-PGo6UlRBFpedFk9M')
+      #     # =>
+      #     # #<Ronin::Web::SessionCookie::Django:0x00007f29b7aa6dc8
+      #     #  @hmac=
+      #     #   "F6\x8A\xF02\x8D\xE3\x15\xD0\xFC\x03\xC8]u\x84\xC8T\xB4\xF1\x0F\x8F\x1A\x8E\x94\x95\x10E\xA5\xE7E\x93\xD3",
+      #     #  @params={"foo"=>"bar"},
+      #     #  @salt=1676070860>
+      #
+      # @see https://docs.djangoproject.com/en/4.1/topics/http/sessions/#using-cookie-based-sessions
+      #
+      class Django < Cookie
+
+        # The salt used to sign the cookie.
+        #
+        # @return [Integer]
+        #
+        # @api public
+        attr_reader :salt
+
+        # The SHA256 HMAC of the Base64 encoded serialized  {#params}.
+        #
+        # @return [String]
+        #
+        # @api public
+        attr_reader :hmac
+
+        #
+        # Initializes the Django cookie.
+        #
+        # @param [Hash{String => Object}] params
+        #   The deserialized params of the session cookie.
+        #
+        # @param [Integer] salt
+        #   The Base62 decoded timestamp that is used to salt the HMAC.
+        #
+        # @param [Integer] hmac
+        #   The SHA256 HMAC of the Base64 encoded serialized  {#params}.
+        #
+        # @api private
+        #
+        def initialize(params,salt,hmac)
+          super(params)
+
+          @salt = salt
+          @hmac = hmac
+        end
+
+        # Regular expression to match Django session cookies.
+        REGEXP = /\A(?:sessionid=)?#{URL_SAFE_BASE64_REGEXP}:#{URL_SAFE_BASE64_REGEXP}:#{URL_SAFE_BASE64_REGEXP}\z/
+
+        #
+        # Identifies if the cookie is a Django session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie value.
+        #
+        # @return [Boolean]
+        #   Indicates whether the session cookie value is a Django session
+        #   cookie.
+        #
+        # @api public
+        #
+        def self.identify?(string)
+          string =~ REGEXP
+        end
+
+        #
+        # Parses a Django session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie string to parse.
+        #
+        # @return [Django]
+        #   The parsed and deserialized session cookie
+        #
+        # @api public
+        #
+        def self.parse(string)
+          # remove any 'sessionid' prefix.
+          string = string.sub(/\Asessionid=/,'')
+
+          # split the cookie
+          params, salt, hmac = string.split(':',3)
+
+          params = Support::Encoding::Base64.decode(params, mode: :url_safe)
+          params = if params.start_with?('{') && params.end_with?('}')
+                     # JSON serialized cookie
+                     JSON.parse(params)
+                   else
+                     # unpickle the Python Pickle serialized session cookie
+                     Python::Pickle.load(params)
+                   end
+
+          salt = Support::Encoding::Base62.decode(salt)
+          hmac = Support::Encoding::Base64.decode(hmac, mode: :url_safe)
+
+          return new(params,salt,hmac)
+        end
+
+        #
+        # Extracts the Django session cookie from the HTTP response.
+        #
+        # @param [Net::HTTPResponse] response
+        #   The HTTP response object.
+        #
+        # @return [Django, nil]
+        #   The parsed Django session cookie, or `nil` if there was no
+        #   `Set-Cookie` header containing a Django session cookie.
+        #
+        # @api public
+        #
+        def self.extract(response)
+          if (set_cookie = response['Set-Cookie'])
+            cookie = set_cookie.split(';',2).first
+
+            if identify?(cookie)
+              return parse(cookie)
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/web/session_cookie/jwt.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-session_cookie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-web-session_cookie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-web-session_cookie.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/session_cookie/cookie'
+
+require 'base64'
+require 'json'
+
+module Ronin
+  module Web
+    module SessionCookie
+      #
+      # Represents a [JSON Web Token (JWT)][JWT].
+      #
+      # [JWT]: https://jwt.io
+      #
+      # ## Examples
+      #
+      #     Ronin::Web::SessionCookie.parse('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c')
+      #     # =>
+      #     # #<Ronin::Web::SessionCookie::JWT:0x00007f18d5a45e58
+      #     #  @header={"alg"=>"HS256", "typ"=>"JWT"},
+      #     #  @hmac=
+      #     #   ":\x93\x92K\x0E\xDE\xE3\xCEK8\xFEO\xAF4\x9C\xC4v\xFBI\x1E\xAC\x00\xE3\x11rG\xC5\xC2.+\xA7\xBA",
+      #     #  @params={"id"=>123456789, "name"=>"Joseph"}>
+      #
+      # @see https://jwt.io/
+      #
+      class JWT < Cookie
+
+        # The parsed JWT header information.
+        #
+        # @return [Hash{String => Object}]
+        #
+        # @api public
+        attr_reader :header
+
+        # The SHA256 HMAC of the encoded {#header} + `.` +  the encoded
+        # {#payload}.
+        #
+        # @return [String]
+        #
+        # @api public
+        attr_reader :hmac
+
+        alias payload params
+
+        #
+        # Initializes the parsed JWT session cookie.
+        #
+        # @param [Hash{String => Object}] header
+        #   The parsed header information.
+        #
+        # @param [Hash{String => Object}] payload
+        #   The parsed JWT payload.
+        #
+        # @param [String] hmac
+        #   The SHA256 HMAC of the encoded header + `.` + the encoded payload.
+        #
+        # @api private
+        #
+        def initialize(header,payload,hmac)
+          @header = header
+
+          super(payload)
+
+          @hmac = hmac
+        end
+
+        # Regular expression to match JWT session cookies.
+        REGEXP = /\A(Bearer )?#{URL_SAFE_BASE64_REGEXP}\.#{URL_SAFE_BASE64_REGEXP}\.#{URL_SAFE_BASE64_REGEXP}\z/
+
+        #
+        # Identifies whether the string is a JWT session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie value to identify.
+        #
+        # @return [Boolean]
+        #   Indicates whether the session cookie value is a JWT session cookie.
+        #
+        # @api public
+        #
+        def self.identify?(string)
+          string =~ REGEXP
+        end
+
+        #
+        # Parses a JWT session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie string to parse.
+        #
+        # @return [JWT]
+        #   The parsed and deserialized session cookie
+        #
+        # @api public
+        #
+        def self.parse(string)
+          # remove any 'Bearer ' prefix.
+          string = string.sub(/\ABearer /,'')
+
+          # split the string
+          header, payload, hmac = string.split('.',3)
+
+          header  = JSON.parse(Base64.decode64(header))
+          payload = JSON.parse(Base64.decode64(payload))
+          hmac    = Base64.decode64(hmac)
+
+          return new(header,payload,hmac)
+        end
+
+        #
+        # Extracts the JWT session cookie from the HTTP response.
+        #
+        # @param [Net::HTTPResponse] response
+        #   The HTTP response object.
+        #
+        # @return [JWT, nil]
+        #   The parsed JWT session cookie, or `nil` if there was no
+        #   `Authorization` header containing a JWT session cookie.
+        #
+        # @api public
+        #
+        def self.extract(response)
+          if (authorization = response['Authorization'])
+            if (match = authorization.match(REGEXP))
+              return parse(match[0])
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/web/session_cookie/rack.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-session_cookie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-web-session_cookie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-web-session_cookie.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/session_cookie/cookie'
+
+require 'base64'
+require 'delegate'
+require 'rack/session/cookie'
+
+module Ronin
+  module Web
+    module SessionCookie
+      #
+      # Represents a [Rack][rack-session] session cookie.
+      #
+      # [rack-session]: https://github.com/rack/rack-session
+      #
+      # ## Examples
+      #
+      #     Ronin::Web::SessionCookie.parse('rack.session=BAh7CEkiD3Nlc3Npb25faWQGOgZFVG86HVJhY2s6OlNlc3Npb246OlNlc3Npb25JZAY6D0BwdWJsaWNfaWRJIkUyYWJkZTdkM2I0YTMxNDE5OThiYmMyYTE0YjFmMTZlNTNlMWMzYWJlYzhiYzc4ZjVhMGFlMGUwODJmMjJlZGIxBjsARkkiCWNzcmYGOwBGSSIxNHY1TmRCMGRVaklXdjhzR3J1b2ZhM2xwNHQyVGp5ZHptckQycjJRWXpIZz0GOwBGSSINdHJhY2tpbmcGOwBGewZJIhRIVFRQX1VTRVJfQUdFTlQGOwBUSSItOTkxNzUyMWYzN2M4ODJkNDIyMzhmYmI5Yzg4MzFmMWVmNTAwNGQyYwY7AEY%3D--02184e43850f38a46c8f22ffb49f7f22be58e272')
+      #     # =>
+      #     # #<Ronin::Web::SessionCookie::Rack:0x00007ff67455ee30
+      #     #  @params=
+      #     #   {"session_id"=>"2abde7d3b4a3141998bbc2a14b1f16e53e1c3abec8bc78f5a0ae0e082f22edb1",
+      #     #    "csrf"=>"4v5NdB0dUjIWv8sGruofa3lp4t2TjydzmrD2r2QYzHg=",
+      #     #    "tracking"=>{"HTTP_USER_AGENT"=>"9917521f37c882d42238fbb9c8831f1ef5004d2c"}}>
+      #
+      # @see https://github.com/rack/rack-session
+      #
+      class Rack < Cookie
+
+        # The HMAC for the deserialized and Base64 encoded session cookie.
+        #
+        # @return [String]
+        attr_reader :hmac
+
+        #
+        # Initializes the parsed Rack session cookie.
+        #
+        # @param [Hash{String => Object}] params
+        #   The parsed params for the session cookie.
+        #
+        # @param [String] hmac
+        #   The HMAC for the serialized and Base64 encoded session cookie.
+        #
+        # @api private
+        #
+        def initialize(params,hmac)
+          super(params)
+
+          @hmac = hmac
+        end
+
+        # Regular expression to match Rack session cookies.
+        REGEXP = /\A(rack\.session=)?(?:#{STRICT_BASE64_REGEXP}|#{URI_ENCODED_BASE64_REGEXP})--[0-9a-f]{40}\z/
+
+        #
+        # Identifies if the cookie is a Rack session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie value to identify.
+        #
+        # @return [Boolean]
+        #   Indicates whether the session cookie is a Rack session cookie.
+        #
+        # @api public
+        #
+        def self.identify?(string)
+          string =~ REGEXP
+        end
+
+        #
+        # Parses a Django session cookie.
+        #
+        # @param [String] string
+        #   The raw session cookie string to parse.
+        #
+        # @return [Rack]
+        #   The parsed and deserialized session cookie
+        #
+        # @api public
+        #
+        def self.parse(string)
+          # remove any 'rack.session' prefix.
+          string = string.sub(/\Arack\.session=/,'')
+
+          payload, hmac = string.split('--',2)
+
+          return new(Marshal.load(Base64.decode64(payload)),hmac)
+        end
+
+        #
+        # Extracts the Rack session cookie from the HTTP response.
+        #
+        # @param [Net::HTTPResponse] response
+        #   The HTTP response object.
+        #
+        # @return [Rack, nil]
+        #   The parsed Rack session cookie, or `nil` if there was no
+        #   `Set-Cookie` header containing a Rack session cookie.
+        #
+        # @api public
+        #
+        def self.extract(response)
+          if (set_cookie = response['Set-Cookie'])
+            cookie = set_cookie.split(';',2).first
+
+            if identify?(cookie)
+              return parse(cookie)
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/web/session_cookie/version.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-session_cookie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-web-session_cookie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-web-session_cookie.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Web
+    module SessionCookie
+      # ronin-web-session_cookie version
+      VERSION = '0.1.0.rc1'
+    end
+  end
+end

data/lib/ronin/web/session_cookie.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-session_cookie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-web-session_cookie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-web-session_cookie.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/session_cookie/rack'
+require 'ronin/web/session_cookie/django'
+require 'ronin/web/session_cookie/jwt'
+
+module Ronin
+  module Web
+    #
+    # Namespace for `ronin-web-session_cookie`.
+    #
+    module SessionCookie
+      # All session cookie classes.
+      #
+      # @api private
+      CLASSES = [
+        Rack,
+        JWT,
+        Django
+      ]
+
+      #
+      # Parses the session cookie.
+      #
+      # @param [String] string
+      #   The raw session cookie to parse.
+      #
+      # @return [Rack, Django, JWT, nil]
+      #   The parsed and deserialized session cookie data.
+      #   Returns `nil` if the session cookie did not match any of the supported
+      #   formats.
+      #
+      # @api public
+      #
+      def self.parse(string)
+        CLASSES.each do |klass|
+          if klass.identify?(string)
+            return klass.parse(string)
+          end
+        end
+
+        return nil
+      end
+
+      #
+      # Extracts and parses the session cookie from the HTTP response.
+      #
+      # @param [Net::HTTPResponse] response
+      #   The HTTP response object.
+      #
+      # @return [Rack, Django, JWT, nil]
+      #   The parsed session cookie or `nil` if no session cookie could be
+      #   detected.
+      #
+      # @api public
+      #
+      def self.extract(response)
+        CLASSES.each do |klass|
+          if (session_cookie = klass.extract(response))
+            return session_cookie
+          end
+        end
+
+        return nil
+      end
+    end
+  end
+end

data/ronin-web-session_cookie.gemspec

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ronin/web/session_cookie/version'
+                  Ronin::Web::SessionCookie::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = ->(patterns) { gem.files & Dir[*patterns] }
+
+  gem.files  = `git ls-files`.split($/)
+  gem.files  = glob[gemspec['files']] if gemspec['files']
+  gem.files += Array(gemspec['generated_files'])
+  # exclude test files from the packages gem
+  gem.files -= glob[gemspec['test_files'] || 'spec/{**/}*']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = ->(string) { string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end