ronin-web-browser 0.1.0.rc1

data/lib/ronin/web/browser/agent.rb

@@ -0,0 +1,430 @@
+# frozen_string_literal: true
+#
+# ronin-web-browser - An automated Chrome API.
+#
+# Copyright (c) 2022-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-browser 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-browser 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-browser.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/browser/cookie'
+require 'ronin/web/browser/cookie_file'
+require 'ronin/support/network/http'
+
+require 'ferrum'
+require 'uri'
+
+module Ronin
+  module Web
+    module Browser
+      #
+      # Represents an instance of a Chrome headless or visible browser.
+      #
+      class Agent < Ferrum::Browser
+
+        # The configured proxy information.
+        #
+        # @return [Hash{Symbol => Object}, nil]
+        attr_reader :proxy
+
+        #
+        # Initializes the browser agent.
+        #
+        # @param [Boolean] visible
+        #   Controls whether the browser will start in visible or headless mode.
+        #
+        # @param [Boolean] headless
+        #   Controls whether the browser will start in headless or visible mode.
+        #
+        # @param [String, URI::HTTP, Addressible::URI, Hash, nil] proxy
+        #   The proxy to send all browser requests through.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for `Ferrum::Browser#initialize`.
+        #
+        def initialize(visible:  false,
+                       headless: !visible,
+                       proxy:    Ronin::Support::Network::HTTP.proxy,
+                       **kwargs)
+          proxy = case proxy
+                  when Hash, nil then proxy
+                  when URI::HTTP, Addressable::URI
+                    {
+                      host:     proxy.host,
+                      port:     proxy.port,
+                      user:     proxy.user,
+                      password: proxy.password
+                    }
+                  when String
+                    uri = URI(proxy)
+
+                    {
+                      host:     uri.host,
+                      port:     uri.port,
+                      user:     uri.user,
+                      password: uri.password
+                    }
+                  else
+                    raise(ArgumentError,"invalid proxy value (#{proxy.inspect}), must be either a Hash, URI::HTTP, String, or nil")
+                  end
+
+          @headless = headless
+          @proxy    = proxy
+
+          super(headless: headless, proxy: proxy, **kwargs)
+        end
+
+        #
+        # Opens a new browser.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {#initialize}.
+        #
+        # @yield [browser]
+        #   If a block is given, it will be passed the new browser object.
+        #   Once the block returns, `quit` will be called on the browser object.
+        #
+        # @yieldparam [Agent] browser
+        #   The newly created browser object.
+        #
+        # @return [Agent]
+        #   The opened browser object.
+        #
+        def self.open(**kwargs)
+          browser = new(**kwargs)
+
+          if block_given?
+            yield browser
+            browser.quit
+          end
+
+          return browser
+        end
+
+        #
+        # Determines whether the browser was opened in headless mode.
+        #
+        # @return [Boolean]
+        #
+        def headless?
+          @headless
+        end
+
+        #
+        # Determines whether the browser was opened in visible mode.
+        #
+        # @return [Boolean]
+        #
+        def visible?
+          !@headless
+        end
+
+        #
+        # Determines whether the proxy was initialized with a proxy.
+        #
+        def proxy?
+          !@proxy.nil?
+        end
+
+        #
+        # Enables or disables bypassing CSP.
+        #
+        # @param [Boolean] mode
+        #   Controls whether to enable or disable CSP bypassing.
+        #
+        def bypass_csp=(mode)
+          if mode then bypass_csp(enabled: true)
+          else         bypass_csp(enabled: false)
+          end
+        end
+
+        #
+        # Registers a callback for the given event type.
+        #
+        # @param [:request, :response, :dialog, String] event
+        #   The event to register a callback for.
+        #   For an exhaustive list of event String names, see the
+        #   [Chrome DevTools Protocol documentation](https://chromedevtools.github.io/devtools-protocol/1-3/)
+        #
+        # @yield [request]
+        #   If the event type is `:request` the given block will be passed the
+        #   request object.
+        #
+        # @yield [exchange]
+        #   If the event type is `:response` the given block will be passed the
+        #   network exchange object containing both the request and the response
+        #   objects.
+        #
+        # @yield [params, index, total]
+        #   Other event types will be passed a params Hash, index, and total.
+        #
+        # @yieldparam [Ferrum::Network::InterceptedRequest] request
+        #   A network request object.
+        #
+        # @yieldparam [Ferrum::Network::Exchange] exchange
+        #   A network exchange object containing both the request and respoonse
+        #   objects.
+        #
+        # @yieldparam [Hash{String => Object}] params
+        #   A params Hash containing the return value(s).
+        #
+        # @yieldparam [Integer] index
+        #
+        # @yieldparam [Integer] total
+        #
+        def on(event,&block)
+          case event
+          when :response
+            super('Network.responseReceived') do |params,index,total|
+              exchange = network.select(params['requestId']).last
+
+              if exchange
+                block.call(exchange,index,total)
+              end
+            end
+          when :close
+            super('Inspector.detached',&block)
+          else
+            super(event,&block)
+          end
+        end
+
+        #
+        # Passes every request to the given block.
+        #
+        # @yield [request]
+        #   The given block will be passed each request before it's sent.
+        #
+        # @yieldparam [Ferrum::Network::InterceptRequest] request
+        #   A network request object.
+        #
+        def every_request
+          network.intercept
+
+          on(:request) do |request|
+            yield request
+            request.continue
+          end
+        end
+
+        #
+        # Passes every response to the given block.
+        #
+        # @yield [response]
+        #   If the given block accepts a single argument, it will be passed
+        #   each response object.
+        #
+        # @yield [response, request]
+        #   If the given block accepts two arguments, it will be passed the
+        #   response and the request objects.
+        #
+        # @yieldparam [Ferrum::Network::Response] response
+        #   A respone object returned for a request.
+        #
+        # @yieldparam [Ferrum::Network::Request] request
+        #   The request object for the response.
+        #
+        def every_response(&block)
+          on(:response) do |exchange,index,total|
+            if block.arity == 2
+              yield exchange.response, exchange.request
+            else
+              yield exchange.response
+            end
+          end
+        end
+
+        #
+        # Passes every requested URL to the given block.
+        #
+        # @yield [url]
+        #   The given block will be passed every URL.
+        #
+        # @yieldparam [String] url
+        #   A URL requested by the browser.
+        #
+        def every_url
+          every_request do |request|
+            yield request.url
+          end
+        end
+
+        #
+        # Passes every requested URL that matches the given pattern to the given
+        # block.
+        #
+        # @param [String, Regexp] pattern
+        #   The pattern to filter the URLs by.
+        #
+        # @yield [url]
+        #   The given block will be passed every URL that matches the pattern.
+        #
+        # @yieldparam [String] url
+        #   A matching URL requested by the browser.
+        #
+        def every_url_like(pattern)
+          every_url do |url|
+            if pattern.match(url)
+              yield url
+            end
+          end
+        end
+
+        #
+        # The page's current URI.
+        #
+        # @return [URI::HTTP]
+        #
+        def page_uri
+          URI.parse(url)
+        end
+
+        #
+        # Queries the XPath or CSS-path query and returns the matching nodes.
+        #
+        # @return [Array<Ferrum::Node>]
+        #   The matching node.
+        #
+        def search(query)
+          if query.start_with?('/')
+            xpath(query)
+          else
+            css(query)
+          end
+        end
+
+        #
+        # Queries the XPath or CSS-path query and returns the first match.
+        #
+        # @return [Ferrum::Node, nil]
+        #   The first matching node.
+        #
+        def at(query)
+          if query.start_with?('/')
+            at_xpath(query)
+          else
+            at_css(query)
+          end
+        end
+
+        #
+        # Queries all `<a href="...">` links in the current page.
+        #
+        # @return [Array<String>]
+        #
+        def links
+          xpath('//a/@href').map(&:value)
+        end
+
+        #
+        # All link URLs in the current page.
+        #
+        # @return [Array<URI::HTTP, URI::HTTPS>]
+        #
+        def urls
+          page_uri = self.page_uri
+
+          links.map { |link| page_uri.merge(link) }
+        end
+
+        alias eval_js evaluate
+        alias load_js add_script_tag
+        alias inject_js evaluate_on_new_document
+        alias load_css add_style_tag
+
+        #
+        # Enumerates over all session cookies.
+        #
+        # @yield [cookie]
+        #   The given block will be passed each session cookie.
+        #
+        # @yieldparam [Ferrum::Cookies::Cookie] cookie
+        #   A cookie that ends with `sess` or `session`.
+        #
+        # @return [Enumerator]
+        #   If no block is given, then an Enumerator object will be returned.
+        #
+        def each_session_cookie
+          return enum_for(__method__) unless block_given?
+
+          cookies.each do |cookie|
+            yield cookie if cookie.session?
+          end
+        end
+
+        #
+        # Fetches all session cookies.
+        #
+        # @return [Array<Ferrum::Cookie>]
+        #   The matching session cookies.
+        #
+        def session_cookies
+          each_session_cookie.to_a
+        end
+
+        #
+        # Sets a cookie.
+        #
+        # @param [String] name
+        #   The cookie name.
+        #
+        # @param [String] value
+        #   The cookie value.
+        #
+        # @param [Hash{Symbol => Object}] options
+        #   Additional cookie attributes.
+        #
+        def set_cookie(name,value,**options)
+          cookies.set(name: name, value: value, **options)
+        end
+
+        #
+        # Loads the cookies from the cookie file.
+        #
+        # @param [String] path
+        #   The path to the cookie file.
+        #
+        def load_cookies(path)
+          CookieFile.new(path).each do |cookie|
+            cookies.set(cookie)
+          end
+        end
+
+        #
+        # Saves the cookies to a cookie file.
+        #
+        # @param [String] path
+        #   The path to the output cookie file.
+        #
+        def save_cookies(path)
+          CookieFile.save(path,cookies)
+        end
+
+        #
+        # Waits indefinitely until the browser window is closed.
+        #
+        def wait_until_closed
+          window_closed = false
+
+          on('Inspector.detached') do
+            window_closed = true
+          end
+
+          sleep(1) until window_closed
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/web/browser/cookie.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+#
+# ronin-web-browser - An automated Chrome API.
+#
+# Copyright (c) 2022-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-browser 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-browser 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-browser.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ferrum/cookies/cookie'
+
+module Ronin
+  module Web
+    module Browser
+      #
+      # Represents a browser cookie.
+      #
+      class Cookie < Ferrum::Cookies::Cookie
+
+        #
+        # Parses a browser cookie from a raw String.
+        #
+        # @param [String] string
+        #   The raw cookie String to parse.
+        #
+        # @return [Cookie]
+        #   The parsed cookie.
+        #
+        # @raise [ArgumentError]
+        #   The string was empty or contains an unknown field.
+        #
+        def self.parse(string)
+          fields = string.split(/;\s+/)
+
+          if fields.empty?
+            raise(ArgumentError,"cookie must not be empty: #{string.inspect}")
+          end
+
+          name, value = fields.shift.split('=',2)
+          attributes  = {
+            'name'  => name,
+            'value' => value
+          }
+
+          fields.each do |field|
+            if field.include?('=')
+              key, value = field.split('=',2)
+
+              case key
+              when 'Expires', 'Max-Age'
+                attributes['expires'] = Time.parse(value).to_i
+              when 'Path'    then attributes['path']     = value
+              when 'Domain'  then attributes['domain']   = value
+              when 'SameSite'then attributes['sameSite'] = value
+              else
+                raise(ArgumentError,"unrecognized Cookie field: #{field.inspect}")
+              end
+            else
+              case field
+              when 'HttpOnly' then attributes['httpOnly'] = true
+              when 'Secure'   then attributes['secure']   = true
+              else
+                raise(ArgumentError,"unrecognized Cookie flag: #{field.inspect}")
+              end
+            end
+          end
+
+          return new(attributes)
+        end
+
+        #
+        # The priority of the cookie.
+        #
+        # @return [String]
+        #
+        def priority
+          @attributes['priority']
+        end
+
+        #
+        # @return [Boolean]
+        #
+        def sameparty?
+          @attributes['sameParty']
+        end
+
+        alias same_party? sameparty?
+
+        #
+        # @return [String]
+        #
+        def source_scheme
+          @attributes['sourceScheme']
+        end
+
+        #
+        # @return [Integer]
+        #
+        def source_port
+          @attributes['sourcePort']
+        end
+
+        #
+        # Converts the cookie back into a raw cookie String.
+        #
+        # @return [String]
+        #   The raw cookie string.
+        #
+        def to_s
+          string = "#{@attributes['name']}=#{@attributes['value']}"
+
+          @attributes.each do |key,value|
+            case key
+            when 'name', 'value' # no-op
+            when 'domain'   then string << "; Domain=#{value}"
+            when 'path'     then string << "; Path=#{value}"
+            when 'expires'  then string << "; Expires=#{Time.at(value).httpdate}"
+            when 'httpOnly' then string << "; httpOnly" if value
+            when 'secure'   then string << "; Secure"   if value
+            end
+          end
+
+          return string
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/web/browser/cookie_file.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+#
+# ronin-web-browser - An automated Chrome API.
+#
+# Copyright (c) 2022-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-browser 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-browser 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-browser.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/web/browser/cookie'
+
+module Ronin
+  module Web
+    module Browser
+      #
+      # Represents a file of cookies.
+      #
+      class CookieFile
+
+        include Enumerable
+
+        # The path to the file.
+        #
+        # @return [String]
+        attr_reader :path
+
+        #
+        # Initializes a cookie file.
+        #
+        # @param [String] path
+        #   The path to the cookie file.
+        #
+        def initialize(path)
+          @path = File.expand_path(path)
+        end
+
+        #
+        # Writes the cookies to the cookie file.
+        #
+        # @param [String] path
+        #   The path to the cookie file to write to.
+        #
+        # @param [Array<Cookie>, Enumerator<Cookie>] cookies
+        #   The cookies to write.
+        #
+        def self.save(path,cookies)
+          File.open(path,'w') do |file|
+            cookies.each do |cookie|
+              file.puts(cookie)
+            end
+          end
+        end
+
+        #
+        # Parses each cookie in the cookie file.
+        #
+        # @yield [cookie]
+        #   The given block will be passed each cookie parsed from each line of
+        #   the file.
+        #
+        # @yieldparam [Cookie] cookie
+        #   A cookie parsed from the file.
+        #
+        # @return [Enumerator]
+        #   If no block is given, then an Enumerator will be returned.
+        #
+        def each
+          return enum_for(__method__) unless block_given?
+
+          File.open(@path) do |file|
+            file.each_line(chomp: true) do |line|
+              yield Cookie.parse(line)
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+#
+# ronin-web-browser - An automated Chrome API.
+#
+# Copyright (c) 2022-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-web-browser 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-browser 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-browser.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Web
+    module Browser
+      # ronin-web-browser version
+      VERSION = '0.1.0.rc1'
+    end
+  end
+end