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.

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) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/buby/implants/extension_helpers.rb', line 251

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



126
127
128
129
130
131
132
 
# File 'lib/buby/implants/extension_helpers.rb', line 126

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.

of the other overloaded #analyzeRequest methods.

@param [String, Array<byte>] request The request to be analyzed

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

Returns:

  • (IRequestInfo) —

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



30
31
32
33
34
 
# File 'lib/buby/implants/extension_helpers.rb', line 30

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

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

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.



43
44
45
46
47
 
# File 'lib/buby/implants/extension_helpers.rb', line 43

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

#buildHttpMessage(headers, body) ⇒ 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>) —

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

Returns:

  • (String) —

    The resulting full HTTP message.



94
95
96
97
98
 
# File 'lib/buby/implants/extension_helpers.rb', line 94

def buildHttpMessage(headers, body)
  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 (URL, #to_s) —

    The URL to which the request should be made.

Returns:

  • (String) —

    A request to the specified URL.



107
108
109
110
111
 
# File 'lib/buby/implants/extension_helpers.rb', line 107

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

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

Overloads:

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

    Parameters:

    • host (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 (String) —

      The HTTP service host.

    • port (Fixnum) —

      The HTTP service port.

    • use_https (Boolean) —

      Flags whether the HTTP service protocol is HTTPS or HTTP.

Returns:

  • (IHttpService) —

    object based on the details provided.



211
212
213
214
 
# File 'lib/buby/implants/extension_helpers.rb', line 211

def buildHttpService(host, port, protocol)
  pp [:got_buildHttpService, host, port, protocol] if $DEBUG
  Buby::Implants::HttpService.implant(__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.



224
225
226
227
 
# File 'lib/buby/implants/extension_helpers.rb', line 224

def buildParameter(name, value, type)
  pp [:got_buildParameter, name, value, type] if $DEBUG
  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. Note: Use #analyzeRequest to obtain details of all parameters within the request.

Parameters:

  • request (String, Array<byte>) —

    The request to be inspected for the specified parameter.

  • parameter_name (String) —

    The name of the parameter to retrieve.

Returns:

  • (IParameter) —

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



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

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

#indexOf(data, pattern, case_sensitive, from, to) ⇒ Object

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:

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



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

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.



241
242
243
244
245
246
 
# File 'lib/buby/implants/extension_helpers.rb', line 241

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.kind_of? Java::Burp::IHttpRequestResponse
  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.



147
148
149
150
151
152
153
 
# File 'lib/buby/implants/extension_helpers.rb', line 147

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.



191
192
193
194
195
196
 
# File 'lib/buby/implants/extension_helpers.rb', line 191

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.



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

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