ronin-web-browser

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

Fork It!
Clone It!
cd ronin-web-browser/
bundle install
git checkout -b my_feature
Code It!
bundle exec rake spec
git push origin my_feature

License

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

ronin-rb/ronin-web-browser