ronin-web-browser 0.1.0.rc1

data/lib/ronin/web/browser.rb

@@ -0,0 +1,148 @@
+# 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/agent'
+require 'ronin/web/browser/version'
+
+module Ronin
+  module Web
+    #
+    # Automates a Chrome web browser.
+    #
+    # ## Examples
+    #
+    # Initialize a headless browser:
+    #
+    # ```ruby
+    # browser = Ronin::Web::Browser.new
+    # # ...
+    # browser.quit
+    # ```
+    #
+    # Initialize a visible browser:
+    #
+    # ```ruby
+    # browser = Ronin::Web::Browser.new(visible: true)
+    # # ...
+    # browser.quit
+    # ```
+    #
+    # Opening a temporary browser and automatically quitting:
+    #
+    # ```ruby
+    # Ronin::Web::Browser.open do |browser|
+    #   # ...
+    # end
+    # ```
+    #
+    # Initializing the browser with a proxy:
+    #
+    # ```ruby
+    # browser = Ronin::Web::Browser.new(proxy: "http://proxy.example.com:8080")
+    # # ...
+    # ```
+    #
+    # Go to and screenshot a webpage:
+    #
+    # ```ruby
+    # Ronin::Web::Browser.open do |browser|
+    #   browser.go_to("https://google.com")
+    #   browser.screenshot(path: "google.png")
+    # end
+    # ```
+    #
+    # Intercept all requests:
+    #
+    # ```ruby
+    # browser = Ronin::Web::Browser.new
+    # browser.network.intercept
+    # browser.on(:request) do |request|
+    #   puts "> #{request.method} #{request.url}"
+    #   request.continue
+    # end
+    #
+    # browser.go_to("https://twitter.com/login")
+    # ```
+    #
+    # Intercept all responses for all requests:
+    #
+    # ```ruby
+    # browser = Ronin::Web::Browser.new
+    # browser.on(:response) do |exchange|
+    #   puts "> #{exchange.request.method} #{exchange.request.url}"
+    #
+    #   puts "< HTTP #{exchange.response.status}"
+    #
+    #   exchange.response.headers.each do |name,value|
+    #     puts "< #{name}: #{value}"
+    #   end
+    #
+    #   puts exchange.response.body
+    # end
+    #
+    # browser.go_to("https://twitter.com/login")
+    # ```
+    #
+    # See [ferrum] for additional documentation.
+    #
+    # [ferrum]: https://github.com/rubycdp/ferrum#readme
+    #
+    module Browser
+      #
+      # Initializes the browser agent.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Keyword arguments for {Agent#initialize}.
+      #
+      # @option kwargs [Boolean] :visible (false)
+      #   Controls whether the browser will start in visible or headless mode.
+      #
+      # @option kwargs [Boolean] headless (true)
+      #   Controls whether the browser will start in headless or visible mode.
+      #
+      # @option kwargs [String, URI::HTTP, Addressible::URI, Hash, nil] :proxy (Ronin::Support::Network::HTTP.proxy)
+      #   The proxy to send all browser requests through.
+      #
+      # @return [Agent]
+      #   A new instance of a headless or visible Chrome browser.
+      #
+      def self.new(**kwargs)
+        Agent.new(**kwargs)
+      end
+
+      #
+      # Opens a new browser.
+      #
+      # @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]
+      #   A new instance of a headless or visible Chrome browser.
+      #
+      def self.open(**kwargs,&block)
+        Agent.open(**kwargs,&block)
+      end
+    end
+  end
+end

data/ronin-web-browser.gemspec

@@ -0,0 +1,60 @@
+# 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/browser/version'
+                  Ronin::Web::Browser::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']
+
+  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

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: ronin-web-browser
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc1
+platform: ruby
+authors:
+- Postmodern
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ronin-support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  ronin-web-browser is a Ruby library for automating the Chrome web browser.
+  ronin-web-browser builds on the ferrum gem, and adds additional API methods
+  that are useful to security researchers.
+email: postmodern.mod3@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- COPYING.txt
+- ChangeLog.md
+- README.md
+files:
+- ".document"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".yardopts"
+- COPYING.txt
+- ChangeLog.md
+- Gemfile
+- README.md
+- Rakefile
+- gemspec.yml
+- lib/ronin/web/browser.rb
+- lib/ronin/web/browser/agent.rb
+- lib/ronin/web/browser/cookie.rb
+- lib/ronin/web/browser/cookie_file.rb
+- lib/ronin/web/browser/version.rb
+- ronin-web-browser.gemspec
+homepage: https://ronin-rb.dev/
+licenses:
+- LGPL-3.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: A Ruby library for automating the Chrome web browser
+test_files: []