pappyproxy package

Subpackages

Submodules

pappyproxy.comm module

pappyproxy.config module

The configuration settings for the proxy.

pappyproxy.config.CERT_DIR

The location of the CA certs that Pappy will use. This can be configured in the config.json file for a project.

Default:{DATADIR}/certs
pappyproxy.config.PAPPY_DIR

The file where pappy’s scripts are located. Don’t write anything here, and you probably don’t need to write anything here. Use DATA_DIR instead.

Default:Wherever the scripts are installed
pappyproxy.config.DATA_DIR

The data directory. This is where files that have to be read by Pappy every time it’s run are put. For example, plugins are stored in {DATADIR}/plugins and certs are by default stored in {DATADIR}/certs. This defaults to ~/.pappy and isn’t configurable right now.

Default:~/.pappy
pappyproxy.config.DATAFILE

The location of the CA certs that Pappy will use. This can be configured in the config.json file for a project.

Default:data.db
pappyproxy.config.DEBUG_DIR

The directory to write debug output to. Don’t put this outside the project folder since it writes all the request data to this directory. You probably won’t need to use this. Configured in the config.json file for the project.

Default:None

pappyproxy.console module

Contains helpers for interacting with the console. Includes definition for the class that is used to run the console.

class pappyproxy.console.ProxyCmd(*args, **kwargs)

Bases: cmd2.Cmd

An object representing the console interface. Provides methods to add commands and aliases to the console.

add_alias(command, alias)

Add an alias for a command. ie add_alias(“foo”, “f”) will let you run the ‘foo’ command with ‘f’

add_aliases(alias_list)

Pass in a list of tuples to add them all as aliases. ie add_aliases([(‘foo’, ‘f’), (‘foo’, ‘fo’)]) will add ‘f’ and ‘fo’ as aliases for ‘foo’

set_cmd(command, func, autocomplete_func=None)

Add a command to the console.

set_cmds(cmd_dict)

Set multiple commands from a dictionary. Format is: {‘command’: (do_func, autocomplete_func)} Use autocomplete_func=None for no autocomplete function

pappyproxy.console.confirm(message, default='n')

A helper function to get confirmation from the user. It prints message then asks the user to answer yes or no. Returns True if the user answers yes, otherwise returns False.

pappyproxy.console.load_reqlist(line, allow_special=True)

A helper function for parsing a list of requests that are passed as an argument. If allow_special is True, then it will parse IDs such as u123 or s123. Even if allow_special is false, it will still parse m## IDs. Will print any errors with loading any of the requests and will return a list of all the requests which were successfully loaded. Returns a deferred.

Returns:Twisted deferred
pappyproxy.console.print_requests(requests)

Takes in a list of requests and prints a table with data on each of the requests. It’s the same table that’s used by ls.

pappyproxy.console.print_table(coldata, rows)

Print a table. Coldata: List of dicts with info on how to print the columns. name is the heading to give column, width (optional) maximum width before truncating. 0 for unlimited.

Rows: List of tuples with the data to print

pappyproxy.context module

class pappyproxy.context.Context

Bases: object

A class representing a set of requests that pass a set of filters

Variables:
  • active_filters (List of functions that takes one pappyproxy.http.Request and returns either true or false.) – Filters that are currently applied to the context
  • active_requests – Requests which pass all the filters applied to the context
  • inactive_requests – Requests which do not pass all the filters applied to the context
add_filter(filt)

Add a filter to the context. This will remove any requests that do not pass the filter from the active_requests set.

Parameters:filt (Function that takes one pappyproxy.http.Request and returns either true or false. (or a pappyproxy.context.Filter)) – The filter to add
add_request(req)

Adds a request to the context. If the request passes all of the context’s filters, it will be placed in the active_requests set. If it does not, it will be placed in the inactive_requests set. Either way, it will be added to all_reqs and if appropriate, in_memory_requests.

Parameters:req (Request) – The request to add
all_reqs = set([])

Class variable! All requests in history. Do not directly add requests to this set. Instead, use pappyproxy.context.Context.add_request() on some context. It will automatically be added to this set.

filter_up()

Removes the last filter that was applied to the context.

in_memory_requests = set([])

Class variable! Requests that are only stored in memory. These are the requests with m## style IDs. Do not directly add requests to this set. Instead, use pappyproxy.context.Context.add_request() on some context with a request that has not been saved. It will automatically be assigned a m## id and be added to this set.

static remove_request(req)

Removes request from all contexts. It is suggested that you use pappyproxy.http.Request.deep_delete() instead as this will remove the request (and its unmangled version, response, and unmangled response) from the data file as well. Otherwise it will just be put back into the context when Pappy is restarted.

Parameters:req (Request) – The request to remove
set_filters(filters)

Set the list of filters for the context.

class pappyproxy.context.Filter(filter_string)

Bases: object

A class representing a filter. Its claim to fame is that you can use pappyproxy.context.Filter.from_filter_string() to generate a filter from a filter string.

static from_filter_string(filter_string)

Create a filter from a filter string.

Return type:Deferred that returns a pappyproxy.context.Filter
pappyproxy.context.async_set_tag(tag, reqs)

Remove the tag from every request then add the given requests to memory and give them the tag. The async version.

Parameters:
  • tag (String) – The tag to set
  • reqs (List of Requests) – The requests to assign to the tag
pappyproxy.context.set_tag(tag, reqs)

Remove the tag from every request then add the given requests to memory and give them the tag. The non-async version.

Parameters:
  • tag (String) – The tag to set
  • reqs (List of Requests) – The requests to assign to the tag

pappyproxy.http module

class pappyproxy.http.HTTPMessage(full_message=None, update_content_length=False)

Bases: object

A base class which represents an HTTP message. It is used to implement both requests and responses

Variables:
add_data(data)

Used for building a message from a Twisted protocol. Add data to the message. The data must conform to the content encoding and transfer encoding given in the headers passed in to add_line(). Can be any fragment of the data. I do not suggest that you use this function ever.

Parameters:data (string) – The data to add
add_line(line)

Used for building a message from a Twisted protocol. Add a line (for status line and headers). Lines must be added in order and the first line must be the status line. The line should not contain the trailing carriage return/newline. I do not suggest you use this for anything.

Parameters:line (string) – The line to add
body

The data portion of the message

Getter:Returns the data portion of the message
Setter:Set the data of the response and update metadata
Type:string
body_complete()

Called when the body of the message is complete

body_pretty

Same thing as pappy.http.HTTPMessage.body() but the output is colorized for the terminal.

copy()

Returns a copy of the request

Return type:Request
from_json(json_string)

Update the metadata of the message to match data from to_json()

Parameters:json_string (JSON data in a string) – The JSON data to use
full_message

The full message including the start line, headers, and body

full_message_pretty

Same as pappyproxy.http.HTTPMessage.full_message() except the output is colorized

get_metadata()

Get all the metadata of the message in dictionary form. Should be implemented in child class. Should not be invoked outside of implementation!

handle_header(key, val)

Called when a header is loaded into the message. Should not be called outside of implementation.

Parameters:
  • key – Header key
  • key – Header value
handle_start_line(start_line)

A handler function for the status line.

headers_end()

Called when the headers are complete.

headers_section

The raw text of the headers including the extra newline at the end.

Getter:Returns the raw text of the headers including the extra newline at the end.
Type:string
headers_section_pretty

Same thing as pappyproxy.http.HTTPMessage.headers_section() except that the headers are colorized for terminal printing.

reserved_meta_keys = ['full_message']
reset_metadata()

Reset meta values to default values. Overridden by child class. Should not be invoked outside of implementation!

set_metadata(data)

Set metadata values based off of a data dictionary. Should be implemented in child class. Should not be invoked outside of implementation!

Parameters:data – Metadata to apply
to_json()

Return a JSON encoding of the message that can be used by from_json() to recreate the message. The full_message portion is base64 encoded because json doesn’t play nice with binary blobs.

update_from_body()

Called when the body of the message is modified directly. Should be used to update metadata that depends on the body of the message.

update_from_headers()

Called when a header is modified. Should be used to update metadata that depends on the values of headers.

class pappyproxy.http.RepeatableDict(from_pairs=None, case_insensitive=False)

A dict that retains the order of items inserted and keeps track of duplicate values. Can optionally treat keys as case insensitive. Custom made for the proxy, so it has strange features

add_pairs(pairs)

Add a list of pairs to the dictionary.

Parameters:pairs (List of tuples of length 2) – The list of key/value pairs to add
all_pairs()

A list of all the key/value pairs stored in the dictionary

all_vals(key)

Return all the values associated with a given key

append(key, val)

Append a pair to the end of the dictionary. Will add a duplicate if the key already exists.

clear()

Remove all key/value pairs from the dictionary

from_dict(d)

Set the RepeatableDict to contain the same items as a normal dictionary.

Parameters:d (dict) – The dictionary to use
set_val(key, val)

Set a value in the dictionary. Will replace the first instance of the key with the value. If multiple values of the keys are already in the dictionary, the duplicates of the key will be removed and the first instance of the key will be replaced with the value. If the dictionary is case insensitive, it will maintain the original capitalization. This is the same behavior as assigning a value via d[key] = val. If the key is not present, it will be added to the end of the dict.

sort()

Sort the dictionary by the key. Requires that all keys can be compared to each other

class pappyproxy.http.Request(full_request=None, update_content_length=True, port=None, is_ssl=None, host=None)

Bases: pappyproxy.http.HTTPMessage

Variables:
  • time_end (datetime.datetime) – The datetime that the request ended.
  • time_start (datetime.datetime) – The datetime that the request was made
  • cookies (RepeatableDict) – Cookies sent with the request
  • fragment (String) – The fragment part of the url (The part that comes after the #)
  • url_params (RepeatableDict) – The url parameters of the request (aka the get parameters)
  • path (String) – The path of the request
  • port (Integer) – The port that the request was sent to (or will be sent to)
  • post_params (RepeatableDict) – The post parameters of the request
  • reqid (String) – The request id of the request
  • response (Response) – The associated response of this request
  • submitted (Bool) – Whether the request has been submitted
  • unmangled (Request) – If the request was mangled, the version of the request before it was mangled.
  • verb (String) – The HTTP verb of the request (ie POST, GET)
  • version (String) – The HTTP version of the request (ie HTTP/1.1)
  • tags (List of Strings) – Tags associated with the request
  • plugin_data (Dict) – Data about the request created by plugins. If you modify this, please add your own key to it for your plugin and store all your plugin’s data under that key (probably as another dict). For example if you have a plugin called foo, try and store all your data under req.plugin_data['foo'].
async_deep_save()

Saves self, unmangled, response, and unmangled response. Returns a deferred which fires after everything has been saved.

Return type:twisted.internet.defer.Deferred
async_save()

Save/update the request in the data file. Returns a twisted deferred which fires when the save is complete.

Return type:twisted.internet.defer.Deferred
async_submit()

Same as submit() but generates deferreds. Submits the request using its host, port, etc. and updates its response value to the resulting response.

Return type:Twisted deferred
deep_delete()

Delete a request, its unmangled version, its response, and its response’s unmangled version from history. Also removes the request from all contexts. Returns a Twisted deferred.

Return type:Deferred
full_path

The full path of the request including URL params and fragment. ie /path/to/stuff?foo=bar&baz=something#somewhere

Getter:Returns the full path of the request
Type:string
full_request

Alias for Request.full_message

Getter:Returns the full text of the request
Type:string
host

The host of the request. ie www.google.com.

Getter:Returns the host of the request
Setter:Changes the host of the request and updates the Host header
Type:string
is_ssl

Whether the request is sent over SSL

Getter:Returns if the request is sent over SSL
Setter:Sets if the request is sent over SSL
Type:Bool
static load_all_requests()

Load all the requests in the data file and return them in a list. Returns a deferred which calls back with the list of requests when complete.

Return type:twisted.internet.defer.Deferred
static load_request(to_load)

Load a request with the given request id and return it. Returns a deferred which calls back with the request when complete.

Return type:twisted.internet.defer.Deferred
static load_requests_by_tag(tag)

Load all the requests in the data file with a given tag and return them in a list. Returns a deferred which calls back with the list of requests when complete.

Return type:twisted.internet.defer.Deferred
path_tuple

The path in tuple form starting with the host. For example, path_parts for a request to http://www.example.com/foo/bar.php would be:

('www.example.com', 'foo', 'bar.php')
Getter:Returns the path in tuple form
Type:Tuple
raw_data

Alias for Request.body

Getter:Returns the data portion of the request
Setter:Set the data of the request and update metadata
Type:string
raw_headers

Alias for Request.headers_section

Getter:Returns the raw text of the headers including the extra newline at the end.
Type:string
rsptime

The response time of the request

Getter:Returns the response time of the request
Type:datetime.timedelta
save()

Save/update the request in the data file. Saves the request, its unmangled version, the response, and the unmanbled response. Cannot be called from inside an async function.

saved

If the request is saved in the data file

Getter:Returns True if the request is saved in the data file
Type:Bool
start_line

The status line of the request. ie GET / HTTP/1.1

Getter:Returns the status line of the request
Setter:Sets the status line of the request
Type:string
status_line

Alias for pappyproxy.http.Request.start_line.

Getter:Returns the status line of the request
Setter:Sets the status line of the request
Type:string
submit()

Submits the request using its host, port, etc. and updates its response value to the resulting response. Cannot be called in async functions. This is what you should use to submit your requests in macros.

static submit_new(host, port, is_ssl, full_request)

Submits a request with the given parameters and returns a request object with the response.

Parameters:
  • host (string) – The host to submit to
  • port (Integer) – The port to submit to
  • full_request (string) – The request data to send
Return type:

Twisted deferred that calls back with a Request
url

The full url of the request including url params, protocol, etc. ie https://www.google.com, http://foo.fakewebsite.com:1234/path?a=b. When setting the URL, the port, is_ssl, path, url params, host, etc are all automatically updated.

Getter:Returns the url of the request
Setter:Sets the url of the request and updates metadata
Type:string
class pappyproxy.http.Response(full_response=None, update_content_length=True)

Bases: pappyproxy.http.HTTPMessage

Variables:
  • cookies (RepeatableDict of ResponseCookie objects) – Cookies set by the response
  • response_code (Integer) – The response code of the response
  • response_text (String) – The text associated with the response code (ie OK, NOT FOUND, etc)
  • rspid (String) – If the response is saved in the data file, the id of the response
  • unmangled (Response) – If the response was mangled, the unmangled version of the response
  • version (String) – The version part of the status line (ie HTTP/1.1)

Add a pappyproxy.http.ResponseCookie to the response.

Warning

This will add duplicate cookies. If you want to add a cookie you’re not sure exists, use set_cookie()

async_save()

Save/update the just request in the data file. Returns a twisted deferred which fires when the save is complete. It is suggested that you use :func: ~pappyproxy.http.Request.async_deep_save instead to save responses.

Return type:twisted.internet.defer.Deferred

Delete a cookie from the response by its key

full_response

The full text of the response including the headers and data. Alias for Response.full_message

Getter:Returns the full text of the response
Type:string
static load_response(*args, **kwargs)

Load a response from its response id. Returns a deferred. I don’t suggest you use this.

Return type:twisted.internet.defer.Deferred
raw_data

Alias for Response.body

Getter:Returns the data portion of the response
Setter:Set the data of the response and update metadata
Type:string
raw_headers

Alias for Response.headers_section

Getter:Returns the raw text of the headers including the extra newline at the end.
Type:string

Set a cookie in the response. cookie must be a pappyproxy.http.ResponseCookie

Set a cookie by key and value. Will not have path, secure, etc set at all.

soup

Returns a beautifulsoup4 object for parsing the html of the response

Getter:Returns a BeautifulSoup object representing the html of the response
start_line

The status line of the response. ie HTTP/1.1 200 OK

Getter:Returns the status line of the response
Setter:Sets the status line of the response
Type:string
class pappyproxy.http.ResponseCookie(set_cookie_string=None)

Bases: object

A cookie representing a cookie set by a response

Variables:
  • key – The key of the cookie
  • val – The value of the cookie
  • expires – The value of the “expires” attribute
  • max_age – The max age of the cookie
  • domain – The domain of the cookie
  • path – The path of the cookie
  • secure – The secure flag of the cookie
  • http_only – The httponly flag of the cookie
cookie_str

Returns the full string of the cookie. ie foo=bar; secure; path=/

Getter:Returns the full string of the cookie.
Setter:Set the metadata from a cookie string. ie from a Set-Cookie header
pappyproxy.http.get_request(url='', url_params={})

Create a request object that makes a GET request to the given url with the given url params.

pappyproxy.http.init(pool)

Initialize the http module.

Parameters:pool (SQLite ConnectionPool) – The ConnectionPool to use to store the request/response objects
pappyproxy.http.post_request(url, post_params={}, url_params={})

Create a request object that makes a POST request to the given url with the given post and url params.

pappyproxy.iter module

pappyproxy.iter.common_passwords()

List common passwords

pappyproxy.iter.common_usernames()

List common usernames

pappyproxy.iter.fuzz_path_trav()

Fuzz common values for path traversal.

pappyproxy.iter.fuzz_sqli()

Fuzz common values that could cause sql errors

pappyproxy.iter.fuzz_xss()

Fuzz values for finding XSS

pappyproxy.macros module

class pappyproxy.macros.FileInterceptMacro(filename='')

Bases: pappyproxy.macros.InterceptMacro

An intercepting macro that loads a macro from a file.

class pappyproxy.macros.InterceptMacro

Bases: object

A class representing a macro that modifies requests as they pass through the proxy

class pappyproxy.macros.Macro(filename='')

Bases: object

A class representing a macro that can perform a series of requests and add data to storage.

pappyproxy.macros.load_macros(loc)

Loads the macros stored in the location and returns a list of Macro objects

pappyproxy.pappy module

pappyproxy.plugin module

This module contains all the api calls written for use in plugins. If you want to do anything that is’t allowed through these function calls or through the functions provided for macros, contact me and I’ll see what I can do to add some more functionality into the next version.

pappyproxy.plugin.active_intercepting_macros()

Returns a list of the active intercepting macro objects. Modifying this list will not affect which macros are active.

pappyproxy.plugin.add_intercepting_macro(name, macro)

Adds an intercepting macro to the proxy. You can either use a pappyproxy.macros.FileInterceptMacro to load an intercepting macro from the disk, or you can create your own using an pappyproxy.macros.InterceptMacro for a base class. You must give a unique name that will be used in pappyproxy.plugin.remove_intercepting_macro() to deactivate it. Remember that activating an intercepting macro will disable request streaming and will affect performance. So please try and only use this if you may need to modify messages before they are passed along.

pappyproxy.plugin.add_req(req)

Adds a request to the history. Will not do anything to requests which are already in history. If the request is not saved, it will be given an m## id.

pappyproxy.plugin.all_reqs()

Returns a list containing all the requests in history (including requests that only exist in memory). Modifying this list will not modify requests included in the history. However, you can edit the requests in this list then call either pappyproxy.http.Request.save() or pappyproxy.http.Request.async_save() to modify the actual request.

pappyproxy.plugin.in_memory_reqs()

Returns a list containing all out of the requests which exist in memory only (requests with an m## style id). You can call either pappyproxy.http.Request.save() or pappyproxy.http.Request.async_save() to save the request to the data file.

pappyproxy.plugin.main_context()

Returns the context object representing the main context. Use this to interact with the context. The returned object can be modified at will. Avoid modifying any class values (ie all_reqs, in_memory_requests) and use the class methods to add/remove requests. See the documentation on pappyproxy.context.Context for more information.

pappyproxy.plugin.plugin_by_name(name)

Returns an interface to access the methods of a plugin from its name. For example, to call the foo function from the bar plugin you would call plugin_by_name('bar').foo().

pappyproxy.plugin.remove_intercepting_macro(name)

Stops an active intercepting macro. You must pass in the name that you used when calling pappyproxy.plugin.add_intercepting_macro() to identify which macro you would like to stop.

pappyproxy.plugin.run_cmd(cmd)

Run a command as if you typed it into the console. Try and use existing APIs to do what you want before using this.

pappyproxy.proxy module

pappyproxy.repeater module

pappyproxy.session module

pappyproxy.util module

exception pappyproxy.util.PappyException

Bases: exceptions.Exception

The exception class for Pappy. If a plugin command raises one of these, the message will be printed to the console rather than displaying a traceback.

pappyproxy.util.printable_data(data)

Return data, but replaces unprintable characters with periods.

Parameters:data (String) – The data to make printable
Return type:String

Module contents