368 lines
14 KiB
Java
368 lines
14 KiB
Java
package burp;
|
|
|
|
/*
|
|
* @(#)IExtensionHelpers.java
|
|
*
|
|
* Copyright PortSwigger Ltd. All rights reserved.
|
|
*
|
|
* This code may be used to extend the functionality of Burp Suite Community Edition
|
|
* and Burp Suite Professional, provided that this usage does not violate the
|
|
* license terms for those products.
|
|
*/
|
|
import java.net.URL;
|
|
import java.util.List;
|
|
|
|
/**
|
|
* 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 <code>IBurpExtenderCallbacks.getHelpers</code> to obtain
|
|
* an instance of this interface.
|
|
*/
|
|
public interface IExtensionHelpers
|
|
{
|
|
|
|
/**
|
|
* This method can be used to analyze an HTTP request, and obtain various
|
|
* key details about it.
|
|
*
|
|
* @param request An <code>IHttpRequestResponse</code> object containing the
|
|
* request to be analyzed.
|
|
* @return An <code>IRequestInfo</code> object that can be queried to obtain
|
|
* details about the request.
|
|
*/
|
|
IRequestInfo analyzeRequest(IHttpRequestResponse request);
|
|
|
|
/**
|
|
* This method can be used to analyze an HTTP request, and obtain various
|
|
* key details about it.
|
|
*
|
|
* @param httpService The HTTP service associated with the request. This is
|
|
* optional and may be <code>null</code>, in which case the resulting
|
|
* <code>IRequestInfo</code> object will not include the full request URL.
|
|
* @param request The request to be analyzed.
|
|
* @return An <code>IRequestInfo</code> object that can be queried to obtain
|
|
* details about the request.
|
|
*/
|
|
IRequestInfo analyzeRequest(IHttpService httpService, byte[] request);
|
|
|
|
/**
|
|
* This method can be used to analyze an HTTP request, and obtain various
|
|
* key details about it. The resulting <code>IRequestInfo</code> object will
|
|
* not include the full request URL. To obtain the full URL, use one of the
|
|
* other overloaded <code>analyzeRequest()</code> methods.
|
|
*
|
|
* @param request The request to be analyzed.
|
|
* @return An <code>IRequestInfo</code> object that can be queried to obtain
|
|
* details about the request.
|
|
*/
|
|
IRequestInfo analyzeRequest(byte[] request);
|
|
|
|
/**
|
|
* This method can be used to analyze an HTTP response, and obtain various
|
|
* key details about it.
|
|
*
|
|
* @param response The response to be analyzed.
|
|
* @return An <code>IResponseInfo</code> object that can be queried to
|
|
* obtain details about the response.
|
|
*/
|
|
IResponseInfo analyzeResponse(byte[] response);
|
|
|
|
/**
|
|
* This method can be used to retrieve details of a specified parameter
|
|
* within an HTTP request. <b>Note:</b> Use <code>analyzeRequest()</code> to
|
|
* obtain details of all parameters within the request.
|
|
*
|
|
* @param request The request to be inspected for the specified parameter.
|
|
* @param parameterName The name of the parameter to retrieve.
|
|
* @return An <code>IParameter</code> object that can be queried to obtain
|
|
* details about the parameter, or <code>null</code> if the parameter was
|
|
* not found.
|
|
*/
|
|
IParameter getRequestParameter(byte[] request, String parameterName);
|
|
|
|
/**
|
|
* This method can be used to URL-decode the specified data.
|
|
*
|
|
* @param data The data to be decoded.
|
|
* @return The decoded data.
|
|
*/
|
|
String urlDecode(String data);
|
|
|
|
/**
|
|
* This method can be used to URL-encode the specified data. Any characters
|
|
* that do not need to be encoded within HTTP requests are not encoded.
|
|
*
|
|
* @param data The data to be encoded.
|
|
* @return The encoded data.
|
|
*/
|
|
String urlEncode(String data);
|
|
|
|
/**
|
|
* This method can be used to URL-decode the specified data.
|
|
*
|
|
* @param data The data to be decoded.
|
|
* @return The decoded data.
|
|
*/
|
|
byte[] urlDecode(byte[] data);
|
|
|
|
/**
|
|
* This method can be used to URL-encode the specified data. Any characters
|
|
* that do not need to be encoded within HTTP requests are not encoded.
|
|
*
|
|
* @param data The data to be encoded.
|
|
* @return The encoded data.
|
|
*/
|
|
byte[] urlEncode(byte[] data);
|
|
|
|
/**
|
|
* This method can be used to Base64-decode the specified data.
|
|
*
|
|
* @param data The data to be decoded.
|
|
* @return The decoded data.
|
|
*/
|
|
byte[] base64Decode(String data);
|
|
|
|
/**
|
|
* This method can be used to Base64-decode the specified data.
|
|
*
|
|
* @param data The data to be decoded.
|
|
* @return The decoded data.
|
|
*/
|
|
byte[] base64Decode(byte[] data);
|
|
|
|
/**
|
|
* This method can be used to Base64-encode the specified data.
|
|
*
|
|
* @param data The data to be encoded.
|
|
* @return The encoded data.
|
|
*/
|
|
String base64Encode(String data);
|
|
|
|
/**
|
|
* This method can be used to Base64-encode the specified data.
|
|
*
|
|
* @param data The data to be encoded.
|
|
* @return The encoded data.
|
|
*/
|
|
String base64Encode(byte[] data);
|
|
|
|
/**
|
|
* This method can be used to convert data from String form into an array of
|
|
* bytes. The conversion does not reflect any particular character set, and
|
|
* a character with the hex representation 0xWXYZ will always be converted
|
|
* into a byte with the representation 0xYZ. It performs the opposite
|
|
* conversion to the method <code>bytesToString()</code>, and byte-based
|
|
* data that is converted to a String and back again using these two methods
|
|
* is guaranteed to retain its integrity (which may not be the case with
|
|
* conversions that reflect a given character set).
|
|
*
|
|
* @param data The data to be converted.
|
|
* @return The converted data.
|
|
*/
|
|
byte[] stringToBytes(String data);
|
|
|
|
/**
|
|
* This method can be used to convert data from an array of bytes into
|
|
* String form. The conversion does not reflect any particular character
|
|
* set, and a byte with the representation 0xYZ will always be converted
|
|
* into a character with the hex representation 0x00YZ. It performs the
|
|
* opposite conversion to the method <code>stringToBytes()</code>, and
|
|
* byte-based data that is converted to a String and back again using these
|
|
* two methods is guaranteed to retain its integrity (which may not be the
|
|
* case with conversions that reflect a given character set).
|
|
*
|
|
* @param data The data to be converted.
|
|
* @return The converted data.
|
|
*/
|
|
String bytesToString(byte[] data);
|
|
|
|
/**
|
|
* 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 <code>String.indexOf()</code> works on
|
|
* String-based data.
|
|
*
|
|
* @param data The data to be searched.
|
|
* @param pattern The pattern to be searched for.
|
|
* @param caseSensitive Flags whether or not the search is case-sensitive.
|
|
* @param from The offset within <code>data</code> where the search should
|
|
* begin.
|
|
* @param to The offset within <code>data</code> where the search should
|
|
* end.
|
|
* @return The offset of the first occurrence of the pattern within the
|
|
* specified bounds, or -1 if no match is found.
|
|
*/
|
|
int indexOf(
|
|
byte[] data,
|
|
byte[] pattern,
|
|
boolean caseSensitive,
|
|
int from,
|
|
int to);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param headers A list of headers to include in the message.
|
|
* @param body The body of the message, of <code>null</code> if the message
|
|
* has an empty body.
|
|
* @return The resulting full HTTP message.
|
|
*/
|
|
byte[] buildHttpMessage(List<String> headers, byte[] body);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param url The URL to which the request should be made.
|
|
* @return A request to the specified URL.
|
|
*/
|
|
byte[] buildHttpRequest(URL url);
|
|
|
|
/**
|
|
* This method adds a new parameter to an HTTP request, and if appropriate
|
|
* updates the Content-Length header.
|
|
*
|
|
* @param request The request to which the parameter should be added.
|
|
* @param parameter An <code>IParameter</code> object containing details of
|
|
* the parameter to be added. Supported parameter types are:
|
|
* <code>PARAM_URL</code>, <code>PARAM_BODY</code> and
|
|
* <code>PARAM_COOKIE</code>.
|
|
* @return A new HTTP request with the new parameter added.
|
|
*/
|
|
byte[] addParameter(byte[] request, IParameter parameter);
|
|
|
|
/**
|
|
* This method removes a parameter from an HTTP request, and if appropriate
|
|
* updates the Content-Length header.
|
|
*
|
|
* @param request The request from which the parameter should be removed.
|
|
* @param parameter An <code>IParameter</code> object containing details of
|
|
* the parameter to be removed. Supported parameter types are:
|
|
* <code>PARAM_URL</code>, <code>PARAM_BODY</code> and
|
|
* <code>PARAM_COOKIE</code>.
|
|
* @return A new HTTP request with the parameter removed.
|
|
*/
|
|
byte[] removeParameter(byte[] request, IParameter parameter);
|
|
|
|
/**
|
|
* This method updates the value of a parameter within an HTTP request, and
|
|
* if appropriate updates the Content-Length header. <b>Note:</b> 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 <code>removeParameter()</code> to remove the
|
|
* parameter with the old type, and then call <code>addParameter()</code> to
|
|
* add a parameter with the new type.
|
|
*
|
|
* @param request The request containing the parameter to be updated.
|
|
* @param parameter An <code>IParameter</code> object containing details of
|
|
* the parameter to be updated. Supported parameter types are:
|
|
* <code>PARAM_URL</code>, <code>PARAM_BODY</code> and
|
|
* <code>PARAM_COOKIE</code>.
|
|
* @return A new HTTP request with the parameter updated.
|
|
*/
|
|
byte[] updateParameter(byte[] request, IParameter parameter);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param request The HTTP request whose method should be toggled.
|
|
* @return A new HTTP request using the toggled method.
|
|
*/
|
|
byte[] toggleRequestMethod(byte[] request);
|
|
|
|
/**
|
|
* This method constructs an <code>IHttpService</code> object based on the
|
|
* details provided.
|
|
*
|
|
* @param host The HTTP service host.
|
|
* @param port The HTTP service port.
|
|
* @param protocol The HTTP service protocol.
|
|
* @return An <code>IHttpService</code> object based on the details
|
|
* provided.
|
|
*/
|
|
IHttpService buildHttpService(String host, int port, String protocol);
|
|
|
|
/**
|
|
* This method constructs an <code>IHttpService</code> object based on the
|
|
* details provided.
|
|
*
|
|
* @param host The HTTP service host.
|
|
* @param port The HTTP service port.
|
|
* @param useHttps Flags whether the HTTP service protocol is HTTPS or HTTP.
|
|
* @return An <code>IHttpService</code> object based on the details
|
|
* provided.
|
|
*/
|
|
IHttpService buildHttpService(String host, int port, boolean useHttps);
|
|
|
|
/**
|
|
* This method constructs an <code>IParameter</code> object based on the
|
|
* details provided.
|
|
*
|
|
* @param name The parameter name.
|
|
* @param value The parameter value.
|
|
* @param type The parameter type, as defined in the <code>IParameter</code>
|
|
* interface.
|
|
* @return An <code>IParameter</code> object based on the details provided.
|
|
*/
|
|
IParameter buildParameter(String name, String value, byte type);
|
|
|
|
/**
|
|
* This method constructs an <code>IHttpHeader</code> object based on the
|
|
* details provided.
|
|
*
|
|
* @param name The header name.
|
|
* @param value The header value.
|
|
* @return An <code>IHttpHeader</code> object based on the details provided.
|
|
*/
|
|
IHttpHeader buildHeader(String name, String value);
|
|
|
|
/**
|
|
* This method constructs an <code>IScannerInsertionPoint</code> 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.
|
|
*
|
|
* @param insertionPointName The name of the insertion point.
|
|
* @param baseRequest The request from which to build scan requests.
|
|
* @param from The offset of the start of the payload location.
|
|
* @param to The offset of the end of the payload location.
|
|
* @return An <code>IScannerInsertionPoint</code> object based on the
|
|
* details provided.
|
|
*/
|
|
IScannerInsertionPoint makeScannerInsertionPoint(
|
|
String insertionPointName,
|
|
byte[] baseRequest,
|
|
int from,
|
|
int to);
|
|
|
|
/**
|
|
* This method analyzes one or more responses to identify variations in a
|
|
* number of attributes and returns an <code>IResponseVariations</code>
|
|
* object that can be queried to obtain details of the variations.
|
|
*
|
|
* @param responses The responses to analyze.
|
|
* @return An <code>IResponseVariations</code> object representing the
|
|
* variations in the responses.
|
|
*/
|
|
IResponseVariations analyzeResponseVariations(byte[]... responses);
|
|
|
|
/**
|
|
* This method analyzes one or more responses to identify the number of
|
|
* occurrences of the specified keywords and returns an
|
|
* <code>IResponseKeywords</code> object that can be queried to obtain
|
|
* details of the number of occurrences of each keyword.
|
|
*
|
|
* @param keywords The keywords to look for.
|
|
* @param responses The responses to analyze.
|
|
* @return An <code>IResponseKeywords</code> object representing the counts
|
|
* of the keywords appearing in the responses.
|
|
*/
|
|
IResponseKeywords analyzeResponseKeywords(List<String> keywords, byte[]... responses);
|
|
}
|