From c34d1e3de6483b1ab8a1a3add53fb84364c68249 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Mon, 11 Mar 2013 11:49:36 +1300 Subject: [PATCH] Docs, examples. --- doc-src/certinstall/firefox.html | 24 +++++++++++++---------- doc-src/certinstall/ios.html | 19 ++++++++++-------- doc-src/certinstall/osx.html | 13 ++++++++----- doc-src/certinstall/windows7.html | 29 ++++++++++++++++++++-------- doc-src/features/proxyauth.html | 5 +++-- doc-src/features/sticky.html | 6 ++---- doc-src/index.py | 3 ++- doc-src/mitmproxy.html | 6 ++++-- doc-src/scripting/inlinescripts.html | 11 ++++++++++- doc-src/ssl.html | 7 ++++++- examples/README | 1 + 11 files changed, 82 insertions(+), 42 deletions(-) diff --git a/doc-src/certinstall/firefox.html b/doc-src/certinstall/firefox.html index a107aebc0..2b2998685 100644 --- a/doc-src/certinstall/firefox.html +++ b/doc-src/certinstall/firefox.html @@ -1,19 +1,23 @@ How to install the __mitmproxy__ certificate authority in Firefox: -### 1. If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target. +
    +
  1. If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target.
    2. -### 2: Open preferences, click on "Advanced", then select"Encryption": +
  2. Open preferences, click on "Advanced", then select"Encryption": + +
    3. - +
  3. Click "View Certificates", "Import", and select the certificate file: + +
    4. -### 3: Click "View Certificates", "Import", and select the certificate file: +
  4. Tick "Trust this CS to identify web sites", and click "Ok": + +
    5. - +
  5. You should now see the mitmproxy certificate listed in the Authorities + tab.
    6. -### 4: Tick "Trust this CS to identify web sites", and click "Ok": - - - -You should now see the mitmproxy certificate listed in the Authorities tab. +
diff --git a/doc-src/certinstall/ios.html b/doc-src/certinstall/ios.html index d306dfc67..81e2cce6f 100644 --- a/doc-src/certinstall/ios.html +++ b/doc-src/certinstall/ios.html @@ -1,18 +1,21 @@ How to install the __mitmproxy__ certificate authority on IOS devices: -### 1: Set up the Mail app on the device to receive email. +
    +
  1. Set up the Mail app on the device to receive email.
    2. -### 2: Mail the mitmproxy-ca-cert.pem file to the device, and tap on the attachment. +
  2. Mail the mitmproxy-ca-cert.pem file to the device, and tap on the attachment.
    3. -### 3: You will be prompted to install a profile. Click "Install": +
  3. You will be prompted to install a profile. Click "Install": - +
    4. -### 4: Accept the warning by clicking "Install" again: +
  4. Accept the warning by clicking "Install" again: - +
    5. -### 5: The certificate should now be trusted: +
  5. The certificate should now be trusted: - +
    6. + +
diff --git a/doc-src/certinstall/osx.html b/doc-src/certinstall/osx.html index 465ada434..61e4be71f 100644 --- a/doc-src/certinstall/osx.html +++ b/doc-src/certinstall/osx.html @@ -1,13 +1,16 @@ How to install the __mitmproxy__ certificate authority in OSX: -### 1: Open Finder, and double-click on the mitmproxy-ca-cert.pem file. +
    +
  1. Open Finder, and double-click on the mitmproxy-ca-cert.pem file.
    2. -### 2: You will be prompted to add the certificate. Click "Always Trust": +
  2. You will be prompted to add the certificate. Click "Always Trust": - + +
    3. -You may be prompted for your password. You should now see the mitmproxy cert -listed under "Certificates". +
  3. You may be prompted for your password. You should now see the + mitmproxy cert listed under "Certificates".
    4. +
diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html index 7c2bb3eff..7a2414a27 100644 --- a/doc-src/certinstall/windows7.html +++ b/doc-src/certinstall/windows7.html @@ -1,19 +1,32 @@ How to install the __mitmproxy__ certificate authority in Windows 7: -### 1: Copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the target system. +
    -### 2: Double-click the certificate file. You should see a certificate import wizard: +
  1. Copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the target system.
    2. - +
  2. + Double-click the certificate file. You should see a certificate import wizard: -### 3: Click "Next" until you're prompted for the certificate store: + +
    3. - +
  3. + Click "Next" until you're prompted for the certificate store: -### 4: Select "Place all certificates in the following store", and select "Trusted Root Certification Authorities": + - +
    4. -### 5: Click "Next" and "Finish". + +
  4. +

    Select "Place all certificates in the following store", and select "Trusted Root Certification Authorities":

    + + + +
    5. + +
  5. Click "Next" and "Finish".
    6. + +
diff --git a/doc-src/features/proxyauth.html b/doc-src/features/proxyauth.html index 0618ee681..c22d50f39 100644 --- a/doc-src/features/proxyauth.html +++ b/doc-src/features/proxyauth.html @@ -1,8 +1,9 @@ - Asks the user for authentication before they are permitted to use the proxy. Authentication headers are stripped from the flows, so they are not passed to -upstream servers. For now, only HTTP Basic authentication is supported. +upstream servers. For now, only HTTP Basic authentication is supported. The +proxy auth options are ignored if the proxy is in transparent or reverse proxy +mode. diff --git a/doc-src/features/sticky.html b/doc-src/features/sticky.html index 1b79f9224..591160672 100644 --- a/doc-src/features/sticky.html +++ b/doc-src/features/sticky.html @@ -22,8 +22,7 @@ with the secured resources. @@ -48,8 +47,7 @@ replay of HTTP Digest authentication. diff --git a/doc-src/index.py b/doc-src/index.py index aa178fa08..7b65adb9f 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -27,11 +27,12 @@ def mpath(p): ns.index_contents = file(mpath("README.mkd")).read() def example(s): - d = file(mpath(s)).read() + d = file(mpath(s)).read().rstrip() extemp = """
%s
(%s)
""" return extemp%(countershape.template.Syntax("py")(d), s) ns.example = example + filt_help = [] for i in filt.filt_unary: filt_help.append( diff --git a/doc-src/mitmproxy.html b/doc-src/mitmproxy.html index f5bdbef8c..678d41b58 100644 --- a/doc-src/mitmproxy.html +++ b/doc-src/mitmproxy.html @@ -1,7 +1,9 @@ __mitmproxy__ is a console tool that allows interactive examination and -modification of HTTP traffic. Use the _?_ shortcut key to view, -context-sensitive documentation from any __mitmproxy__ screen. +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 _?_ shortcut key to view, context-sensitive +documentation from any __mitmproxy__ screen. ## Flow list diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html index 7abf743c6..39752b7f0 100644 --- a/doc-src/scripting/inlinescripts.html +++ b/doc-src/scripting/inlinescripts.html @@ -13,6 +13,15 @@ lets the script interact with the global mitmproxy state. The __response__ event also gets an instance of Flow, which we can use to manipulate the response itself. +We can now run this script as follows: + +
+> mitmdump -s add_header.py
+
+ +The new header will be added to all responses passing through the proxy. + + ## Events @@ -60,7 +69,7 @@ Called once on script shutdown, after any other events. The main classes you will deal with in writing mitmproxy scripts are: -
command-line
    -
  • -t (sticky cookies on all requests)
    • -
  • -T FILTER (sticky cookies on requests matching filter
    • +
  • -t FILTER
command-line
    -
  • -u (sticky auth on all requests)
    • -
  • -U FILTER (sticky auth on requests matching filter
    • +
  • -u FILTER
+
diff --git a/doc-src/ssl.html b/doc-src/ssl.html index 7ee9438e3..8708fe6f6 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -3,7 +3,7 @@ The first time __mitmproxy__ or __mitmdump__ is started, the following set of certificate files for a dummy Certificate Authority are created in the config directory (~/.mitmproxy by default): -
libmproxy.flow.ClientConnection Describes a client connection.
+
@@ -17,6 +17,11 @@ directory (~/.mitmproxy by default): + + + +
mitmproxy-ca.pem The private key and certificate in PEM format.mitmproxy-ca-cert.p12 The certificate in PKCS12 format. For use on Windows.
mitmproxy-ca-cert.cerSame file as .pem, but with an extension expected by some Android + devices.
This CA is used for on-the-fly generation of dummy certificates for SSL diff --git a/examples/README b/examples/README index ab06ad27d..0a4684a7f 100644 --- a/examples/README +++ b/examples/README @@ -3,6 +3,7 @@ dup_and_replay.py Duplicates each request, changes it, and then replays th flowbasic Basic use of mitmproxy as a library. modify_form.py Modify all form submissions to add a parameter. modify_querystring.py Modify all query strings to add a parameters. +proxapp How to embed a WSGI app in a mitmproxy server stub.py Script stub with a method definition for every event. stickycookies An example of writing a custom proxy with libmproxy. upsidedownternet.py Rewrites traffic to turn PNGs upside down.