Module: Buby::Implants::ExtensionHelpers

Defined in:
lib/buby/implants/extension_helpers.rb

Overview

This interface contains a number of helper methods, which extensions can use to assist with various common tasks that arise for Burp extensions.

Extensions can call IBurpExtenderCallbacks.getHelpers() to obtain an instance of this interface. This module is used to extend the JRuby proxy class returned by Burp.

Constant Summary collapse

PARAM_TYPES = 
{
  'url' => 0,
  'body' => 1,
  'cookie' => 2,
  'xml' => 3,
  'xml_attr' => 4,
  'multipart_attr' => 5,
  'json' => 6
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.implant(helpers) ⇒ Object

Install ourselves into the current IExtensionHelpers java class

Parameters:

  • helpers (IExtensionHelpers) 


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
 
# File 'lib/buby/implants/extension_helpers.rb', line 304

def self.implant(helpers)
  unless helpers.implanted? || helpers.nil?
    pp [:implanting, helpers, helpers.class] if $DEBUG
    helpers.class.class_exec(helpers) do |helpers|
      a_methods = %w{
        analyzeRequest
        analyzeResponse
        getRequestParameter
        indexOf
        buildHttpMessage
        buildHttpRequest
        addParameter
        removeParameter
        updateParameter
        toggleRequestMethod
        buildParameter
        makeScannerInsertionPoint
      }
      a_methods.each do |meth|
        alias_method "__"+meth.to_s, meth
      end
      include Buby::Implants::ExtensionHelpers
      a_methods.each do |meth|
        java_class.ruby_names_for_java_method(meth).each do |ruby_meth|
          define_method ruby_meth, Buby::Implants::ExtensionHelpers.instance_method(meth)
        end
      end
      include Buby::Implants::Proxy
    end
  end
  helpers
end

Instance Method Details

#addParameter(request, parameter) ⇒ String

TODO:

Switch IHttpRequestResponse to new Buby::Implants functionality (2.0)

This method adds a new parameter to an HTTP request, and if appropriate updates the Content-Length header.

Parameters:

  • request (String, Array<byte>, IHttpRequestResponse) —

    The request to which the parameter should be added.

  • parameter (IParameter, Hash) —

    An IParameter object containing details of the parameter to be added. Supported parameter types are:

    • PARAM_URL

    • PARAM_BODY

    • PARAM_COOKIE

Returns:

  • (String) —

    A new HTTP request with the new parameter added.



153
154
155
156
157
158
159
 
# File 'lib/buby/implants/extension_helpers.rb', line 153

def addParameter(request, parameter)
  pp [:got_addParameter, parameter, request] if $DEBUG
  request = request.request if request.kind_of? Java::Burp::IHttpRequestResponse
  request = request.to_java_bytes if request.respond_to? :to_java_bytes
  parameter = Buby::Parameter::Base.new parameter if parameter.kind_of? Hash
  String.from_java_bytes(__addParameter(request, parameter))
end

#analyzeRequest(request) ⇒ IRequestInfo #analyzeRequest(httpService, request) ⇒ IRequestInfo #analyzeRequest(request) ⇒ IRequestInfo

This method can be used to analyze an HTTP request, and obtain various key details about it. The resulting IRequestInfo object will not include the full request URL.

Overloads:

  • #analyzeRequest(request) ⇒ IRequestInfo

    Analyze a HttpRequestResponse object.

    Parameters:

    • request (IHttpRequestResponse) —

      The request to be analyzed.

  • #analyzeRequest(httpService, request) ⇒ IRequestInfo

    Analyze a request from a HttpService object, and a String or

    +byte[]+.

    Parameters:

    • http_service (IHttpService) —

      HTTP service description

    • request (String, Array<byte>) —

      The request to be analyzed

  • #analyzeRequest(request) ⇒ IRequestInfo

    Analyze a String or byte[] request. To obtain the full URL, use

    one of the other overloaded {#analyzeRequest} methods.

    Parameters:

    • request (String, Array<byte>) —

      The request to be analyzed

Returns:

  • (IRequestInfo) —

    object (wrapped with Ruby goodness) that can be queried to obtain details about the request.



41
42
43
44
45
 
# File 'lib/buby/implants/extension_helpers.rb', line 41

def analyzeRequest(*args)
  pp [:got_analyze_request, *args] if $DEBUG
  args[-1] = args[-1].to_java_bytes if args[-1].respond_to? :to_java_bytes
  Buby::Implants::RequestInfo.implant(__analyzeRequest(*args))
end

#analyzeResponse(response) ⇒ IResponseInfo #analyzeResponse(response) ⇒ IResponseInfo?

This method can be used to analyze an HTTP response, and obtain various key details about it.

Overloads:

  • #analyzeResponse(response) ⇒ IResponseInfo

    Returns object (wrapped with Ruby goodness) that can be queried to obtain details about the response.

    Parameters:

    • response (String, Array<byte>) —

      The response to be analyzed.

    Returns:

    • (IResponseInfo) —

      object (wrapped with Ruby goodness) that can be queried to obtain details about the response.

  • #analyzeResponse(response) ⇒ IResponseInfo?

    Returns Object (wrapped with Ruby goodness) that can be queried to obtain details about the response. Returns nil when response is nil.

    Parameters:

    • response (IHttpRequestResponse) —

      The response to be analyzed.

    Returns:

    • (IResponseInfo, nil) —

      Object (wrapped with Ruby goodness) that can be queried to obtain details about the response. Returns nil when response is nil.



60
61
62
63
64
65
 
# File 'lib/buby/implants/extension_helpers.rb', line 60

def analyzeResponse(response)
  pp [:got_analyze_response, response] if $DEBUG
  response = response.response if response.respond_to? :response
  response = response.to_java_bytes if response.respond_to? :to_java_bytes
  Buby::Implants::ResponseInfo.implant(__analyzeResponse(response)) if response
end

#buildHttpMessage(headers, body = nil) ⇒ String

This method builds an HTTP message containing the specified headers and message body. If applicable, the Content-Length header will be added or updated, based on the length of the body.

Parameters:

  • headers (Array<String>) —

    A list of headers to include in the message.

  • body (String, Array<byte>) (defaults to: nil) —

    The body of the message, or nil if the message has an empty body.

Returns:

  • (String) —

    The resulting full HTTP message.



120
121
122
123
124
 
# File 'lib/buby/implants/extension_helpers.rb', line 120

def buildHttpMessage(headers, body = nil)
  pp [:got_build_http_message, headers, body] if $DEBUG
  body = body.to_java_bytes if body.respond_to?(:to_java_bytes)
  String.from_java_bytes(__buildHttpMessage(headers, body))
end

#buildHttpRequest(url) ⇒ String

This method creates a GET request to the specified URL. The headers used in the request are determined by the Request headers settings as configured in Burp Spider’s options.

Parameters:

  • url (java.net.URL, URI, #to_s) —

    The URL to which the request should be built.

Returns:

  • (String) —

    A request to the specified URL.



134
135
136
137
138
 
# File 'lib/buby/implants/extension_helpers.rb', line 134

def buildHttpRequest(url)
  pp [:got_build_http_request, url] if $DEBUG
  url = Java::JavaNet::URL.new url.to_s unless url.kind_of?(Java::JavaNet::URL)
  String.from_java_bytes __buildHttpRequest(url)
end

#buildHttpService(host, port, protocol) ⇒ IHttpService #buildHttpService(host, port, use_https) ⇒ IHttpService #buildHttpService(url) ⇒ IHttpService

This method constructs an IHttpService object based on the details provided.

Overloads:

  • #buildHttpService(host, port, protocol) ⇒ IHttpService

    Parameters:

    • host (Java::JavaNet::URL, URI, String) —

      The HTTP service host.

    • port (Fixnum) —

      The HTTP service port.

    • protocol (String) —

      The HTTP service protocol.

  • #buildHttpService(host, port, use_https) ⇒ IHttpService

    Parameters:

    • host (Java::JavaNet::URL, URI, String) —

      The HTTP service host.

    • port (Fixnum) —

      The HTTP service port.

    • use_https (Boolean) —

      Flags whether the HTTP service protocol is HTTPS or HTTP.

  • #buildHttpService(url) ⇒ IHttpService

    Parameters:

    • url (Java::JavaNet::URL, URI, String) —

      URL specifying host, port and protocol. Will automatically set port to 80/443 if http(s) url is passed. Defaults to 80 for other URL schemes.

Returns:

  • (IHttpService) —

    object based on the details provided.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/buby/implants/extension_helpers.rb', line 242

def buildHttpService(host, *args)
  pp [:got_buildHttpService, host, *args] if $DEBUG
  port, protocol = *args
  case host
  when URI, Java::JavaNet::URL
    port ||= host.port
    protocol ||= host.protocol
    host = host.host
  else
    thost = host.kind_of?(String) ? Java::JavaNet::URL.new(host) : host
    port ||= thost.port
    protocol ||= thost.protocol
  end
  port ||= case protocol
  when TrueClass, /^https$/i
    443
  else
    80
  end

  port = https ? 443 : 80 if port < 0
  host = host.host if host.respond_to? :host

  __buildHttpService(host, port, protocol)
end

#buildParameter(name, value, type) ⇒ IParameter

This method constructs an IParameter object based on the details

provided.

Parameters:

  • name (String) —

    The parameter name.

  • value (String) —

    The parameter value.

  • type (Fixnum) —

    The parameter type, as defined in the IParameter interface.

Returns:

  • (IParameter) —

    object based on the details provided.



276
277
278
279
280
 
# File 'lib/buby/implants/extension_helpers.rb', line 276

def buildParameter(name, value, type)
  pp [:got_buildParameter, name, value, type] if $DEBUG
  ptype = TYPE_HASH[ptype.to_s] unless ptype.kind_of?(Fixnum)
  Buby::Implants::Parameter.implant(__buildParameter(name, value, type))
end

#getRequestParameter(request, parameter_name) ⇒ IParameter?

This method can be used to retrieve details of a specified parameter within an HTTP request. Use #analyzeRequest to obtain details of all parameters within the request.

Parameters:

  • request (IHttpRequestResponse, String, Array<byte>) —

    The request to be inspected for the specified parameter.

  • parameter_name (#to_s) —

    The name of the parameter to retrieve.

Returns:

  • (IParameter, nil) —

    object that can be queried to obtain details about the parameter, or nil if the parameter was not found.



77
78
79
80
81
82
 
# File 'lib/buby/implants/extension_helpers.rb', line 77

def getRequestParameter(request, parameter_name)
  pp [:got_get_request_parameter, parameter_name, request] if $DEBUG
  request = request.request if request.kind_of?(Java::Burp::IHttpRequestResponse)
  request = request.to_java_bytes if request.respond_to? :to_java_bytes
  Buby::Implants::Parameter.implant(__getRequestParameter(request, parameter_name.to_s))
end

#indexOf(data, pattern, case_sensitive, from, to) ⇒ Fixnum?

Note:

This method is only wrapped for testing purposes. There are better ways to do this in the JRuby runtime.

This method searches a piece of data for the first occurrence of a specified pattern. It works on byte-based data in a way that is similar to the way the native Java method String.indexOf() works on String-based data.

Parameters:

  • data (String, Array<byte>) —

    The data to be searched.

  • pattern (String, Array<byte>) —

    The pattern to be searched for.

  • case_sensitive (Boolean) —

    Flags whether or not the search is case-sensitive.

  • from (Fixnum) —

    The offset within data where the search should begin.

  • to (Fixnum) —

    The offset within data where the search should end.

Returns:

  • (Fixnum, nil) —

    The offset of the first occurrence of the pattern within the specified bounds, or nil if no match is found.



102
103
104
105
106
107
108
 
# File 'lib/buby/implants/extension_helpers.rb', line 102

def indexOf(data, pattern, case_sensitive, from, to)
  pp [:got_index_of, case_sensitive, from, to, data, pattern] if $DEBUG
  data = data.to_java_bytes if data.respond_to?(:to_java_bytes)
  pattern = pattern.to_java_bytes if data.respond_to?(:to_java_bytes)
  ret = __indexOf(data, pattern, case_sensitive, from, to)
  ret == -1 ? nil : ret
end

#makeScannerInsertionPoint(insertion_point_name, base_request, from, to) ⇒ IScannerInsertionPoint

TODO:

Switch IHttpRequestResponse to new Buby::Implants functionality (2.0)

This method constructs an IScannerInsertionPoint object based on the

details provided. It can be used to quickly create a simple insertion
point based on a fixed payload location within a base request.

Parameters:

  • insertion_point_name (String) —

    The name of the insertion point.

  • base_request (String, Array<byte>, IHttpRequestResponse) —

    The request from which to build scan requests.

  • from (Fixnum) —

    The offset of the start of the payload location.

  • to (Fixnum) —

    The offset of the end of the payload location.

Returns:

  • (IScannerInsertionPoint) —

    object based on the details provided.



294
295
296
297
298
299
 
# File 'lib/buby/implants/extension_helpers.rb', line 294

def makeScannerInsertionPoint(insertion_point_name, base_request, from, to)
  pp [:got_makeScannerInsertionPoint, insertion_point_name, base_request, from, to] if $DEBUG
  base_request = base_request.request if base_request.respond_to? :request
  base_request = base_request.to_java_bytes if base_request.respond_to? :to_java_bytes
  Buby::Implants::ScannerInsertionPoint.implant(__makeScannerInsertionPoint(insertion_point_name, base_request, from, to))
end

#removeParameter(request, parameter) ⇒ String

TODO:

Switch IHttpRequestResponse to new Buby::Implants functionality (2.0)

This method removes a parameter from an HTTP request, and if appropriate updates the Content-Length header.

Parameters:

  • request (String, Array<byte>, IHttpRequestResponse) —

    The request from which the parameter should be removed.

  • parameter (IParameter, Hash) —

    Object containing details of the parameter to be removed. Supported parameter types are:

    • PARAM_URL

    • PARAM_BODY

    • PARAM_COOKIE

Returns:

  • (String) —

    A new HTTP request with the parameter removed.



174
175
176
177
178
179
180
 
# File 'lib/buby/implants/extension_helpers.rb', line 174

def removeParameter(request, parameter);
  pp [:got_addParameter, parameter, request] if $DEBUG
  request = request.request if request.kind_of? Java::Burp::IHttpRequestResponse
  request = request.to_java_bytes if request.respond_to? :to_java_bytes
  parameter = Buby::Parameter::Base.new parameter if parameter.kind_of? Hash
  String.from_java_bytes(__removeParameter(request, parameter))
end

#toggleRequestMethod(request) ⇒ String

TODO:

Switch IHttpRequestResponse to new Buby::Implants functionality (2.0)

This method can be used to toggle a request’s method between GET and POST. Parameters are relocated between the URL query string and message body as required, and the Content-Length header is created or removed as applicable.

Parameters:

  • request (String, Array<byte>, IHttpRequestResponse) —

    The HTTP request whose method should be toggled.

Returns:

  • (String) —

    A new HTTP request using the toggled method.



218
219
220
221
222
223
 
# File 'lib/buby/implants/extension_helpers.rb', line 218

def toggleRequestMethod(request)
  pp [:got_toggleRequestMethod, request] if $DEBUG
  request = request.request if request.kind_of? Java::Burp::IHttpRequestResponse
  request = request.to_java_bytes if request.respond_to? :to_java_bytes
  String.from_java_bytes(__toggleRequestMethod(request))
end

#updateParameter(request, parameter) ⇒ String

TODO:

Switch IHttpRequestResponse to new Buby::Implants functionality (2.0)

This method updates the value of a parameter within an HTTP request, and if appropriate updates the Content-Length header. @note: This method can only be used to update the value of an existing

parameter of a specified type. If you need to change the type of an
existing parameter, you should first call {#removeParameter} to remove
the parameter with the old type, and then call {#addParameter} to add
a parameter with the new type.

Parameters:

  • request (String, Array<byte>, IHttpRequestResponse) —

    The request containing the parameter to be updated.

  • parameter (IParameter, Hash) —

    Object containing details of the parameter to be updated. Supported parameter types are:

    • PARAM_URL

    • PARAM_BODY

    • PARAM_COOKIE

Returns:

  • (String) —

    A new HTTP request with the parameter updated.



200
201
202
203
204
205
206
 
# File 'lib/buby/implants/extension_helpers.rb', line 200

def updateParameter(request, parameter)
  pp [:got_updateParameter, parameter, request] if $DEBUG
  request = request.request if request.kind_of? Java::Burp::IHttpRequestResponse
  request = request.to_java_bytes if request.respond_to? :to_java_bytes
  parameter = Buby::Parameter::Base.new parameter if parameter.kind_of? Hash
  String.from_java_bytes(__updateParameter(request, parameter))
end