ronin-web-browser

ronin-web-browser

• Website
• Source
• Issues
• Documentation
• Discord | Mastodon

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.

Features

• Automates the Chrome web browser.
• Supports running in visible or headless mode.
• Supports using a HTTP proxy.
• Supports event hooks for requests and responses.
• Supports parsing, setting, loading, and saving cookies.
• Supports saving screenshots into a directory or git repository.
• Small memory footprint (~50Kb Ruby + ~600Kb headless Chrome).
• Has 81% documentation coverage.
• Has 82% test coverage.

Examples

Initialize a headless browser:

browser = Ronin::Web::Browser.new
# ...
browser.quit

Initialize a visible browser:

browser = Ronin::Web::Browser.new(visible: true)
# ...
browser.quit

Opening a temporary browser and automatically quitting:

Ronin::Web::Browser.open do |browser|
  # ...
end

Initializing the browser with a proxy:

browser = Ronin::Web::Browser.new(proxy: "http://proxy.example.com:8080")
# ...

Go to and screenshot a webpage:

Ronin::Web::Browser.open do |browser|
  browser.go_to("https://google.com")
  browser.screenshot(path: "google.png")
end

Intercept all requests:

browser = Ronin::Web::Browser.new
browser.every_request do |request|
  puts "> #{request.method} #{request.url}"
end

browser.go_to("https://twitter.com/login")

Intercept all responses for all requests:

browser = Ronin::Web::Browser.new
browser.every_response do |response,request|
  puts "> #{request.method} #{request.url}"

  puts "< HTTP #{response.status}"

  response.headers.each do |name,value|
    puts "< #{name}: #{value}"
  end

  puts response.body
end

browser.go_to("https://twitter.com/login")

Evaluate JavaScript within the current page:

browser = Ronin::Web::Browser.new
browser.goto('https://github.com')
browser.eval_js('document.cookie')
# => "..."

Load a JavaScript file into the current page as a <script> tag:

browser.load_js(url: 'https://.../file.js')

Load JavaScript code into the current page as a <script> tag:

browser.load_js(content: '...')

Inject JavaScript code into every page:

browser.inject_js('...')

See ferrum for additional documentation.

Requirements

• Ruby >= 3.0.0
• ronin-support ~> 1.0
• ferrum ~> 0.13

Install

$ gem install ronin-web-browser

Gemfile

gem 'ronin-web-browser', '~> 0.1'

gemspec

gem.add_dependency 'ronin-web-browser', '~> 0.1'

Development

1. Fork It!
2. Clone It!
3. cd ronin-web-browser/
4. bundle install
5. git checkout -b my_feature
6. Code It!
7. bundle exec rake spec
8. git push origin my_feature

License

Copyright (c) 2022-2024 Hal Brodigan ([e-mail])

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/.