From 1165e35e1b6a3ae59afb6d9e259f75a201406174 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sat, 5 Sep 2015 20:15:35 +0200 Subject: docs++ --- docs/clientreplay.rst | 4 ++ docs/conf.py | 2 +- docs/config.rst | 4 ++ docs/dev/models.rst | 1 + docs/filters.rst | 4 ++ docs/index.rst | 7 +++ docs/mitmdump.rst | 64 +++++++++++++++++++- docs/mitmproxy.rst | 124 ++++++++++++++++++++++++++++++++++++++- docs/modes.rst | 4 +- docs/scripting/inlinescripts.rst | 6 +- 10 files changed, 211 insertions(+), 9 deletions(-) create mode 100644 docs/clientreplay.rst create mode 100644 docs/config.rst create mode 100644 docs/filters.rst diff --git a/docs/clientreplay.rst b/docs/clientreplay.rst new file mode 100644 index 00000000..9b19befe --- /dev/null +++ b/docs/clientreplay.rst @@ -0,0 +1,4 @@ +.. _clientreplay: + +Client-side replay +================== \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 65aa19dc..1581b055 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,7 +56,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'mitmproxy dev docs' +project = u'mitmproxy docs' copyright = u'2015, the mitmproxy project' author = u'The mitmproxy project' diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 00000000..ec96d154 --- /dev/null +++ b/docs/config.rst @@ -0,0 +1,4 @@ +.. _config: + +Configuration +============= \ No newline at end of file diff --git a/docs/dev/models.rst b/docs/dev/models.rst index ef370f09..850d89f5 100644 --- a/docs/dev/models.rst +++ b/docs/dev/models.rst @@ -19,6 +19,7 @@ Models :undoc-members: .. autoclass:: Headers + :show-inheritance: :members: :special-members: :no-undoc-members: \ No newline at end of file diff --git a/docs/filters.rst b/docs/filters.rst new file mode 100644 index 00000000..d2363150 --- /dev/null +++ b/docs/filters.rst @@ -0,0 +1,4 @@ +.. _filters: + +Filters +======= \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 7c792ea4..33aa7b41 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,13 @@ mitmproxy mitmdump + config + +.. toctree:: + :hidden: + :caption: Features + + filters .. toctree:: :hidden: diff --git a/docs/mitmdump.rst b/docs/mitmdump.rst index c56903ec..d9b4a26b 100644 --- a/docs/mitmdump.rst +++ b/docs/mitmdump.rst @@ -1,4 +1,66 @@ .. _mitmdump: +.. program:: mitmdump mitmdump -======== \ No newline at end of file +======== + + +**mitmdump** is the command-line companion to mitmproxy. It provides +tcpdump-like functionality to let you view, record, and programmatically +transform HTTP traffic. See the :option:`--help` flag output for complete +documentation. + + + +Examples +-------- + +Saving traffic +^^^^^^^^^^^^^^ + +>>> mitmdump -w outfile + +Start up mitmdump in proxy mode, and write all traffic to **outfile**. + + +Filtering saved traffic +^^^^^^^^^^^^^^^^^^^^^^^ + +>>> mitmdump -nr infile -w outfile "~m post" + +Start mitmdump without binding to the proxy port (:option:`-n`), read all flows from +infile, apply the specified filter expression (only match POSTs), and write to +outfile. + + +Client replay +^^^^^^^^^^^^^ + +>>> mitmdump -nc outfile + +Start mitmdump without binding to the proxy port (:option:`-n`), then replay all +requests from outfile (:option:`-c filename`). Flags combine in the obvious way, so +you can replay requests from one file, and write the resulting flows to +another: + +>>> mitmdump -nc srcfile -w dstfile + +See the :ref:`clientreplay` section for more information. + + +Running a script +^^^^^^^^^^^^^^^^ + +>>> mitmdump -s examples/add_header.py + +This runs the **add_header.py** example script, which simply adds a new header +to all responses. + +Scripted data transformation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +>>> mitmdump -ns examples/add_header.py -r srcfile -w dstfile + +This command loads flows from **srcfile**, transforms it according to the +specified script, then writes it back to **dstfile**. + diff --git a/docs/mitmproxy.rst b/docs/mitmproxy.rst index b39a8f87..fa3b57c7 100644 --- a/docs/mitmproxy.rst +++ b/docs/mitmproxy.rst @@ -1,4 +1,126 @@ .. _mitmproxy: +.. program:: mitmproxy mitmproxy -========= \ No newline at end of file +========= + + +**mitmproxy** is a console tool that allows interactive examination and +modification of HTTP traffic. It differs from mitmdump in that all flows are +kept in memory, which means that it's intended for taking and manipulating +small-ish samples. Use the :kbd:`?` shortcut key to view, context-sensitive +documentation from any **mitmproxy** screen. + +Flow list +--------- + +The flow list shows an index of captured flows in chronological order. + +.. image:: screenshots/mitmproxy.png + +- **1**: A GET request, returning a 302 Redirect response. +- **2**: A GET request, returning 16.75kb of text/html data. +- **3**: A replayed request. +- **4**: Intercepted flows are indicated with orange text. The user may edit + these flows, and then accept them (using the :kbd:`a` key) to continue. In this + case, the request has been intercepted on the way to the server. +- **5**: A response intercepted from the server on the way to the client. +- **6**: The event log can be toggled on and off using the :kbd:`e` shortcut key. This + pane shows events and errors that may not result in a flow that shows up in the + flow pane. +- **7**: Flow count. +- **8**: Various information on mitmproxy's state. In this case, we have an + interception pattern set to ``.*``. +- **9**: Bind address indicator - mitmproxy is listening on port 8080 of all + interfaces. + + +Flow view +--------- + +The **Flow View** lets you inspect and manipulate a single flow: + +.. image:: screenshots/mitmproxy-flowview.png + +- **1**: Flow summary. +- **2**: The Request/Response tabs, showing you which part of the flow you are + currently viewing. In the example above, we're viewing the Response. Hit :kbd:`tab` + to switch between the Response and the Request. +- **3**: Headers. +- **4**: Body. +- **5**: View Mode indicator. In this case, we're viewing the body in **hex** mode. The other + available modes are **pretty**, which uses a number of heuristics to show you a friendly + view of various content types, and **raw**, which shows you exactly what's there without any + changes. You can change modes using the :kbd:`m` key. + + +Grid Editor +----------- + +Much of the data that we'd like to interact with in mitmproxy is structured. +For instance, headers, queries and form data can all be thought of as a list of +key/value pairs. Mitmproxy has a built-in editor that lays this type of data +out in a grid for easy manipulation. + +At the moment, the Grid Editor is used in four parts of mitmproxy: + + - Editing request or response headers (:kbd:`e` for edit, then :kbd:`h` for headers in flow view) + - Editing a query string (:kbd:`e` for edit, then :kbd:`q` for query in flow view) + - Editing a URL-encoded form (:kbd:`e` for edit, then :kbd:`f` for form in flow view) + - Editing replacement patterns (:kbd:`o` for options, then :kbd:`R` for Replacement Patterns) + +If there is is no data, an empty editor will be started to let you add some. +Here is the editor showing the headers from a request: + +.. image:: screenshots/mitmproxy-kveditor.png + +To edit, navigate to the key or value you want to modify using the arrow or vi +navigation keys, and press enter. The background color will change to show that +you are in edit mode for the specified field: + +.. image:: screenshots/mitmproxy-kveditor-editmode.png + +Modify the field as desired, then press escape to exit edit mode when you're +done. You can also add a row (:kbd:`a` key), delete a row (:kbd:`d` key), spawn an +external editor on a field (:kbd:`e` key). Be sure to consult the context-sensitive +help (:kbd:`?` key) for more. + +Example: Interception +--------------------- + +**mitmproxy**'s interception functionality lets you pause an HTTP request or +response, inspect and modify it, and then accept it to send it on to the server +or client. + + +1: Set an interception pattern +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: screenshots/mitmproxy-intercept-filt.png + +We press :kbd:`i` to set an interception pattern. In this case, the ``~q`` filter +pattern tells **mitmproxy** to intercept all requests. For complete filter +syntax, see the :ref:`filters` section of the documentation, +or the built-in help function in **mitmproxy**. + +2: Intercepted connections are indicated with orange text: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: screenshots/mitmproxy-intercept-mid.png + +3: You can now view and modify the request: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: screenshots/mitmproxy-intercept-options.png + +In this case, we viewed the request by selecting it, pressed :kbd:`e` for "edit" +and :kbd:`m` for "method" to change the HTTP request method. + +4: Accept the intercept to continue: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: screenshots/mitmproxy-intercept-result.png + +Finally, we press :kbd:`a` to accept the modified request, which is then sent on to +the server. In this case, we changed the request from an HTTP GET to +OPTIONS, and Google's server has responded with a 405 "Method not allowed". diff --git a/docs/modes.rst b/docs/modes.rst index ccd1f3ee..197c0525 100644 --- a/docs/modes.rst +++ b/docs/modes.rst @@ -25,7 +25,7 @@ Mitmproxy's regular mode is the simplest and the easiest to set up. 1. Start mitmproxy. 2. Configure your client to use mitmproxy by explicitly setting an HTTP proxy. 3. Quick Check: You should already be able to visit an unencrypted HTTP site through the proxy. -4. Open the magic domain mitm.it and install the certificate for your device. +4. Open the magic domain **mitm.it** and install the certificate for your device. .. note:: Unfortunately, some applications bypass the system HTTP proxy settings - Android applications @@ -91,7 +91,7 @@ In this scenario, we would: 2. Configure the client to use the proxy machine's IP as the default gateway. 3. Quick Check: At this point, you should already be able to visit an unencrypted HTTP site over the proxy. -4. Open the magic domain mitm.it and install the certificate +4. Open the magic domain **mitm.it**mitm and install the certificate for your device. Setting the custom gateway on clients can be automated by serving the settings diff --git a/docs/scripting/inlinescripts.rst b/docs/scripting/inlinescripts.rst index 9b5ced5b..5914def8 100644 --- a/docs/scripting/inlinescripts.rst +++ b/docs/scripting/inlinescripts.rst @@ -152,10 +152,8 @@ The main classes you will deal with in writing mitmproxy scripts are: - An HTTP response. :py:class:`~libmproxy.models.Error` - A communications error. -:py:class:`netlib.odict.ODDict` - - A dictionary-like object for managing sets of key/value data. There - is also a variant called ODictCaseless that ignores key case for some - calls (used mainly for headers). +:py:class:`netlib.http.Headers` + - A dictionary-like object for managing HTTP headers. :py:class:`netlib.certutils.SSLCert` - Exposes information SSL certificates. :py:class:`libmproxy.flow.FlowMaster` -- cgit v1.2.3