Module: Ronin::Network::HTTP

Included in:
Net, Mixins::HTTP, Support, URI::HTTP
Defined in:
lib/ronin/network/http/http.rb,
lib/ronin/network/http/proxy.rb,
lib/ronin/network/http/exceptions/unknown_request.rb

Overview

Provides helper methods for communicating with HTTP Servers.

Defined Under Namespace

Classes: Proxy, UnknownRequest

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.expand_options(options = {}) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Expands the given HTTP options.

Options Hash (options):

  • :url (String, URI::HTTP, URI::HTTPS)

    The URL to request.

  • :host (String)

    The host to connect to.

  • :port (String) — default: Net::HTTP.default_port

    The port to connect to.

  • :user (String)

    The user to authenticate as.

  • :password (String)

    The password to authenticate with.

  • :path (String) — default: '/'

    The path to request.

  • :proxy (String, Hash) — default: HTTP.proxy

    The Proxy information.


171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
# File 'lib/ronin/network/http/http.rb', line 171

def self.expand_options(options={})
  new_options = options.dup

  new_options[:port] ||= Net::HTTP.default_port
  new_options[:path] ||= '/'

  if new_options[:ssl] == true
    new_options[:ssl] = {}
  end

  if (url = new_options.delete(:url))
    new_options.merge!(HTTP.expand_url(url))
  end

  new_options[:proxy] = if new_options.has_key?(:proxy)
                          HTTP::Proxy.create(new_options[:proxy])
                        else
                          HTTP.proxy
                        end

  return new_options
end

.expand_url(url) ⇒ Hash{Symbol => Object}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Expands the URL into options.


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
# File 'lib/ronin/network/http/http.rb', line 116

def self.expand_url(url)
  new_options = {}

  url = case url
        when URI  then url
        when Hash then URI::HTTP.build(url)
        else           URI(url.to_s)
        end

  new_options[:ssl] = {} if url.scheme == 'https'

  new_options[:host] = url.host
  new_options[:port] = url.port

  new_options[:user]     = url.user     if url.user
  new_options[:password] = url.password if url.password

  new_options[:path] = url.path  unless url.path.empty?
  new_options[:query] = url.query unless url.query.nil?

  return new_options
end

.header_name(name) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts an underscored, dashed, lowercase or uppercase HTTP header name to the standard camel-case HTTP header name.


206
207
208
209
210
211
# File 'lib/ronin/network/http/http.rb', line 206

def self.header_name(name)
  words = name.to_s.split(/[\s+_-]/)

  words.each { |word| word.capitalize! }
  return words.join('-')
end

.headers(options = {}) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts underscored, dashed, lowercase and uppercase HTTP headers to standard camel-cased HTTP headers.


225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
# File 'lib/ronin/network/http/http.rb', line 225

def self.headers(options={})
  headers = {}

  if user_agent
    headers['User-Agent'] = user_agent
  end

  if options
    options.each do |name,value|
      headers[HTTP.header_name(name)] = value.to_s
    end
  end

  return headers
end

.proxyProxy

Note:

If the HTTP_PROXY environment variable is specified, it will be used as the default value.

The Ronin HTTP proxy to use.

See Also:


54
55
56
57
58
59
60
# File 'lib/ronin/network/http/http.rb', line 54

def self.proxy
  @proxy ||= if ENV['HTTP_PROXY']
               Proxy.parse(ENV['HTTP_PROXY'])
             else
               Proxy.new
             end
end

.proxy=(new_proxy) ⇒ Proxy

Sets the Ronin HTTP proxy to use.

Raises:

  • (ArgumentError)

    The given proxy information was not a Proxy, URI::HTTP, Hash or String.


77
78
79
# File 'lib/ronin/network/http/http.rb', line 77

def self.proxy=(new_proxy)
  @proxy = Proxy.create(new_proxy)
end

.request(options = {}) ⇒ HTTP::Request

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a specific type of HTTP request object.

Options Hash (options):

  • :method (Symbol, String)

    The HTTP method to use for the request.

  • :path (String) — default: '/'

    The path to request.

  • :query (String)

    The query-string to append to the request path.

  • :query_params (String)

    The query-params to append to the request path.

  • :body (String)

    The body of the request.

  • :form_data (Hash, String)

    The form data that may be sent in the body of the request.

  • :user (String)

    The user to authenticate as.

  • :password (String)

    The password to authenticate with.

  • :headers (Hash{Symbol,String => String})

    Additional HTTP headers to use for the request.

Raises:

  • (ArgumentError)

    The :method option must be specified.

  • (UnknownRequest)

    The :method option did not match a known Net::HTTP request class.

See Also:


288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
# File 'lib/ronin/network/http/http.rb', line 288

def self.request(options={})
  unless options[:method]
    raise(ArgumentError,"the :method option must be specified")
  end

  name = options[:method].to_s.capitalize

  unless Net::HTTP.const_defined?(name)
    raise(UnknownRequest,"unknown HTTP request type #{name.dump}")
  end

  headers = headers(options[:headers])
  path    = (options[:path] || '/').to_s
  query   = if options[:query]
              options[:query].to_s
            elsif options[:query_params]
              URI::QueryParams.dump(options[:query_params])
            end

  if query
    # append the query-string onto the path
    path += if path.include?('?') then "&#{query}"
            else                       "?#{query}"
            end
  end

  request = Net::HTTP.const_get(name).new(path,headers)

  if options[:form_data]
    case options[:form_data]
    when String
      request.content_type = 'application/x-www-form-urlencoded'
      request.body         = options[:form_data]
    else
      request.form_data = options[:form_data]
    end
  elsif options[:body]
    request.body = options[:body]
  end

  if options[:user]
    user     = options[:user].to_s
    password = if options[:password]
                 options[:password].to_s
               end

    request.basic_auth(user,password)
  end

  return request
end

.user_agentString?

The default Ronin HTTP User-Agent string.


89
90
91
# File 'lib/ronin/network/http/http.rb', line 89

def self.user_agent
  @user_agent ||= nil
end

.user_agent=(agent) ⇒ Object

Sets the default Ronin HTTP User-Agent string.


101
102
103
# File 'lib/ronin/network/http/http.rb', line 101

def self.user_agent=(agent)
  @user_agent = agent
end

Instance Method Details

#http_connect(options = {}) {|http| ... } ⇒ Net::HTTP

Starts a HTTP connection with the server.

Options Hash (options):

  • :url (String, URI::HTTP)

    The full URL to request.

  • :host (String)

    The host the HTTP server is running on.

  • :port (Integer) — default: Net::HTTP.default_port

    The port the HTTP server is listening on.

  • :proxy (String, Hash) — default: HTTP.proxy

    A Hash of proxy settings to use when connecting to the HTTP server.

  • :user (String)

    The user to authenticate with when connecting to the HTTP server.

  • :password (String)

    The password to authenticate with when connecting to the HTTP server.

  • :ssl (Boolean, Hash)

    Enables SSL for the HTTP connection.

Yields:

  • (http)

    If a block is given, it will be passed the newly created HTTP session object.

Yield Parameters:

  • http (Net::HTTP)

    The newly created HTTP session.


382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
# File 'lib/ronin/network/http/http.rb', line 382

def http_connect(options={},&block)
  options = HTTP.expand_options(options)

  host  = options[:host].to_s
  port  = options[:port]
  proxy = options[:proxy]
  proxy_host = if (proxy && proxy[:host])
                 proxy[:host].to_s
               end

  http = Net::HTTP::Proxy(
    proxy_host,
    proxy[:port],
    proxy[:user],
    proxy[:password]
  ).new(host,port)

  if options[:ssl]
    http.use_ssl     = true
    http.verify_mode = SSL::VERIFY[options[:ssl][:verify]]
  end

  http.start()

  if block
    if block.arity == 2
      block.call(http,options)
    else
      block.call(http)
    end
  end

  return http
end

#http_copy(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Copy request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


644
645
646
647
648
649
# File 'lib/ronin/network/http/http.rb', line 644

def http_copy(options={})
  response = http_request(options.merge(:method => :copy))

  yield response if block_given?
  return response
end

#http_delete(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Delete request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
# File 'lib/ronin/network/http/http.rb', line 671

def http_delete(options={},&block)
  original_headers = options[:headers]

  # set the HTTP Depth header
  options[:headers] = {:depth => 'Infinity'}

  if original_headers
    options[:header].merge!(original_headers)
  end

  response = http_request(options.merge(:method => :delete))

  yield response if block_given?
  return response
end

#http_get(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Get request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


707
708
709
710
711
712
# File 'lib/ronin/network/http/http.rb', line 707

def http_get(options={},&block)
  response = http_request(options.merge(:method => :get))

  yield response if block_given?
  return response
end

#http_get_body(options = {}) ⇒ String

Performs an HTTP Get request and returns the Respond Body.

See Also:


752
753
754
# File 'lib/ronin/network/http/http.rb', line 752

def http_get_body(options={})
  http_get(options).body
end

#http_get_headers(options = {}) ⇒ Hash{String => Array<String>}

Performs an HTTP Get request and returns the Response Headers.

See Also:

Since:

  • 0.2.0


729
730
731
732
733
734
735
736
737
# File 'lib/ronin/network/http/http.rb', line 729

def http_get_headers(options={})
  headers = {}

  http_get(options).each_header do |name,value|
    headers[HTTP.header_name(name)] = value
  end

  return headers
end

#http_head(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Head request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


776
777
778
779
780
781
# File 'lib/ronin/network/http/http.rb', line 776

def http_head(options={},&block)
  response = http_request(options.merge(:method => :head))

  yield response if block_given?
  return response
end

#http_lock(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Lock request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


803
804
805
806
807
808
# File 'lib/ronin/network/http/http.rb', line 803

def http_lock(options={},&block)
  response = http_request(options.merge(:method => :lock))

  yield response if block_given?
  return response
end

#http_mkcol(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Mkcol request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


830
831
832
833
834
835
# File 'lib/ronin/network/http/http.rb', line 830

def http_mkcol(options={},&block)
  response = http_request(options.merge(:method => :mkcol))

  yield response if block_given?
  return response
end

#http_move(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Move request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


857
858
859
860
861
862
# File 'lib/ronin/network/http/http.rb', line 857

def http_move(options={},&block)
  response = http_request(options.merge(:method => :move))

  yield response if block_given?
  return response
end

#http_ok?(options = {}) ⇒ Boolean

Checks if the response has an HTTP OK status code.

Options Hash (options):

  • :method (Symbol, String) — default: :head

    The method to use for the request.

See Also:


576
577
578
# File 'lib/ronin/network/http/http.rb', line 576

def http_ok?(options={})
  http_status(options) == 200
end

#http_options(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Options request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


884
885
886
887
888
889
# File 'lib/ronin/network/http/http.rb', line 884

def http_options(options={},&block)
  response = http_request(options.merge(:method => :options))

  yield response if block_given?
  return response
end

#http_post(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Post request.

Options Hash (options):

  • :form_data (Hash, String)

    The form data to send with the HTTP Post request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


914
915
916
917
918
919
# File 'lib/ronin/network/http/http.rb', line 914

def http_post(options={},&block)
  response = http_request(options.merge(:method => :post))

  yield response if block_given?
  return response
end

#http_post_body(options = {}) ⇒ String

Performs an HTTP Post request and returns the Response Body.

Options Hash (options):

  • :form_data (Hash, String)

    The form data to send with the HTTP Post request.

See Also:


965
966
967
# File 'lib/ronin/network/http/http.rb', line 965

def http_post_body(options={})
  http_post(options).body
end

#http_post_headers(options = {}) ⇒ Hash{String => Array<String>}

Performs an HTTP Post request and returns the Response Headers.

Options Hash (options):

  • :form_data (Hash, String)

    The form data to send with the HTTP Post request.

See Also:

Since:

  • 0.2.0


939
940
941
942
943
944
945
946
947
# File 'lib/ronin/network/http/http.rb', line 939

def http_post_headers(options={})
  headers = {}

  http_post(options).each_header do |name,value|
    headers[HTTP.header_name(name)] = value
  end

  return headers
end

#http_powered_by(options = {}) ⇒ String

Sends an HTTP Head request and returns the HTTP X-Powered-By header.

Options Hash (options):

  • :method (Symbol, String) — default: :get

    The method to use for the request.

See Also:


618
619
620
621
622
# File 'lib/ronin/network/http/http.rb', line 618

def http_powered_by(options={})
  options = {:method => :get}.merge(options)

  return http_request(options)['x-powered-by']
end

#http_prop_find(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Propfind request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
# File 'lib/ronin/network/http/http.rb', line 1024

def http_prop_find(options={},&block)
  original_headers = options[:headers]

  # set the HTTP Depth header
  options[:headers] = {:depth => '0'}

  if original_headers
    options[:header].merge!(original_headers)
  end

  response = http_request(options.merge(:method => :propfind))

  yield response if block_given?
  return response
end

#http_prop_patch(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Proppatch request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


1060
1061
1062
1063
1064
1065
# File 'lib/ronin/network/http/http.rb', line 1060

def http_prop_patch(options={},&block)
  response = http_request(options.merge(:method => :proppatch))

  yield response if block_given?
  return response
end

#http_put(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP PUT request.

Options Hash (options):

  • :body (String)

    The body for the request.

  • :form_data (Hash, String)

    The form data to send with the HTTP PUT request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:

Since:

  • 0.4.0


997
998
999
1000
1001
1002
# File 'lib/ronin/network/http/http.rb', line 997

def http_put(options={})
  response = http_request(options.merge(:method => :put))

  yield response if block_given?
  return response
end

#http_request(options = {}) {|request, (options)| ... } ⇒ Net::HTTPResponse

Connects to the HTTP server and sends an HTTP Request.

Options Hash (options):

  • :method (Symbol, String)

    The HTTP method to use in the request.

  • :path (String)

    The path to request from the HTTP server.

  • :headers (Hash)

    The Hash of the HTTP headers to send with the request. May contain either Strings or Symbols, lower-case or camel-case keys.

  • :body (String)

    The body of the request.

  • :form_data (Hash, String)

    The form data that may be sent in the body of the request.

Yields:

  • (request, (options))

    If a block is given, it will be passed the HTTP request object. If the block has an arity of 2, it will also be passed the expanded version of the given options.

Yield Parameters:

  • request (Net::HTTPRequest)

    The HTTP request object to use in the request.

  • options (Hash)

    The expanded version of the given options.

See Also:


516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
# File 'lib/ronin/network/http/http.rb', line 516

def http_request(options={},&block)
  response = nil

  http_session(options) do |http,expanded_options|
    req = HTTP.request(expanded_options)

    if block
      if block.arity == 2
        block.call(req,expanded_options)
      else
        block.call(req)
      end
    end

    response = http.request(req)
  end

  return response
end

#http_server(options = {}) ⇒ String

Sends a HTTP Head request and returns the HTTP Server header.

Options Hash (options):

  • :method (Symbol, String) — default: :head

    The method to use for the request.

See Also:


596
597
598
599
600
# File 'lib/ronin/network/http/http.rb', line 596

def http_server(options={})
  options = {:method => :head}.merge(options)

  return http_request(options)['server']
end

#http_session(options = {}) {|http| ... } ⇒ nil

Creates a new temporary HTTP session with the server.

Options Hash (options):

  • :url (String, URI::HTTP)

    The full URL to request.

  • :host (String)

    The host the HTTP server is running on.

  • :port (Integer) — default: Net::HTTP.default_port

    The port the HTTP server is listening on.

  • :user (String)

    The user to authenticate with when connecting to the HTTP server.

  • :password (String)

    The password to authenticate with when connecting to the HTTP server.

  • :proxy (String, Hash) — default: HTTP.proxy

    A Hash of proxy settings to use when connecting to the HTTP server.

  • :ssl (Boolean, Hash)

    Enables SSL for the HTTP connection.

Yields:

  • (http)

    If a block is given, it will be passed the newly created HTTP session object.

Yield Parameters:

  • http (Net::HTTP)

    The newly created HTTP session.

See Also:


460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
# File 'lib/ronin/network/http/http.rb', line 460

def http_session(options={},&block)
  http_connect(options) do |http,expanded_options|
    if block
      if block.arity == 2
        block.call(http,expanded_options)
      else
        block.call(http)
      end
    end

    http.finish
  end

  return nil
end

#http_status(options = {}) ⇒ Integer

Returns the Status Code of the Response.

Options Hash (options):

  • :method (Symbol, String) — default: :head

    The method to use for the request.

See Also:

Since:

  • 0.2.0


554
555
556
557
558
# File 'lib/ronin/network/http/http.rb', line 554

def http_status(options={})
  options = {:method => :head}.merge(options)

  return http_request(options).code.to_i
end

#http_trace(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Trace request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


1087
1088
1089
1090
1091
1092
# File 'lib/ronin/network/http/http.rb', line 1087

def http_trace(options={},&block)
  response = http_request(options.merge(:method => :trace))

  yield response if block_given?
  return response
end

#http_unlock(options = {}) {|response| ... } ⇒ Net::HTTPResponse

Performs an HTTP Unlock request.

Yields:

  • (response)

    If a block is given, it will be passed the response received from the request.

Yield Parameters:

  • response (Net::HTTPResponse)

    The HTTP response object.

See Also:


1114
1115
1116
1117
1118
1119
# File 'lib/ronin/network/http/http.rb', line 1114

def http_unlock(options={},&block)
  response = http_request(options.merge(:method => :unlock))

  yield response if block_given?
  return response
end