As discussed in the Flow View section of the mitmproxy overview, mitmproxy allows you to inspect and manipulate flows. When inspecting a single flow, mitmproxy uses a number of heuristics to show a friendly view of various content types; if mitmproxy cannot show a friendly view, mitmproxy defaults to a raw view.

By default, mitmproxy has support for displaying the following content types in a friendly view:

  • 1: Hex
  • 2: HTML
  • 3: Image
  • 4: JavaScript
  • 5: JSON
  • 6: URL-encoded data
  • 7: XML
  • 8: AMF (requires PyAMF)
  • 9: Protobuf (requires protobuf library)

Each content type invokes a different flow viewer to parse the data and display the friendly view. Users can add custom content viewers by adding a view class to contentview.py, discussed below.

Adding a new View class to contentview.py

The content viewers used by mitmproxy to present a friendly view of various content types are stored in contentview.py. Reviewing this file shows a number of classes named ViewSomeDataType, each with the properties: name, prompt, and content_types and a function named __call__.

Adding a new content viewer to parse a data type is as simple as writing a new View class. Your new content viewer View class should have the same properties as the other View classes: name, prompt, and content_types and a __call__ function to parse the content of the request/response.

  • The name property should be a string describing the contents and new content viewer;
  • The prompt property should be a two item tuple:

    • 1: A string that will be used to display the new content viewer's type; and
    • 2: A one character string that will be the hotkey used to select the new content viewer from the Flow View screen;
  • The content_types property should be a list of strings of HTTP Content-Types that the new content viewer can parse.

    • Note that mitmproxy will use the content_types to try and heuristically show a friendly view of content and that you can override the built-in views by populating content_types with values for content_types that are already parsed -- e.g. "image/png".

After defining the name, prompt, and content_types properties of the class, you should write the __call__ function, which will parse the request/response data and provide a friendly view of the data. The __call__ function should take the following arguments: self, hdrs, content, limit; hdrs is a ODictCaseless object containing the headers of the request/response; content is the content of the request/response, and limit is an integer representing the amount of data to display in the view window.

The __call__ function returns two values: (1) a string describing the parsed data; and (2) the parsed data for friendly display. The parsed data to be displayed should be a list of strings formatted for display. You can use the _view_text function in contentview.py to format text for display. Alternatively, you can display content as a series of key-value pairs; to do so, prepare a list of lists, where each list item is a two item list -- a key that describes the data, and then the data itself; after preparing the list of lists, use the common.format_keyvals function on it to prepare it as text for display.

If the new content viewer fails or throws an exception, mitmproxy will default to a raw view.