ronin-support-web 0.1.0.rc1

data/lib/ronin/support/web/websocket.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web 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-support-web 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-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/web/websocket/client'
+require 'ronin/support/web/websocket/server'
+require 'ronin/support/web/websocket/mixin'
+
+require 'ronin/support/network/tcp'
+require 'ronin/support/network/ssl'
+
+module Ronin
+  module Support
+    module Web
+      #
+      # WebSocket helper methods.
+      #
+      module WebSocket
+        # @!macro [new] ssl_kwargs
+        #   @option ssl [1, 1.1, 1.2, String, Symbol, nil] :version
+        #     The SSL version to use.
+        #
+        #   @option ssl [Symbol, Boolean] :verify
+        #     Specifies whether to verify the SSL certificate.
+        #     May be one of the following:
+        #
+        #     * `:none`
+        #     * `:peer`
+        #     * `:fail_if_no_peer_cert`
+        #     * `:client_once`
+        #
+        #   @option ssl [Crypto::Key::RSA, OpenSSL::PKey::RSA, nil] :key
+        #     The RSA key to use for the SSL context.
+        #
+        #   @option ssl [String] :key_file
+        #     The path to the SSL `.key` file.
+        #
+        #   @option ssl [Crypto::Cert, OpenSSL::X509::Certificate, nil] :cert
+        #     The X509 certificate to use for the SSL context.
+        #
+        #   @option ssl [String] :cert_file
+        #     The path to the SSL `.crt` file.
+        #
+        #   @option ssl [String] :ca_bundle
+        #     Path to the CA certificate file or directory.
+
+        # @!macro [new] client_kwargs
+        #   @option kwargs [String, nil] :bind_host
+        #     The optional host to bind the server socket to.
+        #
+        #   @option kwargs [Integer, nil] :bind_port
+        #     The optioanl port to bind the server socket to. If not
+        #     specified, it will default to the port of the URL.
+        #
+        #   @!macro ssl_kwargs
+
+        #
+        # Tests whether the WebSocket is open.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.connect`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Client#initialize}.
+        #
+        # @!macro client_kwargs
+        #
+        # @return [Boolean, nil]
+        #   Specifies whether the WebSocket is open.
+        #   If the connection was not accepted, `nil` will be returned.
+        #
+        # @api public
+        #
+        def self.open?(url, ssl: {}, **kwargs)
+          uri  = URI(url)
+          host = uri.host
+          port = uri.port
+
+          case uri.scheme
+          when 'ws'
+            Support::Network::TCP.open?(host,port,**kwargs)
+          when 'wss'
+            Support::Network::SSL.open?(host,port,**kwargs,**ssl)
+          else
+            raise(ArgumentError,"unsupported WebSocket URI scheme: #{url.inspect}")
+          end
+        end
+
+        # Connects to a websocket.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.connect`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Client#initialize}.
+        #
+        # @!macro client_kwargs
+        #
+        # @yield [websocket]
+        #   If a block is given, then it will be passed the WebSocket
+        #   connection. Once the block has returned, the WebSocket connection
+        #   will be closed.
+        #
+        # @yieldparam [Client] websocket
+        #   The WebSocket connection.
+        #
+        # @return [Client]
+        #   The WebSocket connection.
+        #
+        # @example Connecting to a WebSocket server:
+        #   websocket_connect('ws://websocket-echo.com')
+        #   # => #<Ronin::Support::Web::WebSocket::Client: ...>
+        #
+        # @example Creating a temporary WebSocket connection:
+        #   websocket_connect('ws://websocket-echo.com') do |websocket|
+        #     # ...
+        #   end
+        #
+        # @api public
+        #
+        def self.connect(url, ssl: {}, **kwargs)
+          client = Client.new(url, ssl: ssl, **kwargs)
+
+          if block_given?
+            yield client
+            client.close
+          else
+            client
+          end
+        end
+
+        #
+        # Connects to the WebSocket and sends the data.
+        #
+        # @param [String] data
+        #   The data to send to the WebSocet.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [:text, :binary, :ping, :pong, :close] type
+        #   The data frame type.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.connect`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Client#initialize}.
+        #
+        # @!macro client_kwargs
+        #
+        # @yield [websocket]
+        #   If a block is given, then it will be passed the WebSocket
+        #   connection. Once the block has returned, the WebSocket connection
+        #   will be closed.
+        #
+        # @yieldparam [Client] websocket
+        #   The WebSocket connection.
+        #
+        # @return [Client]
+        #   The WebSocket connection.
+        #
+        # @api public
+        #
+        def self.connect_and_send(data,url, type: :text, ssl: {}, **kwargs)
+          client = connect(url, ssl: ssl, **kwargs)
+          client.send(data, type: type)
+
+          yield client if block_given?
+          return client
+        end
+
+        #
+        # Connects to the WebSocket, sends the data, and closes the connection.
+        #
+        # @param [String] data
+        #   The data to send to the WebSocet.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [:text, :binary, :ping, :pong, :close] type
+        #   The data frame type.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.connect`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Client#initialize}.
+        #
+        # @!macro client_kwargs
+        #
+        # @return [true]
+        #
+        # @api public
+        #
+        def self.send(data,url, type: :text, ssl: {}, **kwargs)
+          connect(url, ssl: ssl, **kwargs) do |client|
+            client.send(data, type: type)
+          end
+
+          return true
+        end
+
+        # @!macro [new] server_kwargs
+        #   @option kwargs [String, nil] :bind_host
+        #     The optional host to bind the server socket to.
+        #
+        #   @option kwargs [Integer, nil] :bind_port
+        #     The optioanl port to bind the server socket to. If not
+        #     specified, it will default to the port of the URL.
+        #
+        #   @option kwargs [Integer] :backlog (5)
+        #     The maximum backlog of pending connections.
+        #
+        #   @!macro ssl_kwargs
+
+        #
+        # Starts a WebSocket server.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.server`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Server#initialize}.
+        #
+        # @!macro server_kwargs
+        #
+        # @yield [server]
+        #   If a block is given, then it will be passed the WebSocket server.
+        #   Once the block has returned, the WebSocket server will be closed.
+        #
+        # @yieldparam [Server] server
+        #   The WebSocket server.
+        #
+        # @return [Server]
+        #   The WebSocket server.
+        #
+        # @api public
+        #
+        def self.server(url, ssl: {}, **kwargs)
+          server = Server.new(url, ssl: ssl, **kwargs)
+
+          if block_given?
+            yield server
+            server.close
+          else
+            server
+          end
+        end
+
+        #
+        # Creates a new WebSocket server listening on a given host and port,
+        # accepting clients in a loop.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.server`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Server#initialize}.
+        #
+        # @!macro server_kwargs
+        #
+        # @yield [client]
+        #   The given block will be passed the newly connected WebSocket
+        #   client. After the block has finished, the WebSocket client will be
+        #   closed.
+        #
+        # @yieldparam [Server::Client] client
+        #   A newly connected WebSocket client.
+        #
+        # @return [nil]
+        #
+        # @api public
+        #
+        def self.server_loop(url, ssl: {}, **kwargs)
+          server(url, ssl: ssl, **kwargs) do |server|
+            loop do
+              client = server.accept
+
+              yield client if block_given?
+              client.close
+            end
+          end
+        end
+
+        #
+        # Opens a WebSocket server, accepts a single connection, yields it to
+        # the given block, then closes both the connection and the server.
+        #
+        # @param [String, URI::WS, URI::WSS] url
+        #   The `ws://` or `wss://` URL to connect to.
+        #
+        # @param [Hash{Symbol => Object}] ssl
+        #   Additional keyword arguments for
+        #   `Ronin::Support::Network::SSL.server`.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments for {Server#initialize}.
+        #
+        # @!macro server_kwargs
+        #
+        # @yield [client]
+        #   The given block will be passed the newly connected WebSocket
+        #   client. After the block has finished, the WebSocket client will be
+        #   closed.
+        #
+        # @yieldparam [Server::Client] client
+        #   A newly connected WebSocket client.
+        #
+        # @return [nil]
+        #
+        # @api public
+        #
+        def self.accept(url, ssl: {}, **kwargs)
+          server(url, ssl: ssl, **kwargs) do |server|
+            client = server.accept
+
+            yield client if block_given?
+            client.close
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/web/xml/mixin.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web 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-support-web 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-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/web/xml'
+
+module Ronin
+  module Support
+    module Web
+      module XML
+        #
+        # Provides helper methods for working with XML.
+        #
+        # @api public
+        #
+        module Mixin
+          #
+          # Parses the body of a document into a HTML document object.
+          #
+          # @param [String, IO] xml
+          #   The XML to parse.
+          #
+          # @yield [doc]
+          #   If a block is given, it will be passed the newly created document
+          #   object.
+          #
+          # @yieldparam [Nokogiri::XML::Document] doc
+          #   The new XML document object.
+          #
+          # @return [Nokogiri::XML::Document]
+          #   The new HTML document object.
+          #
+          # @see http://rubydoc.info/gems/nokogiri/Nokogiri/XML/Document
+          # @see XML.parse
+          #
+          def xml_parse(xml,&block)
+            XML.parse(xml,&block)
+          end
+
+          #
+          # Opens an XML file.
+          #
+          # @param [String] path
+          #   The path to the XML file.
+          #
+          # @yield [doc]
+          #   If a block is given, it will be passed the newly created document
+          #   object.
+          #
+          # @yieldparam [Nokogiri::XML::Document] doc
+          #   The new XML document object.
+          #
+          # @return [Nokogiri::XML::Document]
+          #   The parsed XML file.
+          #
+          # @example
+          #   doc = XML.open('index.xml')
+          #   # => #<Nokogiri::XML::Document:...>
+          #
+          # @see http://rubydoc.info/gems/nokogiri/Nokogiri/XML/Document
+          # @see XML.open
+          #
+          def xml_open(path,&block)
+            XML.open(path,&block)
+          end
+
+          alias open_xml xml_open
+
+          #
+          # Creates a new `Nokogiri::XML::Builder`.
+          #
+          # @yield []
+          #   The block that will be used to construct the XML document.
+          #
+          # @return [Nokogiri::XML::Builder]
+          #   The new XML builder object.
+          #
+          # @example
+          #   xml_build do
+          #     root {
+          #       foo(id: 'bar')
+          #     }
+          #   end
+          #
+          # @see http://rubydoc.info/gems/nokogiri/Nokogiri/XML/Builder
+          # @see XML.build
+          #
+          def xml_build(&block)
+            XML.build(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/web/xml.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web 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-support-web 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-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'nokogiri'
+
+module Ronin
+  module Support
+    module Web
+      #
+      # XML helper methods.
+      #
+      module XML
+        #
+        # Parses the body of a document into a HTML document object.
+        #
+        # @param [String, IO] xml
+        #   The XML to parse.
+        #
+        # @yield [doc]
+        #   If a block is given, it will be passed the newly created document
+        #   object.
+        #
+        # @yieldparam [Nokogiri::XML::Document] doc
+        #   The new XML document object.
+        #
+        # @return [Nokogiri::XML::Document]
+        #   The new HTML document object.
+        #
+        # @see http://rubydoc.info/gems/nokogiri/Nokogiri/XML/Document
+        #
+        # @api public
+        #
+        def self.parse(xml)
+          doc = Nokogiri::XML.parse(xml)
+          yield doc if block_given?
+          return doc
+        end
+
+        #
+        # Opens an XML file.
+        #
+        # @param [String] path
+        #   The path to the XML file.
+        #
+        # @yield [doc]
+        #   If a block is given, it will be passed the newly created document
+        #   object.
+        #
+        # @yieldparam [Nokogiri::XML::Document] doc
+        #   The new XML document object.
+        #
+        # @return [Nokogiri::XML::Document]
+        #   The parsed XML file.
+        #
+        # @example
+        #   doc = XML.open('data.xml')
+        #   # => #<Nokogiri::XML::Document:...>
+        #
+        # @api public
+        #
+        def self.open(path)
+          doc = Nokogiri::XML(File.open(path))
+          yield doc if block_given?
+          return doc
+        end
+
+        #
+        # Creates a new `Nokogiri::XML::Builder`.
+        #
+        # @yield []
+        #   The block that will be used to construct the XML document.
+        #
+        # @return [Nokogiri::XML::Builder]
+        #   The new XML builder object.
+        #
+        # @example
+        #   XML.build do
+        #     root {
+        #       foo(id: 'bar')
+        #     }
+        #   end
+        #
+        # @see http://rubydoc.info/gems/nokogiri/Nokogiri/XML/Builder
+        #
+        # @api public
+        #
+        def self.build(&block)
+          Nokogiri::XML::Builder.new(&block)
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/web.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web 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-support-web 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-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/web/xml'
+require 'ronin/support/web/html'
+require 'ronin/support/web/mixin'
+require 'ronin/support/web/version'
+
+module Ronin
+  module Support
+    #
+    # Top-level namespace for `ronin-support-web`.
+    #
+    # ## Example
+    #
+    #     require 'ronin/support/web'
+    #     include Ronin::Support::Web
+    #
+    #     html_parse "<html>...</html>"
+    #     # => #<Nokogiri::HTML::Document: ...>
+    #
+    module Web
+      include Mixin
+    end
+  end
+end

data/ronin-support-web.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/support/web/version'
+                  Ronin::Support::Web::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