Grasscutters/mitmproxy
3
0
Fork 0
mirror of https://github.com/Grasscutters/mitmproxy.git synced 2024-11-22 15:37:45 +00:00
Code Issues Projects Releases Wiki Activity

Revert "Move the doc tree out into its own repo."

Browse Source 
This reverts commit 8f88fcedd6.
This commit is contained in:
Aldo Cortesi 2014-01-27 14:16:23 +13:00
parent 47c7e37723
commit f47d89ff4e
91 changed files with 5706 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc-src/01-bootstrap.min.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

16
doc-src/02-docstyle.css Normal file
View File

@ -0,0 +1,16 @@
body {
padding-top: 60px;
padding-bottom: 40px;
}
.tablenum {
font-weight: bold;
}
.nowrap {
white-space: nowrap;
}
h1 {
line-height: 1.1;
}

572
doc-src/_explicit.graffle/data.plist Normal file
View File

@ -0,0 +1,572 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>ActiveLayerIndex</key>
<integer>0</integer>
<key>ApplicationVersion</key>
<array>
<string>com.omnigroup.OmniGraffle.MacAppStore</string>
<string>139.16</string>
</array>
<key>AutoAdjust</key>
<true/>
<key>BackgroundGraphic</key>
<dict>
<key>Bounds</key>
<string>{{0, 0}, {559.19998741149902, 782.79998779296875}}</string>
<key>Class</key>
<string>SolidGraphic</string>
<key>ID</key>
<integer>2</integer>
<key>Style</key>
<dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
<key>BaseZoom</key>
<integer>0</integer>
<key>CanvasOrigin</key>
<string>{0, 0}</string>
<key>ColumnAlign</key>
<integer>1</integer>
<key>ColumnSpacing</key>
<real>36</real>
<key>CreationDate</key>
<string>2013-01-02 19:31:53 +0000</string>
<key>Creator</key>
<string>Aldo Cortesi</string>
<key>DisplayScale</key>
<string>1.000 cm = 1.000 cm</string>
<key>GraphDocumentVersion</key>
<integer>8</integer>
<key>GraphicsList</key>
<array>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ID</key>
<integer>4074</integer>
<key>Points</key>
<array>
<string>{300.4483540852865, 420.70833897590637}</string>
<string>{344.88497416178387, 420.70833897590654}</string>
<string>{362.21830749511713, 420.04167230923986}</string>
<string>{413.55166625976557, 419.70833905537921}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ID</key>
<integer>4070</integer>
<key>Points</key>
<array>
<string>{84.896692911783873, 420.66667453447985}</string>
<string>{129.33331298828122, 420.66667453448002}</string>
<string>{146.66664632161454, 420.00000786781334}</string>
<string>{198.00000508626297, 419.66667461395269}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{326.00000000000023, 391.39999198913591}, {62, 24}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4063</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 2: Forwarded \
Request}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{110, 403.39997863769622}, {49, 12}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4061</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 1: Request}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{430.83098347981803, 515.99999999999989}, {36, 14}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>ID</key>
<integer>4026</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf0 Server}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{40.499999999999993, 486.66666666666663}, {31, 14}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>ID</key>
<integer>4025</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf0 Client}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{417.16432189941418, 323.90565299479198}, {63.333332061767578, 185.52200317382812}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>4004</integer>
<key>ImageID</key>
<integer>6</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{205.34386889139773, 289.33333333333331}, {84, 248.66667175292969}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>4023</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Color</key>
<dict>
<key>b</key>
<string>0</string>
<key>g</key>
<string>0.463735</string>
<key>r</key>
<string>1</string>
</dict>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf2 mitmproxy}</string>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{4.6666666467984399, 351.33332316080771}, {102.66666412353516, 130.66667175292969}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>134</integer>
<key>ImageID</key>
<integer>3</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
</array>
<key>GridInfo</key>
<dict/>
<key>GuidesLocked</key>
<string>NO</string>
<key>GuidesVisible</key>
<string>YES</string>
<key>HPages</key>
<integer>1</integer>
<key>ImageCounter</key>
<integer>7</integer>
<key>ImageLinkBack</key>
<array>
<dict/>
<dict/>
</array>
<key>ImageList</key>
<array>
<string>image6.tiff</string>
<string>image3.icns</string>
</array>
<key>KeepToScale</key>
<false/>
<key>Layers</key>
<array>
<dict>
<key>Lock</key>
<string>NO</string>
<key>Name</key>
<string>Layer 1</string>
<key>Print</key>
<string>YES</string>
<key>View</key>
<string>YES</string>
</dict>
</array>
<key>LayoutInfo</key>
<dict>
<key>Animate</key>
<string>NO</string>
<key>circoMinDist</key>
<real>18</real>
<key>circoSeparation</key>
<real>0.0</real>
<key>layoutEngine</key>
<string>dot</string>
<key>neatoSeparation</key>
<real>0.0</real>
<key>twopiSeparation</key>
<real>0.0</real>
</dict>
<key>LinksVisible</key>
<string>NO</string>
<key>MagnetsVisible</key>
<string>NO</string>
<key>MasterSheets</key>
<array/>
<key>ModificationDate</key>
<string>2013-01-03 02:27:49 +0000</string>
<key>Modifier</key>
<string>Aldo Cortesi</string>
<key>NotesVisible</key>
<string>NO</string>
<key>Orientation</key>
<integer>2</integer>
<key>OriginVisible</key>
<string>NO</string>
<key>PageBreaks</key>
<string>YES</string>
<key>PrintInfo</key>
<dict>
<key>NSBottomMargin</key>
<array>
<string>float</string>
<string>41</string>
</array>
<key>NSHorizonalPagination</key>
<array>
<string>coded</string>
<string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFxlwCG</string>
</array>
<key>NSLeftMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
<key>NSPaperSize</key>
<array>
<string>size</string>
<string>{595.19998741149902, 841.79998779296875}</string>
</array>
<key>NSPrintReverseOrientation</key>
<array>
<string>int</string>
<string>0</string>
</array>
<key>NSRightMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
<key>NSTopMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
</dict>
<key>PrintOnePage</key>
<false/>
<key>ReadOnly</key>
<string>NO</string>
<key>RowAlign</key>
<integer>1</integer>
<key>RowSpacing</key>
<real>36</real>
<key>SheetTitle</key>
<string>Canvas 1</string>
<key>SmartAlignmentGuidesActive</key>
<string>YES</string>
<key>SmartDistanceGuidesActive</key>
<string>YES</string>
<key>UniqueID</key>
<integer>1</integer>
<key>UseEntirePage</key>
<false/>
<key>VPages</key>
<integer>1</integer>
<key>WindowInfo</key>
<dict>
<key>CurrentSheet</key>
<integer>0</integer>
<key>ExpandedCanvases</key>
<array>
<dict>
<key>name</key>
<string>Canvas 1</string>
</dict>
</array>
<key>Frame</key>
<string>{{300, 236}, {974, 874}}</string>
<key>ListView</key>
<true/>
<key>OutlineWidth</key>
<integer>142</integer>
<key>RightSidebar</key>
<false/>
<key>ShowRuler</key>
<true/>
<key>Sidebar</key>
<true/>
<key>SidebarWidth</key>
<integer>120</integer>
<key>VisibleRegion</key>
<string>{{0, 202}, {550, 469.33333333333337}}</string>
<key>Zoom</key>
<real>1.5</real>
<key>ZoomValues</key>
<array>
<array>
<string>Canvas 1</string>
<real>1.5</real>
<real>1</real>
</array>
</array>
</dict>
</dict>
</plist>

BIN
doc-src/_explicit.graffle/image3.icns Normal file
View File

Binary file not shown.

BIN
doc-src/_explicit.graffle/image6.tiff Normal file
View File

Binary file not shown.

1054
doc-src/_explicit_https.graffle/data.plist Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
doc-src/_explicit_https.graffle/image3.icns Normal file
View File

Binary file not shown.

BIN
doc-src/_explicit_https.graffle/image6.tiff Normal file
View File

Binary file not shown.

36
doc-src/_layout.html Normal file
View File

@ -0,0 +1,36 @@
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="@!urlTo(idxpath)!@">mitmproxy $!VERSION!$ docs</a>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span3">
<div class="well sidebar-nav">
$!navbar!$
</div>
</div>
<div class="span9">
<div class="page-header">
<h1>@!this.title!@</h1>
</div>
$!body!$
</div>
</div>
<hr>
<footer>
<p>@!copyright!@</p>
</footer>
</div>

48
doc-src/_nav.html Normal file
View File

@ -0,0 +1,48 @@
<ul class="nav nav-list">
$!nav(idxpath, this, state)!$
$!nav("install.html", this, state)!$
$!nav("howmitmproxy.html", this, state)!$
<li class="nav-header">Tools</li>
$!nav("mitmproxy.html", this, state)!$
$!nav("mitmdump.html", this, state)!$
<li class="nav-header">Features</li>
$!nav("anticache.html", this, state)!$
$!nav("clientreplay.html", this, state)!$
$!nav("filters.html", this, state)!$
$!nav("forwardproxy.html", this, state)!$
$!nav("proxyauth.html", this, state)!$
$!nav("replacements.html", this, state)!$
$!nav("serverreplay.html", this, state)!$
$!nav("setheaders.html", this, state)!$
$!nav("sticky.html", this, state)!$
$!nav("reverseproxy.html", this, state)!$
$!nav("upstreamcerts.html", this, state)!$
<li class="nav-header">Installing Certificates</li>
$!nav("ssl.html", this, state)!$
$!nav("certinstall/android.html", this, state)!$
$!nav("certinstall/firefox.html", this, state)!$
$!nav("certinstall/ios.html", this, state)!$
$!nav("certinstall/ios-simulator.html", this, state)!$
$!nav("certinstall/osx.html", this, state)!$
$!nav("certinstall/windows7.html", this, state)!$
<li class="nav-header">Transparent Proxying</li>
$!nav("transparent.html", this, state)!$
$!nav("transparent/linux.html", this, state)!$
$!nav("transparent/osx.html", this, state)!$
<li class="nav-header">Scripting mitmproxy</li>
$!nav("scripting/inlinescripts.html", this, state)!$
$!nav("scripting/libmproxy.html", this, state)!$
<li class="nav-header">Tutorials</li>
$!nav("tutorials/30second.html", this, state)!$
$!nav("tutorials/gamecenter.html", this, state)!$
$!nav("tutorials/transparent-dhcp.html", this, state)!$
<li class="nav-header">Hacking</li>
$!nav("dev/testing.html", this, state)!$
</ul>

771
doc-src/_transparent.graffle/data.plist Normal file
View File

@ -0,0 +1,771 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>ActiveLayerIndex</key>
<integer>0</integer>
<key>ApplicationVersion</key>
<array>
<string>com.omnigroup.OmniGraffle.MacAppStore</string>
<string>139.16</string>
</array>
<key>AutoAdjust</key>
<true/>
<key>BackgroundGraphic</key>
<dict>
<key>Bounds</key>
<string>{{0, 0}, {559.19998741149902, 782.79998779296875}}</string>
<key>Class</key>
<string>SolidGraphic</string>
<key>ID</key>
<integer>2</integer>
<key>Style</key>
<dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
<key>BaseZoom</key>
<integer>0</integer>
<key>CanvasOrigin</key>
<string>{0, 0}</string>
<key>ColumnAlign</key>
<integer>1</integer>
<key>ColumnSpacing</key>
<real>36</real>
<key>CreationDate</key>
<string>2013-01-02 19:31:53 +0000</string>
<key>Creator</key>
<string>Aldo Cortesi</string>
<key>DisplayScale</key>
<string>1.000 cm = 1.000 cm</string>
<key>GraphDocumentVersion</key>
<integer>8</integer>
<key>GraphicsList</key>
<array>
<dict>
<key>Bounds</key>
<string>{{101.18773396809897, 358.41662979125977}, {62, 12}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4079</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 2: Redirection}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{102.18775939941409, 405.16666666666663}, {78, 12}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4078</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 3: HTTP Request}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ControlPoints</key>
<array>
<string>{-29.333333333333343, 15.666671991348267}</string>
<string>{-14, -7.3333333333333712}</string>
</array>
<key>ID</key>
<integer>37</integer>
<key>Points</key>
<array>
<string>{196.99999491373691, 331.83332316080725}</string>
<string>{198.00000508626303, 402.49998982747394}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>Bezier</key>
<true/>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>LineType</key>
<integer>1</integer>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{205.34387397766082, 289.3333333333328}, {84, 52.666667938232422}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>4076</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Color</key>
<dict>
<key>b</key>
<string>0.547829</string>
<key>g</key>
<string>1</string>
<key>r</key>
<string>0.790866</string>
</dict>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf2 router}</string>
</dict>
</dict>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ID</key>
<integer>4075</integer>
<key>Points</key>
<array>
<string>{304.061024983724, 422.16667167345679}</string>
<string>{348.49764506022132, 422.16667167345696}</string>
<string>{365.83097839355469, 421.50000500679027}</string>
<string>{417.16433715820312, 421.16667175292963}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{321.11267089843761, 405.16706339518225}, {49, 12}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4067</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 4: Request}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{101.18773682912195, 295.66660690307623}, {62, 12}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>FontInfo</key>
<dict>
<key>Font</key>
<string>Helvetica</string>
<key>Size</key>
<real>12</real>
</dict>
<key>ID</key>
<integer>4058</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs20 \cf0 1: Connection}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ID</key>
<integer>4041</integer>
<key>Points</key>
<array>
<string>{85.896713256836037, 421.41666793823208}</string>
<string>{199.00002034505209, 421.16666666666669}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Class</key>
<string>LineGraphic</string>
<key>ID</key>
<integer>31</integer>
<key>Points</key>
<array>
<string>{84.896687825520857, 314.66666126251221}</string>
<string>{129.33330790201822, 314.66666126251238}</string>
<string>{146.66664123535153, 313.99999459584569}</string>
<string>{198, 313.66666134198505}</string>
</array>
<key>Style</key>
<dict>
<key>stroke</key>
<dict>
<key>HeadArrow</key>
<string>FilledArrow</string>
<key>Legacy</key>
<true/>
<key>TailArrow</key>
<string>0</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{430.83098347981803, 515.99999999999989}, {36, 14}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>ID</key>
<integer>4026</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf0 Server}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{40.499999999999993, 486.66666666666663}, {31, 14}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>FitText</key>
<string>YES</string>
<key>Flow</key>
<string>Resize</string>
<key>ID</key>
<integer>4025</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Pad</key>
<integer>0</integer>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf0 Client}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
<key>Wrap</key>
<string>NO</string>
</dict>
<dict>
<key>Bounds</key>
<string>{{417.16432189941418, 323.90565299479198}, {63.333332061767578, 185.52200317382812}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>4004</integer>
<key>ImageID</key>
<integer>6</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{205.34386889139773, 289.33333333333331}, {84, 248.66667175292969}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>4023</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Color</key>
<dict>
<key>b</key>
<string>0</string>
<key>g</key>
<string>0.463735</string>
<key>r</key>
<string>1</string>
</dict>
</dict>
</dict>
<key>Text</key>
<dict>
<key>Text</key>
<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
\f0\fs24 \cf2 mitmproxy}</string>
</dict>
</dict>
<dict>
<key>Bounds</key>
<string>{{4.6666666467984399, 351.33332316080771}, {102.66666412353516, 130.66667175292969}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
<integer>134</integer>
<key>ImageID</key>
<integer>3</integer>
<key>Shape</key>
<string>Rectangle</string>
<key>Style</key>
<dict>
<key>fill</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>shadow</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
<key>stroke</key>
<dict>
<key>Draws</key>
<string>NO</string>
</dict>
</dict>
</dict>
</array>
<key>GridInfo</key>
<dict/>
<key>GuidesLocked</key>
<string>NO</string>
<key>GuidesVisible</key>
<string>YES</string>
<key>HPages</key>
<integer>1</integer>
<key>ImageCounter</key>
<integer>7</integer>
<key>ImageLinkBack</key>
<array>
<dict/>
<dict/>
</array>
<key>ImageList</key>
<array>
<string>image6.tiff</string>
<string>image3.icns</string>
</array>
<key>KeepToScale</key>
<false/>
<key>Layers</key>
<array>
<dict>
<key>Lock</key>
<string>NO</string>
<key>Name</key>
<string>Layer 1</string>
<key>Print</key>
<string>YES</string>
<key>View</key>
<string>YES</string>
</dict>
</array>
<key>LayoutInfo</key>
<dict>
<key>Animate</key>
<string>NO</string>
<key>circoMinDist</key>
<real>18</real>
<key>circoSeparation</key>
<real>0.0</real>
<key>layoutEngine</key>
<string>dot</string>
<key>neatoSeparation</key>
<real>0.0</real>
<key>twopiSeparation</key>
<real>0.0</real>
</dict>
<key>LinksVisible</key>
<string>NO</string>
<key>MagnetsVisible</key>
<string>NO</string>
<key>MasterSheets</key>
<array/>
<key>ModificationDate</key>
<string>2013-01-03 04:13:10 +0000</string>
<key>Modifier</key>
<string>Aldo Cortesi</string>
<key>NotesVisible</key>
<string>NO</string>
<key>Orientation</key>
<integer>2</integer>
<key>OriginVisible</key>
<string>NO</string>
<key>PageBreaks</key>
<string>YES</string>
<key>PrintInfo</key>
<dict>
<key>NSBottomMargin</key>
<array>
<string>float</string>
<string>41</string>
</array>
<key>NSHorizonalPagination</key>
<array>
<string>coded</string>
<string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFxlwCG</string>
</array>
<key>NSLeftMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
<key>NSPaperSize</key>
<array>
<string>size</string>
<string>{595.19998741149902, 841.79998779296875}</string>
</array>
<key>NSPrintReverseOrientation</key>
<array>
<string>int</string>
<string>0</string>
</array>
<key>NSRightMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
<key>NSTopMargin</key>
<array>
<string>float</string>
<string>18</string>
</array>
</dict>
<key>PrintOnePage</key>
<false/>
<key>ReadOnly</key>
<string>NO</string>
<key>RowAlign</key>
<integer>1</integer>
<key>RowSpacing</key>
<real>36</real>
<key>SheetTitle</key>
<string>Canvas 1</string>
<key>SmartAlignmentGuidesActive</key>
<string>YES</string>
<key>SmartDistanceGuidesActive</key>
<string>YES</string>
<key>UniqueID</key>
<integer>1</integer>
<key>UseEntirePage</key>
<false/>
<key>VPages</key>
<integer>1</integer>
<key>WindowInfo</key>
<dict>
<key>CurrentSheet</key>
<integer>0</integer>
<key>ExpandedCanvases</key>
<array>
<dict>
<key>name</key>
<string>Canvas 1</string>
</dict>
</array>
<key>Frame</key>
<string>{{295, 141}, {974, 874}}</string>
<key>ListView</key>
<true/>
<key>OutlineWidth</key>
<integer>142</integer>
<key>RightSidebar</key>
<false/>
<key>ShowRuler</key>
<true/>
<key>Sidebar</key>
<true/>
<key>SidebarWidth</key>
<integer>120</integer>
<key>VisibleRegion</key>
<string>{{0, 208}, {550, 469.33333333333337}}</string>
<key>Zoom</key>
<real>1.5</real>
<key>ZoomValues</key>
<array>
<array>
<string>Canvas 1</string>
<real>1.5</real>
<real>1</real>
</array>
</array>
</dict>
</dict>
</plist>

BIN
doc-src/_transparent.graffle/image3.icns Normal file
View File

Binary file not shown.

BIN
doc-src/_transparent.graffle/image6.tiff Normal file
View File

Binary file not shown.

1096
doc-src/_transparent_https.graffle/data.plist Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
doc-src/_transparent_https.graffle/image3.icns Normal file
View File

Binary file not shown.

BIN
doc-src/_transparent_https.graffle/image6.tiff Normal file
View File

Binary file not shown.

42
doc-src/_websitelayout.html Normal file
View File

@ -0,0 +1,42 @@
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="@!urlTo(idxpath)!@">mitmproxy</a>
<div class="nav">
<ul class="nav">
<li $!'class="active"' if this.match("/index.html", True) else ""!$> <a href="@!top!@/index.html">home</a> </li>
<li $!'class="active"' if this.under("/doc") else ""!$><a href="@!top!@/doc/index.html">docs</a></li>
<li $!'class="active"' if this.under("/about.html") else ""!$><a href="@!top!@/about.html">about</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span3">
<div class="well sidebar-nav">
$!navbar!$
</div>
</div>
<div class="span9">
<div class="page-header">
<h1>@!this.title!@</h1>
</div>
$!body!$
</div>
</div>
<hr>
<footer>
<p>@!copyright!@</p>
</footer>
</div>

BIN
doc-src/certinstall/android-settingssecurityinstallca.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
doc-src/certinstall/android-settingssecuritymenu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

BIN
doc-src/certinstall/android-settingssecurityuserinstalledca.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
doc-src/certinstall/android-shellwgetmitmproxyca.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

45
doc-src/certinstall/android.html Normal file
View File

@ -0,0 +1,45 @@
The proxy situation on Android is [an
embarrasment](http://code.google.com/p/android/issues/detail?id=1273). It's
scarcely credible, but Android didn't have a global proxy setting at all until
quite recently, and it's still not supported on many common Android versions.
In the meantime the app ecosystem has grown used to life without this basic
necessity, and many apps merrily ignore it even if it's there. This situation
is improving, but in many circumstances using [transparent
mode](@!urlTo("transparent.html")!@) is mandatory for testing Android apps.
We used an Asus Transformer Prime TF201 with Android 4.0.3 in the examples
below - your device may differ, but the broad process should be similar.
## Getting the certificate onto the device
First we need to get the __mitmproxy-ca-cert.cer__ file into the
__/sdcard__ folder on the device (/sdcard/Download on older devices). There are a number of ways to do
this. If you have the Android Developer Tools installed, you can use [__adb
push__](http://developer.android.com/tools/help/adb.html) to accomplish this.
Depending on your device, you could also transfer the file using external media
like an SD Card. In this example, we're using wget from within a terminal
emulator to transfer the certificate from a local HTTP server:
<img src="android-shellwgetmitmproxyca.png"/>
## Installing the certificate
Once we have the certificate on the local disk, we need to import it into the
list of trusted CAs. Go to Settings -&gt; Security -&gt; Credential Storage,
and select "Install from storage":
<img src="android-settingssecuritymenu.png"/>
The certificate in /sdcard is automatically located and offered for
installation. Installing the cert will delete the download file from the local
disk:
<img src="android-settingssecurityinstallca.png"/>
Afterwards, you should see the certificate listed in the Trusted Credentials
store:
<img src="android-settingssecurityuserinstalledca.png"/>

23
doc-src/certinstall/firefox.html Normal file
View File

@ -0,0 +1,23 @@
How to install the __mitmproxy__ certificate authority in Firefox:
<ol class="tlist">
<li> If needed, copy the ~/.mitmproxy/mitmproxy-ca-cert.pem file to the target. </li>
<li>Open preferences, click on "Advanced", then select"Encryption":
<img src="@!urlTo('firefox3.jpg')!@"/>
</li>
<li> Click "View Certificates", "Import", and select the certificate file:
<img src="@!urlTo('firefox3-import.jpg')!@"/>
</li>
<li>Tick "Trust this CS to identify web sites", and click "Ok":
<img src="@!urlTo('firefox3-trust.jpg')!@"/>
</li>
<li> You should now see the mitmproxy certificate listed in the Authorities
tab.</li>
</ol>

10
doc-src/certinstall/index.py Normal file
View File

@ -0,0 +1,10 @@
from countershape import Page
pages = [
Page("firefox.html", "Firefox"),
Page("osx.html", "OSX"),
Page("windows7.html", "Windows 7"),
Page("ios.html", "IOS"),
Page("ios-simulator.html", "IOS Simulator"),
Page("android.html", "Android"),
]

23
doc-src/certinstall/ios-simulator.html Normal file
View File

@ -0,0 +1,23 @@
How to install the __mitmproxy__ certificate authority in the IOS simulator:
<ol class="tlist">
<li> First, check out the <a
href="https://github.com/ADVTOOLS/ADVTrustStore">ADVTrustStore</a> tool
from github.</li>
<li> Now, run the following command:
<pre class="terminal">./iosCertTrustManager.py -a ~/.mitmproxy/mitmproxy-ca-cert.pem</pre>
</li>
</ol>
Note that although the IOS simulator has its own certificate store, it shares
the proxy settings of the host operating system. You will therefore to have
configure your OSX host's proxy settings to use the mitmproxy instance you want
to test with.

21
doc-src/certinstall/ios.html Normal file
View File

@ -0,0 +1,21 @@
How to install the __mitmproxy__ certificate authority on IOS devices:
<ol class="tlist">
<li>Set up the Mail app on the device to receive email.</li>
<li>Mail the mitmproxy-ca-cert.pem file to the device, and tap on the attachment.</li>
<li>You will be prompted to install a profile. Click "Install":
<img src="@!urlTo('ios-profile.png')!@"/></li>
<li>Accept the warning by clicking "Install" again:
<img src="@!urlTo('ios-warning.png')!@"/></li>
<li>The certificate should now be trusted:
<img src="@!urlTo('ios-installed.png')!@"/></li>
</ol>

16
doc-src/certinstall/osx.html Normal file
View File

@ -0,0 +1,16 @@
How to install the __mitmproxy__ certificate authority in OSX:
<ol class="tlist">
<li>Open Finder, and double-click on the mitmproxy-ca-cert.pem file.</li>
<li>You will be prompted to add the certificate. Click "Always Trust":
<img src="@!urlTo('osx-addcert-alwaystrust.png')!@"/>
</li>
<li> You may be prompted for your password. You should now see the
mitmproxy cert listed under "Certificates".</li>
</ol>

32
doc-src/certinstall/windows7.html Normal file
View File

@ -0,0 +1,32 @@
How to install the __mitmproxy__ certificate authority in Windows 7:
<ol class="tlist">
<li> Copy the ~/.mitmproxy/mitmproxy-ca-cert.p12 file to the target system. </li>
<li>
Double-click the certificate file. You should see a certificate import wizard:
<img src="@!urlTo('win7-wizard.png')!@"/>
</li>
<li>
Click "Next" until you're prompted for the certificate store:
<img src="@!urlTo('win7-certstore.png')!@"/>
</li>
<li>
<p>Select "Place all certificates in the following store", and select "Trusted Root Certification Authorities":</p>
<img src="@!urlTo('win7-certstore-trustedroot.png')!@"/>
</li>
<li> Click "Next" and "Finish". </li>
</ol>

52
doc-src/dev/addingviews.html Normal file
View File

@ -0,0 +1,52 @@
As discussed in [the Flow View section of the mitmproxy
overview](@!urlTo("mitmproxy.html")!@), 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.
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.

6
doc-src/dev/index.py Normal file
View File

@ -0,0 +1,6 @@
from countershape import Page
pages = [
Page("testing.html", "Testing"),
# Page("addingviews.html", "Writing Content Views"),
]

43
doc-src/dev/testing.html Normal file
View File

@ -0,0 +1,43 @@
All the mitmproxy projects strive to maintain 100% code coverage. In general,
patches and pull requests will be declined unless they're accompanied by a
suitable extension to the test suite.
Our tests are written for the [nose](https://nose.readthedocs.org/en/latest/).
At the point where you send your pull request, a command like this:
<pre class="terminal">
> nosetests --with-cov --cov-report term-missing ./test
</pre>
Should give output something like this:
<pre class="terminal">
> ---------- coverage: platform darwin, python 2.7.2-final-0 --
> Name Stmts Miss Cover Missing
> ----------------------------------------------------
> libmproxy/__init__ 0 0 100%
> libmproxy/app 4 0 100%
> libmproxy/cmdline 100 0 100%
> libmproxy/controller 69 0 100%
> libmproxy/dump 150 0 100%
> libmproxy/encoding 39 0 100%
> libmproxy/filt 201 0 100%
> libmproxy/flow 891 0 100%
> libmproxy/proxy 427 0 100%
> libmproxy/script 27 0 100%
> libmproxy/utils 133 0 100%
> libmproxy/version 4 0 100%
> ----------------------------------------------------
> TOTAL 2045 0 100%
> ----------------------------------------------------
> Ran 251 tests in 11.864s
</pre>
There are exceptions to the coverage requirement - for instance, much of the
console interface code can't sensibly be unit tested. These portions are
excluded from coverage analysis either in the **.coveragerc** file, or using
**#pragma no-cover** directives. To keep our coverage analysis relevant, we use
these measures as sparingly as possible.

BIN
doc-src/explicit.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

BIN
doc-src/explicit_https.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

18
doc-src/features/anticache.html Normal file
View File

@ -0,0 +1,18 @@
When the __anticache__ option is passed to mitmproxy, it removes headers
(__if-none-match__ and __if-modified-since__) that might elicit a
304-not-modified response from the server. This is useful when you want to make
sure you capture an HTTP exchange in its totality. It's also often used during
[client replay](@!urlTo("clientreplay.html")!@), when you want to make sure the
server responds with complete data.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th> <td>--anticache</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>o</b> then <b>a</b></td>
</tr>
</tbody>
</table>

22
doc-src/features/clientreplay.html Normal file
View File

@ -0,0 +1,22 @@
Client-side replay does what it says on the tin: you provide a previously saved
HTTP conversation, and mitmproxy replays the client requests one by one. Note
that mitmproxy serializes the requests, waiting for a response from the server
before starting the next request. This might differ from the recorded
conversation, where requests may have been made concurrently.
You may want to use client-side replay in conjunction with the
[anticache](@!urlTo("anticache.html")!@) option, to make sure the server
responds with complete data.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th> <td>-c path</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>c</b></td>
</tr>
</tbody>
</table>

36
doc-src/features/filters.html Normal file
View File

@ -0,0 +1,36 @@
Many commands in __mitmproxy__ and __mitmdump__ take a filter expression.
Filter expressions consist of the following operators:
<table class="table">
<tbody>
<!--(for i in filt_help)-->
<tr>
<td class="filt_cmd">@!i[0]!@</td>
<td class="filt_help">@!i[1]!@</td>
</tr>
<!--(end)-->
</tbody>
</table>
- Regexes are Python-style
- Regexes can be specified as quoted strings
- Header matching (~h, ~hq, ~hs) is against a string of the form "name: value".
- Strings with no operators are matched against the request URL.
- The default binary operator is &amp;.
Examples
========
URL containing "google.com":
google\.com
Requests whose body contains the string "test":
~q ~b test
Anything but requests with a text/html content type:
!(~q & ~t \"text/html\")

16
doc-src/features/forwardproxy.html Normal file
View File

@ -0,0 +1,16 @@
In this mode, mitmproxy accepts proxy requests and unconditionally forwards all
requests to a specified upstream server. This is in contrast to <a
href="@!urlTo("reverseproxy.html")!@">reverse proxy mode</a>, in which
mitmproxy forwards ordinary HTTP requests to an upstream server.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th> <td>-F http[s]://hostname[:port]</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>F</b></td>
</tr>
</tbody>
</table>

15
doc-src/features/index.py Normal file
View File

@ -0,0 +1,15 @@
from countershape import Page
pages = [
Page("anticache.html", "Anticache"),
Page("clientreplay.html", "Client-side replay"),
Page("filters.html", "Filter expressions"),
Page("forwardproxy.html", "Forward proxy mode"),
Page("setheaders.html", "Set Headers"),
Page("serverreplay.html", "Server-side replay"),
Page("sticky.html", "Sticky cookies and auth"),
Page("proxyauth.html", "Proxy Authentication"),
Page("replacements.html", "Replacements"),
Page("reverseproxy.html", "Reverse proxy mode"),
Page("upstreamcerts.html", "Upstream Certs"),
]

26
doc-src/features/proxyauth.html Normal file
View File

@ -0,0 +1,26 @@
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. The
proxy auth options are ignored if the proxy is in transparent or reverse proxy
mode.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th>
<td>
<ul>
<li>--nonanonymous</li>
<li>--singleuser USER</li>
<li>--htpasswd PATH</li>
</ul>
</td>
</tr>
</tbody>
</table>

74
doc-src/features/replacements.html Normal file
View File

@ -0,0 +1,74 @@
Mitmproxy lets you specify an arbitrary number of patterns that define text
replacements within flows. Each pattern has 3 components: a filter that defines
which flows a replacement applies to, a regular expression that defines what
gets replaced, and a target value that defines what is substituted in.
Replace hooks fire when either a client request or a server response is
received. Only the matching flow component is affected: so, for example, if a
replace hook is triggered on server response, the replacement is only run on
the Response object leaving the Request intact. You control whether the hook
triggers on the request, response or both using the filter pattern. If you need
finer-grained control than this, it's simple to create a script using the
replacement API on Flow components.
Replacement hooks are extremely handy in interactive testing of applications.
For instance you can use a replace hook to replace the text "XSS" with a
complicated XSS exploit, and then "inject" the exploit simply by interacting
with the application through the browser. When used with tools like Firebug and
mitmproxy's own interception abilities, replacement hooks can be an amazingly
flexible and powerful feature.
## On the command-line
The replacement hook command-line options use a compact syntax to make it easy
to specify all three components at once. The general form is as follows:
/patt/regex/replacement
Here, __patt__ is a mitmproxy filter expression, __regex__ is a valid Python
regular expression, and __replacement__ is a string literal. The first
character in the expression (__/__ in this case) defines what the separation
character is. Here's an example of a valid expression that replaces "foo" with
"bar" in all requests:
:~q:foo:bar
In practice, it's pretty common for the replacement literal to be long and
complex. For instance, it might be an XSS exploit that weighs in at hundreds or
thousands of characters. To cope with this, there's a variation of the
replacement hook specifier that lets you load the replacement text from a file.
So, you might start __mitmdump__ as follows:
<pre class="terminal">
mitmdump --replace-from-file :~q:foo:~/xss-exploit
</pre>
This will load the replacement text from the file __~/xss-exploit__.
Both the _--replace_ and _--replace-from-file_ flags can be passed multiple
times.
## Interactively
The _R_ shortcut key in mitmproxy lets you add and edit replacement hooks using
a built-in editor. The context-sensitive help (_h_) has complete usage
information.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th>
<td>
<ul>
<li>--replace</li>
<li>--replace-from-file</li>
</ul>
</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>R</b></td>
</tr>
</tbody>
</table>

19
doc-src/features/reverseproxy.html Normal file
View File

@ -0,0 +1,19 @@
In reverse proxy mode, mitmproxy accepts standard HTTP requests and forwards
them to the specified upstream server. This is in contrast to <a
href="@!urlTo("forwardproxy.html")!@">forward proxy mode</a>, in which
mitmproxy forwards HTTP proxy requests to an upstream server.
Note that the displayed URL for flows in this mode will use the value of the
__Host__ header field from the request, not the reverse proxy server.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th> <td>-P http[s]://hostname[:port]</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>P</b></td>
</tr>
</tbody>
</table>

35
doc-src/features/serverreplay.html Normal file
View File

@ -0,0 +1,35 @@
- command-line: _-S path_
- mitmproxy shortcut: _S_
Server-side replay lets us replay server responses from a saved HTTP
conversation.
Matching requests with responses
--------------------------------
By default, __mitmproxy__ excludes request headers when matching incoming
requests with responses from the replay file. This works in most circumstances,
and makes it possible to replay server responses in situations where request
headers would naturally vary, e.g. using a different user agent. The _--rheader
headername_ command-line option allows you to override this behaviour by
specifying individual headers that should be included in matching.
Response refreshing
-------------------
Simply replaying server responses without modification will often result in
unexpected behaviour. For example cookie timeouts that were in the future at
the time a conversation was recorded might be in the past at the time it is
replayed. By default, __mitmproxy__ refreshes server responses before sending
them to the client. The __date__, __expires__ and __last-modified__ headers are
all updated to have the same relative time offset as they had at the time of
recording. So, if they were in the past at the time of recording, they will be
in the past at the time of replay, and vice versa. Cookie expiry times are
updated in a similar way.
You can turn off response refreshing using the _--norefresh_ argument, or using
the _o_ options shortcut within __mitmproxy__.

18
doc-src/features/setheaders.html Normal file
View File

@ -0,0 +1,18 @@
This feature lets you specify a set of headers to be added to requests or
responses, based on a filter pattern. You can specify these either on the
command-line, or through an interactive editor in mitmproxy.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th>
<td>
--setheader PATTERN
</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>H</b></td>
</tr>
</tbody>
</table>

60
doc-src/features/sticky.html Normal file
View File

@ -0,0 +1,60 @@
## Sticky cookies
When the sticky cookie option is set, __mitmproxy__ will add the cookie most
recently set by the server to any cookie-less request. Consider a service that
sets a cookie to track the session after authentication. Using sticky cookies,
you can fire up mitmproxy, and authenticate to a service as you usually would
using a browser. After authentication, you can request authenticated resources
through mitmproxy as if they were unauthenticated, because mitmproxy will
automatically add the session tracking cookie to requests. Among other things,
this lets you script interactions with authenticated resources (using tools
like wget or curl) without having to worry about authentication.
Sticky cookies are especially powerful when used in conjunction with [client
replay](@!urlTo("clientreplay.html")!@) - you can record the authentication
process once, and simply replay it on startup every time you need to interact
with the secured resources.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th>
<td>
<ul>
<li>-t FILTER</li>
</ul>
</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>t</b></td>
</tr>
</tbody>
</table>
## Sticky auth
The sticky auth option is analogous to the sticky cookie option, in that HTTP
__Authorization__ headers are simply replayed to the server once they have been
seen. This is enough to allow you to access a server resource using HTTP Basic
authentication through the proxy. Note that __mitmproxy__ doesn't (yet) support
replay of HTTP Digest authentication.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th>
<td>
<ul>
<li>-u FILTER</li>
</ul>
</td>
</tr>
<tr>
<th>mitmproxy shortcut</th> <td><b>u</b></td>
</tr>
</tbody>
</table>

21
doc-src/features/upstreamcerts.html Normal file
View File

@ -0,0 +1,21 @@
When mitmproxy receives a connection destined for an SSL-protected service, it
freezes the connection before reading its request data, and makes a connection
to the upstream server to "sniff" the contents of its SSL certificate. The
information gained - the __Common Name__ and __Subject Alternative Names__ - is
then used to generate the interception certificate, which is sent to the client
so the connection can continue.
This rather intricate little dance lets us seamlessly generate correct
certificates even if the client has specifed only an IP address rather than the
hostname. It also means that we don't need to sniff additional data to generate
certs in transparent mode.
Upstream cert sniffing is on by default, and can optionally be turned off.
<table class="table">
<tbody>
<tr>
<th width="20%">command-line</th> <td>--no-upstream-cert</td>
</tr>
</tbody>
</table>

360
doc-src/howmitmproxy.html Normal file
View File

@ -0,0 +1,360 @@
Mitmproxy is an enormously flexible tool. Knowing exactly how the proxying
process works will help you deploy it creatively, and take into account its
fundamental assumptions and how to work around them. This document explains
mitmproxy's proxy mechanism in detail, starting with the simplest unencrypted
explicit proxying, and working up to the most complicated interaction -
transparent proxying of SSL-protected traffic[^ssl] in the presence of
[SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).
<div class="page-header">
<h1>Explicit HTTP</h1>
</div>
Configuring the client to use mitmproxy as an explicit proxy is the simplest
and most reliable way to intercept traffic. The proxy protocol is codified in
the [HTTP RFC](http://www.ietf.org/rfc/rfc2068.txt), so the behaviour of both
the client and the server is well defined, and usually reliable. In the
simplest possible interaction with mitmproxy, a client connects directly to the
proxy, and makes a request that looks like this:
<pre>GET http://example.com/index.html HTTP/1.1</pre>
This is a proxy GET request - an extended form of the vanilla HTTP GET request
that includes a schema and host specification, and it includes all the
information mitmproxy needs to proceed.
<img src="explicit.png"/>
<table class="table">
<tbody>
<tr>
<td><b>1</b></td>
<td>The client connects to the proxy and makes a request.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>Mitmproxy connects to the upstream server and simply forwards
the request on.</td>
</tr>
</tbody>
</table>
<div class="page-header">
<h1>Explicit HTTPS</h1>
</div>
The process for an explicitly proxied HTTPS connection is quite different. The
client connects to the proxy and makes a request that looks like this:
<pre>CONNECT example.com:443 HTTP/1.1</pre>
A conventional proxy can neither view nor manipulate an SSL-encrypted data
stream, so a CONNECT request simply asks the proxy to open a pipe between the
client and server. The proxy here is just a facilitator - it blindly forwards
data in both directions without knowing anything about the contents. The
negotiation of the SSL connection happens over this pipe, and the subsequent
flow of requests and responses are completely opaque to the proxy.
## The MITM in mitmproxy
This is where mitmproxy's fundamental trick comes into play. The MITM in its
name stands for Man-In-The-Middle - a reference to the process we use to
intercept and interfere with these theoretically opaque data streams. The basic
idea is to pretend to be the server to the client, and pretend to be the client
to the server, while we sit in the middle decoding traffic from both sides. The
tricky part is that the [Certificate
Authority](http://en.wikipedia.org/wiki/Certificate_authority) system is
designed to prevent exactly this attack, by allowing a trusted third-party to
cryptographically sign a server's SSL certificates to verify that they are
legit. If this signature doesn't match or is from a non-trusted party, a secure
client will simply drop the connection and refuse to proceed. Despite the many
shortcomings of the CA system as it exists today, this is usually fatal to
attempts to MITM an SSL connection for analysis. Our answer to this conundrum
is to become a trusted Certificate Authority ourselves. Mitmproxy includes a
full CA implementation that generates interception certificates on the fly. To
get the client to trust these certificates, we [register mitmproxy as a trusted
CA with the device manually](@!urlTo("ssl.html")!@).
## Complication 1: What's the remote hostname?
To proceed with this plan, we need to know the domain name to use in the
interception certificate - the client will verify that the certificate is for
the domain it's connecting to, and abort if this is not the case. At first
blush, it seems that the CONNECT request above gives us all we need - in this
example, both of these values are "example.com". But what if the client had
initiated the connection as follows:
<pre>CONNECT 10.1.1.1:443 HTTP/1.1</pre>
Using the IP address is perfectly legitimate because it gives us enough
information to initiate the pipe, even though it doesn't reveal the remote
hostname.
Mitmproxy has a cunning mechanism that smooths this over - [upstream
certificate sniffing](@!urlTo("features/upstreamcerts.html")!@). As soon as we
see the CONNECT request, we pause the client part of the conversation, and
initiate a simultaneous connection to the server. We complete the SSL handshake
with the server, and inspect the certificates it used. Now, we use the Common
Name in the upstream SSL certificates to generate the dummy certificate for the
client. Voila, we have the correct hostname to present to the client, even if
it was never specified.
## Complication 2: Subject Alternative Name
Enter the next complication. Sometimes, the certificate Common Name is not, in
fact, the hostname that the client is connecting to. This is because of the
optional [Subject Alternative
Name](http://en.wikipedia.org/wiki/SubjectAltName) field in the SSL certificate
that allows an arbitrary number of alternative domains to be specified. If the
expected domain matches any of these, the client will proceed, even though the
domain doesn't match the certificate Common Name. The answer here is simple:
when extract the CN from the upstream cert, we also extract the SANs, and add
them to the generated dummy certificate.
## Complication 3: Server Name Indication
One of the big limitations of vanilla SSL is that each certificate requires its
own IP address. This means that you couldn't do virtual hosting where multiple
domains with independent certificates share the same IP address. In a world
with a rapidly shrinking IPv4 address pool this is a problem, and we have a
solution in the form of the [Server Name
Indication](http://en.wikipedia.org/wiki/Server_Name_Indication) extension to
the SSL and TLS protocols. This lets the client specify the remote server name
at the start of the SSL handshake, which then lets the server select the right
certificate to complete the process.
SNI breaks our upstream certificate sniffing process, because when we connect
without using SNI, we get served a default certificate that may have nothing to
do with the certificate expected by the client. The solution is another tricky
complication to the client connection process. After the client connects, we
allow the SSL handshake to continue until just _after_ the SNI value has been
passed to us. Now we can pause the conversation, and initiate an upstream
connection using the correct SNI value, which then serves us the correct
upstream certificate, from which we can extract the expected CN and SANs.
There's another wrinkle here. Due to a limitation of the SSL library mitmproxy
uses, we can't detect that a connection _hasn't_ sent an SNI request until it's
too late for upstream certificate sniffing. In practice, we therefore make a
vanilla SSL connection upstream to sniff non-SNI certificates, and then discard
the connection if the client sends an SNI notification. If you're watching your
traffic with a packet sniffer, you'll see two connections to the server when an
SNI request is made, the first of which is immediately closed after the SSL
handshake. Luckily, this is almost never an issue in practice.
## Putting it all together
Lets put all of this together into the complete explicitly proxied HTTPS flow.
<img src="explicit_https.png"/>
<table class="table">
<tbody>
<tr>
<td><b>1</b></td>
<td>The client makes a connection to mitmproxy, and issues an HTTP
CONNECT request.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>Mitmproxy responds with a 200 Connection Established, as if it
has set up the CONNECT pipe.</td>
</tr>
<tr>
<td><b>3</b></td>
<td>The client believes it's talking to the remote server, and
initiates the SSL connection. It uses SNI to indicate the hostname
it is connecting to.</td>
</tr>
<tr>
<td><b>4</b></td>
<td>Mitmproxy connects to the server, and establishes an SSL
connection using the SNI hostname indicated by the client.</td>
</tr>
<tr>
<td><b>5</b></td>
<td>The server responds with the matching SSL certificate, which
contains the CN and SAN values needed to generate the interception
certificate.</td>
</tr>
<tr>
<td><b>6</b></td>
<td>Mitmproxy generates the interception cert, and continues the
client SSL handshake paused in step 3.</td>
</tr>
<tr>
<td><b>7</b></td>
<td>The client sends the request over the established SSL
connection.</td>
</tr>
<tr>
<td><b>7</b></td>
<td>Mitmproxy passes the request on to the server over the SSL
connection initiated in step 4.</td>
</tr>
</tbody>
</table>
<div class="page-header">
<h1>Transparent HTTP</h1>
</div>
When a transparent proxy is used, the HTTP/S connection is redirected into a
proxy at the network layer, without any client configuration being required.
This makes transparent proxying ideal for those situations where you can't
change client behaviour - proxy-oblivious Android applications being a common
example.
To achieve this, we need to introduce two extra components. The first is a
redirection mechanism that transparently reroutes a TCP connection destined for
a server on the Internet to a listening proxy server. This usually takes the
form of a firewall on the same host as the proxy server -
[iptables](http://www.netfilter.org/) on Linux or
[pf](http://en.wikipedia.org/wiki/PF_\(firewall\)) on OSX. Once the client has
initiated the connection, it makes a vanilla HTTP request, which might look
something like this:
<pre>GET /index.html HTTP/1.1</pre>
Note that this request differs from the explicit proxy variation, in that it
omits the scheme and hostname. How, then, do we know which upstream host to
forward the request to? The routing mechanism that has performed the
redirection keeps track of the original destination for us. Each routing
mechanism has a different way of exposing this data, so this introduces the
second component required for working transparent proxying: a host module that
knows how to retrieve the original destination address from the router. In
mitmproxy, this takes the form of a built-in set of
[modules](https://github.com/mitmproxy/mitmproxy/tree/master/libmproxy/platform)
that know how to talk to each platform's redirection mechanism. Once we have
this information, the process is fairly straight-forward.
<img src="transparent.png"/>
<table class="table">
<tbody>
<tr>
<td><b>1</b></td>
<td>The client makes a connection to the server.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>The router redirects the connection to mitmproxy, which is
typically listening on a local port of the same host. Mitmproxy
then consults the routing mechanism to establish what the original
destination was.</td>
</tr>
<tr>
<td><b>3</b></td>
<td>Now, we simply read the client's request...</td>
</tr>
<tr>
<td><b>4</b></td>
<td>... and forward it upstream.</td>
</tr>
</tbody>
</table>
<div class="page-header">
<h1>Transparent HTTPS</h1>
</div>
The first step is to determine whether we should treat an incoming connection
as HTTPS. The mechanism for doing this is simple - we use the routing mechanism
to find out what the original destination port is. By default, we treat all
traffic destined for ports 443 and 8443 as SSL.
From here, the process is a merger of the methods we've described for
transparently proxying HTTP, and explicitly proxying HTTPS. We use the routing
mechanism to establish the upstream server address, and then proceed as for
explicit HTTPS connections to establish the CN and SANs, and cope with SNI.
<img src="transparent_https.png"/>
<table class="table">
<tbody>
<tr>
<td><b>1</b></td>
<td>The client makes a connection to the server.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>The router redirects the connection to mitmproxy, which is
typically listening on a local port of the same host. Mitmproxy
then consults the routing mechanism to establish what the original
destination was.</td>
</tr>
<tr>
<td><b>3</b></td>
<td>The client believes it's talking to the remote server, and
initiates the SSL connection. It uses SNI to indicate the hostname
it is connecting to.</td>
</tr>
<tr>
<td><b>4</b></td>
<td>Mitmproxy connects to the server, and establishes an SSL
connection using the SNI hostname indicated by the client.</td>
</tr>
<tr>
<td><b>5</b></td>
<td>The server responds with the matching SSL certificate, which
contains the CN and SAN values needed to generate the interception
certificate.</td>
</tr>
<tr>
<td><b>6</b></td>
<td>Mitmproxy generates the interception cert, and continues the
client SSL handshake paused in step 3.</td>
</tr>
<tr>
<td><b>7</b></td>
<td>The client sends the request over the established SSL
connection.</td>
</tr>
<tr>
<td><b>7</b></td>
<td>Mitmproxy passes the request on to the server over the SSL
connection initiated in step 4.</td>
</tr>
</tbody>
</table>
[^ssl]: I use "SSL" to refer to both SSL and TLS in the generic sense, unless otherwise specified.

4
doc-src/index.html Normal file
View File

@ -0,0 +1,4 @@
@!index_contents!@

89
doc-src/index.py Normal file
View File

@ -0,0 +1,89 @@
import os, sys, datetime
import countershape
from countershape import Page, Directory, PythonModule, markup, model
import countershape.template
sys.path.insert(0, "..")
from libmproxy import filt, version
MITMPROXY_SRC = os.environ.get("MITMPROXY_SRC", os.path.abspath(".."))
ns.VERSION = version.VERSION
if ns.options.website:
ns.idxpath = "doc/index.html"
this.layout = countershape.Layout("_websitelayout.html")
else:
ns.idxpath = "index.html"
this.layout = countershape.Layout("_layout.html")
ns.title = countershape.template.Template(None, "<h1>@!this.title!@</h1>")
this.titlePrefix = "%s - " % version.NAMEVERSION
this.markup = markup.Markdown(extras=["footnotes"])
ns.docMaintainer = "Aldo Cortesi"
ns.docMaintainerEmail = "aldo@corte.si"
ns.copyright = u"\u00a9 mitmproxy project, %s" % datetime.date.today().year
def mpath(p):
p = os.path.join(MITMPROXY_SRC, p)
return os.path.expanduser(p)
with open(mpath("README.mkd")) as f:
readme = f.read()
ns.index_contents = readme.split("\n", 1)[1] #remove first line (contains build status)
def example(s):
d = file(mpath(s)).read().rstrip()
extemp = """<div class="example">%s<div class="example_legend">(%s)</div></div>"""
return extemp%(countershape.template.Syntax("py")(d), s)
ns.example = example
filt_help = []
for i in filt.filt_unary:
filt_help.append(
("~%s"%i.code, i.help)
)
for i in filt.filt_rex:
filt_help.append(
("~%s regex"%i.code, i.help)
)
for i in filt.filt_int:
filt_help.append(
("~%s int"%i.code, i.help)
)
filt_help.sort()
filt_help.extend(
[
("!", "unary not"),
("&", "and"),
("|", "or"),
("(...)", "grouping"),
]
)
ns.filt_help = filt_help
def nav(page, current, state):
if current.match(page, False):
pre = '<li class="active">'
else:
pre = "<li>"
p = state.application.getPage(page)
return pre + '<a href="%s">%s</a></li>'%(model.UrlTo(page), p.title)
ns.nav = nav
ns.navbar = countershape.template.File(None, "_nav.html")
pages = [
Page("index.html", "Introduction"),
Page("install.html", "Installation"),
Page("mitmproxy.html", "mitmproxy"),
Page("mitmdump.html", "mitmdump"),
Page("howmitmproxy.html", "How mitmproxy works"),
Page("ssl.html", "Overview"),
Directory("certinstall"),
Directory("scripting"),
Directory("tutorials"),
Page("transparent.html", "Overview"),
Directory("transparent"),
]

52
doc-src/install.html Normal file
View File

@ -0,0 +1,52 @@
The preferred way to install mitmproxy - whether you're installing the latest
release or from source - is to use [pip](http://www.pip-installer.org/). If you
don't already have pip on your system, you can find installation instructions
[here](http://www.pip-installer.org/en/latest/installing.html).
## Installing the latest release
A single command will download and install the latest release of mitmproxy,
along with all its dependencies:
<pre class="terminal">
pip install mitmproxy
</pre>
## Installing from source
When installing from source, the easiest method is still to use pip. In this
case run:
<pre class="terminal">
pip install /path/to/source
</pre>
Note that if you're installing current git master, you will also have to
install the current git master of [netlib](http://github.com/mitmproxy/netlib) by
hand.
## OSX
- If you're running a Python interpreter installed with homebrew (or similar),
you may have to install some dependencies by hand.
- Make sure that XCode is installed from the App Store, and that the
command-line tools have been downloaded (XCode/Preferences/Downloads).
- Now use __pip__ to do the installation, as above.
There are a few bits of customization you might want to do to make mitmproxy
comfortable to use on OSX. The default color scheme is optimized for a dark
background terminal, but you can select a palette for a light terminal
background with the --palette option. You can use the OSX <b>open</b> program
to create a simple and effective <b>~/.mailcap</b> file to view request and
response bodies:
<pre class="terminal">
application/*; /usr/bin/open -Wn %s
audio/*; /usr/bin/open -Wn %s
image/*; /usr/bin/open -Wn %s
video/*; /usr/bin/open -Wn %s
</pre>

68
doc-src/mitmdump.html Normal file
View File

@ -0,0 +1,68 @@
__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 _--help_ flag output for complete
documentation.
# Examples
## Saving traffic
<pre class="terminal">
> mitmdump -w outfile
</pre>
Start up mitmdump in proxy mode, and write all traffic to __outfile__.
## Filtering saved traffic
<pre class="terminal">
> mitmdump -nr infile -w outfile "~m post"
</pre>
Start mitmdump without binding to the proxy port (_-n_), read all flows from
infile, apply the specified filter expression (only match POSTs), and write to
outfile.
## Client replay
<pre class="terminal">
> mitmdump -nc outfile
</pre>
Start mitmdump without binding to the proxy port (_-n_), then replay all
requests from outfile (_-c filename_). Flags combine in the obvious way, so
you can replay requests from one file, and write the resulting flows to
another:
<pre class="terminal">
> mitmdump -nc srcfile -w dstfile
</pre>
See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
## Running a script
<pre class="terminal">
> mitmdump -s examples/add_header.py
</pre>
This runs the __add_header.py__ example script, which simply adds a new header
to all responses.
## Scripted data transformation
<pre class="terminal">
> mitmdump -ns examples/add_header.py -r srcfile -w dstfile
</pre>
This command loads flows from __srcfile__, transforms it according to the
specified script, then writes it back to __dstfile__.

115
doc-src/mitmproxy.html Normal file
View File

@ -0,0 +1,115 @@
__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 _?_ 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.
<img src="@!urlTo('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 _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 _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:
<img src="@!urlTo('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 _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 _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 (_e_ for edit, then _h_ for headers in flow view)
- Editing a query string (_e_ for edit, then _q_ for query in flow view)
- Editing a URL-encoded form (_e_ for edit, then _f_ for form in flow view)
- Editing replacement patterns (_R_ globally)
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:
<img src="@!urlTo('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:
<img src="@!urlTo('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 (_a_ key), delete a row (_d_ key), spawn an
external editor on a field (_e_ key). Be sure to consult the context-sensitive
help (_?_ 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
<img src="@!urlTo('mitmproxy-intercept-filt.png')!@"/>
We press _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 [Filter expressions](@!urlTo("filters.html")!@) section of this
document, or the built-in help function in __mitmproxy__.
### 2: Intercepted connections are indicated with orange text:
<img src="@!urlTo('mitmproxy-intercept-mid.png')!@"/>
### 3: You can now view and modify the request:
<img src="@!urlTo('mitmproxy-intercept-options.png')!@"/>
In this case, we viewed the request by selecting it, pressed _e_ for "edit"
and _m_ for "method" to change the HTTP request method.
### 4: Accept the intercept to continue:
<img src="@!urlTo('mitmproxy-intercept-result.png')!@"/>
Finally, we press _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".

BIN
doc-src/screenshots/firefox3-import.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

BIN
doc-src/screenshots/firefox3-trust.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
doc-src/screenshots/firefox3.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
doc-src/screenshots/ios-installed.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

BIN
doc-src/screenshots/ios-profile.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 81 KiB

BIN
doc-src/screenshots/ios-warning.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

BIN
doc-src/screenshots/mitmproxy-flowview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 308 KiB

BIN
doc-src/screenshots/mitmproxy-intercept-filt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
doc-src/screenshots/mitmproxy-intercept-mid.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
doc-src/screenshots/mitmproxy-intercept-options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
doc-src/screenshots/mitmproxy-intercept-result.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
doc-src/screenshots/mitmproxy-kveditor-editmode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
doc-src/screenshots/mitmproxy-kveditor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
doc-src/screenshots/mitmproxy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 149 KiB

BIN
doc-src/screenshots/osx-addcert-alwaystrust.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
doc-src/screenshots/win7-certstore-trustedroot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc-src/screenshots/win7-certstore.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
doc-src/screenshots/win7-wizard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

6
doc-src/scripting/index.py Normal file
View File

@ -0,0 +1,6 @@
from countershape import Page
pages = [
Page("inlinescripts.html", "Inline Scripts"),
Page("libmproxy.html", "libmproxy"),
]

149
doc-src/scripting/inlinescripts.html Normal file
View File

@ -0,0 +1,149 @@
__mitmproxy__ has a powerful scripting API that allows you to modify flows
on-the-fly or rewrite previously saved flows locally.
The mitmproxy scripting API is event driven - a script is simply a Python
module that exposes a set of event methods. Here's a complete mitmproxy script
that adds a new header to every HTTP response before it is returned to the
client:
$!example("examples/add_header.py")!$
The first argument to each event method is an instance of ScriptContext that
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 using mitmdump or mitmproxy as follows:
<pre class="terminal">
> mitmdump -s add_header.py
</pre>
The new header will be added to all responses passing through the proxy.
## Events
### start(ScriptContext, argv)
Called once on startup, before any other events.
### clientconnect(ScriptContext, ClientConnect)
Called when a client initiates a connection to the proxy. Note that
a connection can correspond to multiple HTTP requests.
### serverconnect(ScriptContext, ServerConnection)
Called when the proxy initiates a connection to the target server. Note that
a connection can correspond to multiple HTTP requests.
### request(ScriptContext, Flow)
Called when a client request has been received. The __Flow__ object is
guaranteed to have a non-None __request__ attribute.
### response(ScriptContext, Flow)
Called when a server response has been received. The __Flow__ object is
guaranteed to have non-None __request__ and __response__ attributes.
### error(ScriptContext, Flow)
Called when a flow error has occurred, e.g. invalid server responses, or
interrupted connections. This is distinct from a valid server HTTP error
response, which is simply a response with an HTTP error code. The __Flow__
object is guaranteed to have non-None __request__ and __error__ attributes.
### clientdisconnect(ScriptContext, ClientDisconnect)
Called when a client disconnects from the proxy.
### done(ScriptContext)
Called once on script shutdown, after any other events.
## API
The main classes you will deal with in writing mitmproxy scripts are:
<table class="table">
<tr>
<th>libmproxy.flow.ClientConnection</th>
<td>Describes a client connection.</td>
</tr>
<tr>
<th>libmproxy.flow.ClientDisconnection</th>
<td>Describes a client disconnection.</td>
</tr>
<tr>
<th>libmproxy.flow.Error</th>
<td>A communications error.</td>
</tr>
<tr>
<th>libmproxy.flow.Flow</th>
<td>A collection of objects representing a single HTTP transaction.</td>
</tr>
<tr>
<th>libmproxy.flow.Headers</th>
<td>HTTP headers for a request or response.</td>
</tr>
<tr>
<th>libmproxy.flow.ODict</th>
<td>A dictionary-like object for managing sets of key/value data. There
is also a variant called CaselessODict that ignores key case for some
calls (used mainly for headers).</td>
</tr>
<tr>
<th>libmproxy.flow.Response</th>
<td>An HTTP response.</td>
</tr>
<tr>
<th>libmproxy.flow.Request</th>
<td>An HTTP request.</td>
</tr>
<tr>
<th>libmproxy.flow.ScriptContext</th>
<td> A handle for interacting with mitmproxy's from within scripts. </td>
</tr>
<tr>
<th>libmproxy.certutils.SSLCert</th>
<td>Exposes information SSL certificates.</td>
</tr>
</table>
The canonical API documentation is the code. You can view the API documentation
using pydoc (which is installed with Python by default), like this:
<pre class="terminal">
> pydoc libmproxy.flow.Request
</pre>
## Running scripts in parallel
We have a single flow primitive, so when a script is handling something, other requests block.
While that's a very desirable behaviour under some circumstances, scripts can be run threaded by using the <code>libmproxy.script.concurrent</code> decorator.
$!example("examples/nonblocking.py")!$
## Running scripts on saved flows
Sometimes, we want to run a script on __Flow__ objects that are already
complete. This happens when you start a script, and then load a saved set of
flows from a file (see the "scripted data transformation" example on the
[mitmdump](@!urlTo("mitmdump.html")!@) page). It also happens when you run a
one-shot script on a single flow through the _|_ (pipe) shortcut in mitmproxy.
In this case, there are no client connections, and the events are run in the
following order: __start__, __request__, __response__, __error__, __done__. If
the flow doesn't have a __response__ or __error__ associated with it, the
matching event will be skipped.

12
doc-src/scripting/libmproxy.html Normal file
View File

@ -0,0 +1,12 @@
All of mitmproxy's basic functionality is exposed through the __libmproxy__
library. The example below shows a simple implementation of the "sticky cookie"
functionality included in the interactive mitmproxy program. Traffic is
monitored for __cookie__ and __set-cookie__ headers, and requests are rewritten
to include a previously seen cookie if they don't already have one. In effect,
this lets you log in to a site using your browser, and then make subsequent
requests using a tool like __curl__, which will then seem to be part of the
authenticated session.
$!example("examples/stickycookies")!$

63
doc-src/ssl.html Normal file
View File

@ -0,0 +1,63 @@
The first time __mitmproxy__ or __mitmdump__ is run, a set of certificate files
for the mitmproxy Certificate Authority are created in the config directory
(~/.mitmproxy by default). The files are as follows:
<table class="table">
<tr>
<td class="nowrap">mitmproxy-ca.pem</td>
<td>The private key and certificate in PEM format.</td>
</tr>
<tr>
<td class="nowrap">mitmproxy-ca-cert.pem</td>
<td>The certificate in PEM format. Use this to distribute to most
non-Windows platforms.</td>
</tr>
<tr>
<td class="nowrap">mitmproxy-ca-cert.p12</td>
<td>The certificate in PKCS12 format. For use on Windows.</td>
</tr>
<tr>
<td class="nowrap">mitmproxy-ca-cert.cer</td>
<td>Same file as .pem, but with an extension expected by some Android
devices.</td>
</tr>
</table>
This CA is used for on-the-fly generation of dummy certificates for SSL
interception. Since your browser won't trust the __mitmproxy__ CA out of the
box (and rightly so), you will see an SSL cert warning every time you visit a
new SSL domain through __mitmproxy__. When you're testing a single site through
a browser, just accepting the bogus SSL cert manually is not too much trouble,
but there are a many circumstances where you will want to configure your
testing system or browser to trust the __mitmproxy__ CA as a signing root
authority.
Using a custom certificate
--------------------------
You can use your own certificate by passing the __--cert__ option to mitmproxy.
The certificate file is expected to be in the PEM format. You can generate
a certificate in this format using these instructions:
<pre class="terminal">
> openssl genrsa -out cert.key 8192
> openssl req -new -x509 -key cert.key -out cert.crt
(Specify the mitm domain as Common Name, e.g. *.google.com)
> cat cert.key cert.crt > cert.pem
> mitmproxy --cert=cert.pem
</pre>
Installing the mitmproxy CA
---------------------------
* [Firefox](@!urlTo("certinstall/firefox.html")!@)
* [OSX](@!urlTo("certinstall/osx.html")!@)
* [Windows 7](@!urlTo("certinstall/windows7.html")!@)
* [iPhone/iPad](@!urlTo("certinstall/ios.html")!@)
* [IOS Simulator](@!urlTo("certinstall/ios-simulator.html")!@)
* [Android](@!urlTo("certinstall/android.html")!@)

120
doc-src/syntax.css Normal file
View File

@ -0,0 +1,120 @@
.highlight { background: #f8f8f8; }
.highlight .c { color: #408080; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #BC7A00 } /* Comment.Preproc */
.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #808080 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #7D9029 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
.grokdoc { background: #f8f8f8; }
.grokdoc .c { color: #408080; font-style: italic } /* Comment */
.grokdoc .err { border: 1px solid #FF0000 } /* Error */
.grokdoc .k { color: #008000; font-weight: bold } /* Keyword */
.grokdoc .o { color: #666666 } /* Operator */
.grokdoc .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.grokdoc .cp { color: #BC7A00 } /* Comment.Preproc */
.grokdoc .c1 { color: #408080; font-style: italic } /* Comment.Single */
.grokdoc .cs { color: #408080; font-style: italic } /* Comment.Special */
.grokdoc .gd { color: #A00000 } /* Generic.Deleted */
.grokdoc .ge { font-style: italic } /* Generic.Emph */
.grokdoc .gr { color: #FF0000 } /* Generic.Error */
.grokdoc .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.grokdoc .gi { color: #00A000 } /* Generic.Inserted */
.grokdoc .go { color: #808080 } /* Generic.Output */
.grokdoc .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.grokdoc .gs { font-weight: bold } /* Generic.Strong */
.grokdoc .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.grokdoc .gt { color: #0040D0 } /* Generic.Traceback */
.grokdoc .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.grokdoc .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.grokdoc .kp { color: #008000 } /* Keyword.Pseudo */
.grokdoc .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.grokdoc .kt { color: #B00040 } /* Keyword.Type */
.grokdoc .m { color: #666666 } /* Literal.Number */
.grokdoc .s { color: #BA2121 } /* Literal.String */
.grokdoc .na { color: #7D9029 } /* Name.Attribute */
.grokdoc .nb { color: #008000 } /* Name.Builtin */
.grokdoc .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.grokdoc .no { color: #880000 } /* Name.Constant */
.grokdoc .nd { color: #AA22FF } /* Name.Decorator */
.grokdoc .ni { color: #999999; font-weight: bold } /* Name.Entity */
.grokdoc .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.grokdoc .nf { color: #0000FF } /* Name.Function */
.grokdoc .nl { color: #A0A000 } /* Name.Label */
.grokdoc .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.grokdoc .nt { color: #008000; font-weight: bold } /* Name.Tag */
.grokdoc .nv { color: #19177C } /* Name.Variable */
.grokdoc .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.grokdoc .w { color: #bbbbbb } /* Text.Whitespace */
.grokdoc .mf { color: #666666 } /* Literal.Number.Float */
.grokdoc .mh { color: #666666 } /* Literal.Number.Hex */
.grokdoc .mi { color: #666666 } /* Literal.Number.Integer */
.grokdoc .mo { color: #666666 } /* Literal.Number.Oct */
.grokdoc .sb { color: #BA2121 } /* Literal.String.Backtick */
.grokdoc .sc { color: #BA2121 } /* Literal.String.Char */
.grokdoc .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.grokdoc .s2 { color: #BA2121 } /* Literal.String.Double */
.grokdoc .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.grokdoc .sh { color: #BA2121 } /* Literal.String.Heredoc */
.grokdoc .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.grokdoc .sx { color: #008000 } /* Literal.String.Other */
.grokdoc .sr { color: #BB6688 } /* Literal.String.Regex */
.grokdoc .s1 { color: #BA2121 } /* Literal.String.Single */
.grokdoc .ss { color: #19177C } /* Literal.String.Symbol */
.grokdoc .bp { color: #008000 } /* Name.Builtin.Pseudo */
.grokdoc .vc { color: #19177C } /* Name.Variable.Class */
.grokdoc .vg { color: #19177C } /* Name.Variable.Global */
.grokdoc .vi { color: #19177C } /* Name.Variable.Instance */
.grokdoc .il { color: #666666 } /* Literal.Number.Integer.Long */

19
doc-src/transparent.html Normal file
View File

@ -0,0 +1,19 @@
When a transparent proxy is used, traffic is redirected into a proxy at the
network layer, without any client configuration being required. This makes
transparent proxying ideal for those situations where you can't change client
behaviour - proxy-oblivious Android applications being a common example.
To set up transparent proxying, we need two new components. The first is a
redirection mechanism that transparently reroutes a TCP connection destined for
a server on the Internet to a listening proxy server. This usually takes the
form of a firewall on the same host as the proxy server -
[iptables](http://www.netfilter.org/) on Linux or
[pf](http://en.wikipedia.org/wiki/PF_\(firewall\)) on OSX. When the proxy
receives a redirected connection, it sees a vanilla HTTP request, without a
host specification. This is where the second new component comes in - a host
module that allows us to query the redirector for the original destination of
the TCP connection.
At the moment, mitmproxy supports transparent proxying on OSX Lion and above,
and all current flavors of Linux.

BIN
doc-src/transparent.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

6
doc-src/transparent/index.py Normal file
View File

@ -0,0 +1,6 @@
from countershape import Page
pages = [
Page("osx.html", "OSX"),
Page("linux.html", "Linux"),
]

43
doc-src/transparent/linux.html Normal file
View File

@ -0,0 +1,43 @@
On Linux, mitmproxy integrates with the iptables redirection mechanism to
achieve transparent mode.
<ol class="tlist">
<li> <a href="@!urlTo('ssl.html')!@">Install the mitmproxy
certificates on the test device</a>. </li>
<li> Enable IP forwarding:
<pre class="terminal">sysctl -w net.ipv4.ip_forward=1</pre>
You may also want to consider enabling this permanently in
<b>/etc/sysctl.conf</b>.
</li>
<li> Create an iptables ruleset that redirects the desired traffic to the
mitmproxy port. Details will differ according to your setup, but the
ruleset should look something like this:
<pre class="terminal">iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080</pre>
</li>
<li> Fire up mitmproxy. You probably want a command like this:
<pre class="terminal">mitmproxy -T --host</pre>
The <b>-T</b> flag turns on transparent mode, and the <b>--host</b>
argument tells mitmproxy to use the value of the Host header for URL
display.
</li>
<li> Finally, configure your test device to use the host on which mitmproxy is
running as the default gateway.</li>
</ol>
For a detailed walkthrough, have a look at the <a href="@!urlTo('tutorials/transparent-dhcp.html')!@"><i>Transparently proxify virtual machines</i></a> tutorial.

81
doc-src/transparent/osx.html Normal file
View File

@ -0,0 +1,81 @@
OSX Lion integrated the [pf](http://www.openbsd.org/faq/pf/) packet filter from
the OpenBSD project, which mitmproxy uses to implement transparent mode on OSX.
Note that this means we don't support transparent mode for earlier versions of
OSX.
<ol class="tlist">
<li> <a href="@!urlTo('ssl.html')!@">Install the mitmproxy
certificates on the test device</a>. </li>
<li> Enable IP forwarding:
<pre class="terminal">sudo sysctl -w net.inet.ip.forwarding=1</pre>
</li>
<li> Place the following two lines in a file called, say, <b>pf.conf</b>:
<pre class="terminal">rdr on en2 inet proto tcp to any port 80 -&gt; 127.0.0.1 port 8080
rdr on en2 inet proto tcp to any port 443 -&gt; 127.0.0.1 port 8080
</pre>
These rules tell pf to redirect all traffic destined for port 80 or 443
to the local mitmproxy instance running on port 8080. You should
replace <b>en2</b> with the interface on which your test device will
appear.
</li>
<li> Configure pf with the rules:
<pre class="terminal">sudo pfctl -f pf.conf</pre>
</li>
<li> And now enable it:
<pre class="terminal">sudo pfctl -e</pre>
</li>
<li> Configure sudoers to allow mitmproxy to access pfctl. Edit the file
<b>/etc/sudoers</b> on your system as root. Add the following line to the end
of the file:
<pre>ALL ALL=NOPASSWD: /sbin/pfctl -s state</pre>
Note that this allows any user on the system to run the command
"/sbin/pfctl -s state" as root without a password. This only allows
inspection of the state table, so should not be an undue security risk. If
you're special feel free to tighten the restriction up to the user running
mitmproxy.</li>
<li> Fire up mitmproxy. You probably want a command like this:
<pre class="terminal">mitmproxy -T --host</pre>
The <b>-T</b> flag turns on transparent mode, and the <b>--host</b>
argument tells mitmproxy to use the value of the Host header for URL
display.
</li>
<li> Finally, configure your test device to use the host on which mitmproxy is
running as the default gateway.</li>
</ol>
Note that the **rdr** rules in the pf.conf given above only apply to inbound
traffic. This means that they will NOT redirect traffic coming from the box
running pf itself. We can't distinguish between an outbound connection from a
non-mitmproxy app, and an outbound connection from mitmproxy itself - if you
want to intercept your OSX traffic, you should use an external host to run
mitmproxy. None the less, pf is flexible to cater for a range of creative
possibilities, like intercepting traffic emanating from VMs. See the
**pf.conf** man page for more.

BIN
doc-src/transparent_https.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

61
doc-src/tutorials/30second.html Normal file
View File

@ -0,0 +1,61 @@
My local cafe is serviced by a rickety and unreliable wireless network,
generously sponsored with ratepayers' money by our city council. After
connecting, you are redirected to an SSL-protected page that prompts you for a
username and password. Once you've entered your details, you are free to enjoy
the intermittent dropouts, treacle-like speeds and incorrectly configured
transparent proxy.
I tend to automate this kind of thing at the first opportunity, on the theory
that time spent now will be more than made up in the long run. In this case, I
might use [Firebug](http://getfirebug.com/) to ferret out the form post
parameters and target URL, then fire up an editor to write a little script
using Python's [urllib](http://docs.python.org/library/urllib.html) to simulate
a submission. That's a lot of futzing about. With mitmproxy we can do the job
in literally 30 seconds, without having to worry about any of the details.
Here's how.
## 1. Run mitmdump to record our HTTP conversation to a file.
<pre class="terminal">
> mitmdump -w wireless-login
</pre>
## 2. Point your browser at the mitmdump instance.
I use a tiny Firefox addon called [Toggle
Proxy](https://addons.mozilla.org/en-us/firefox/addon/toggle-proxy-51740/) to
switch quickly to and from mitmproxy. I'm assuming you've already [configured
your browser with mitmproxy's SSL certificate
authority](http://mitmproxy.org/doc/ssl.html).
## 3. Log in as usual.
And that's it! You now have a serialized version of the login process in the
file wireless-login, and you can replay it at any time like this:
<pre class="terminal">
> mitmdump -c wireless-login
</pre>
## Embellishments
We're really done at this point, but there are a couple of embellishments we
could make if we wanted. I use [wicd](http://wicd.sourceforge.net/) to
automatically join wireless networks I frequent, and it lets me specify a
command to run after connecting. I used the client replay command above and
voila! - totally hands-free wireless network startup.
We might also want to prune requests that download CSS, JS, images and so
forth. These add only a few moments to the time it takes to replay, but they're
not really needed and I somehow feel compelled to trim them anyway. So, we fire up
the mitmproxy console tool on our serialized conversation, like so:
<pre class="terminal">
> mitmproxy -r wireless-login
</pre>
We can now go through and manually delete (using the __d__ keyboard shortcut)
everything we want to trim. When we're done, we use __w__ to save the
conversation back to the file.

122
doc-src/tutorials/gamecenter.html Normal file
View File

@ -0,0 +1,122 @@
## The setup
In this tutorial, I'm going to show you how simple it is to creatively
interfere with Apple Game Center traffic using mitmproxy. To set things up, I
registered my mitmproxy CA certificate with my iPhone - there's a [step by step
set of instructions](@!urlTo("certinstall/ios.html")!@) elsewhere in this manual. I then
started mitmproxy on my desktop, and configured the iPhone to use it as a
proxy.
## Taking a look at the Game Center traffic
Lets take a first look at the Game Center traffic. The game I'll use in this
tutorial is [Super Mega
Worm](http://itunes.apple.com/us/app/super-mega-worm/id388541990?mt=8) - a
great little retro-apocalyptic sidescroller for the iPhone:
<center>
<img src="@!urlTo('tutorials/supermega.png')!@"/>
</center>
After finishing a game (take your time), watch the traffic flowing through
mitmproxy:
<center>
<img src="@!urlTo('tutorials/one.png')!@"/>
</center>
We see a bunch of things we might expect - initialisation, the retrieval of
leaderboards and so forth. Then, right at the end, there's a POST to this
tantalising URL:
<pre>
https://service.gc.apple.com/WebObjects/GKGameStatsService.woa/wa/submitScore
</pre>
The contents of the submission are particularly interesting:
<!--(block|syntax("xml"))-->
<plist version="1.0">
<dict>
<key>scores</key>
<array>
<dict>
<key>category</key>
<string>SMW_Adv_USA1</string>
<key>context</key>
<integer>0</integer>
<key>score-value</key>
<integer>0</integer>
<key>timestamp</key>
<integer>1363515361321</integer>
</dict>
</array>
</dict>
</plist>
<!--(end)-->
This is a [property list](http://en.wikipedia.org/wiki/Property_list),
containing an identifier for the game, a score (55, in this case), and a
timestamp. Looks pretty simple to mess with.
## Modifying and replaying the score submission
Lets edit the score submission. First, select it in mitmproxy, then press
__enter__ to view it. Make sure you're viewing the request, not the response -
you can use __tab__ to flick between the two. Now press __e__ for edit. You'll
be prompted for the part of the request you want to change - press __b__ for
body. Your preferred editor (taken from the EDITOR environment variable) will
now fire up. Lets bump the score up to something a bit more ambitious:
<!--(block|syntax("xml"))-->
<plist version="1.0">
<dict>
<key>scores</key>
<array>
<dict>
<key>category</key>
<string>SMW_Adv_USA1</string>
<key>context</key>
<integer>0</integer>
<key>score-value</key>
<integer>2200272667</integer>
<key>timestamp</key>
<integer>1363515361321</integer>
</dict>
</array>
</dict>
</plist>
<!--(end)-->
Save the file and exit your editor.
The final step is to replay this modified request. Simply press __r__ for
replay.
## The glorious result and some intrigue
<center>
<img src="@!urlTo('tutorials/leaderboard.png')!@"/>
</center>
And that's it - according to the records, I am the greatest Super Mega Worm
player of all time.
There's a curious addendum to this tale. When I first wrote this tutorial, all
the top competitors' scores were the same: 2,147,483,647 (this is no longer the
case, beacause there are now so many fellow cheaters using this tutorial). If
you think that number seems familiar, you're right: it's 2^31-1, the maximum
value you can fit into a signed 32-bit int. Now let me tell you another
peculiar thing about Super Mega Worm - at the end of every game, it submits
your highest previous score to the Game Center, not your current score. This
means that it stores your highscore somewhere, and I'm guessing that it reads
that stored score back into a signed integer. So, if you _were_ to cheat by the
relatively pedestrian means of modifying the saved score on your jailbroken
phone, then 2^31-1 might well be the maximum score you could get. Then again,
if the game itself stores its score in a signed 32-bit int, you could get the
same score through perfect play, effectively beating the game. So, which is it
in this case? I'll leave that for you to decide.

7
doc-src/tutorials/index.py Normal file
View File

@ -0,0 +1,7 @@
from countershape import Page
pages = [
Page("30second.html", "Client playback: a 30 second example"),
Page("gamecenter.html", "Setting highscores on Apple's GameCenter"),
Page("transparent-dhcp.html", "Transparently proxify virtual machines")
]

BIN
doc-src/tutorials/leaderboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 438 KiB

BIN
doc-src/tutorials/one.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 138 KiB

BIN
doc-src/tutorials/supermega.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

54
doc-src/tutorials/transparent-dhcp.html Normal file
View File

@ -0,0 +1,54 @@
This walkthrough illustrates how to set up transparent proxying with mitmproxy. We use VirtualBox VMs with an Ubuntu proxy machine in this example, but the general principle can be applied to other setups.
1. **Configure VirtualBox Network Adapters for the proxy machine**
The network setup is simple: `internet <--> proxy vm <--> (virtual) internal network`.
For the proxy machine, *eth0* represents the outgoing network. *eth1* is connected to the internal network that will be proxified, using a static ip (192.168.3.1).
<hr>VirtualBox configuration:
<img src="@!urlTo('tutorials/transparent-dhcp/step1_vbox_eth0.png')!@"/><br><br>
<img src="@!urlTo('tutorials/transparent-dhcp/step1_vbox_eth1.png')!@"/>
<br>Proxy VM:
<img src="@!urlTo('tutorials/transparent-dhcp/step1_proxy.png')!@"/>
<hr>
2. **Configure DHCP and DNS**
We use dnsmasq to provide DHCP and DNS in our internal network.
Dnsmasq is a lightweight server designed to provide DNS (and optionally DHCP and TFTP) services to a small-scale
network.
- Before we get to that, we need to fix some Ubuntu quirks:
**Ubuntu >12.04** runs an internal dnsmasq instance (listening on loopback only) by default
<a href="https://www.stgraber.org/2012/02/24/dns-in-ubuntu-12-04/">[1]</a>. For our use case, this needs to be
disabled by changing <br>`dns=dnsmasq` to `#dns=dnsmasq` in */etc/NetworkManager/NetworkManager.conf*
and running `sudo restart network-manager` afterwards.
- Now, dnsmasq can be be installed and configured:
`sudo apt-get install dnsmasq`
Replace */etc/dnsmasq.conf* with the following configuration:
<pre>\# Listen for DNS requests on the internal network
interface=eth1
\# Act as a DHCP server, assign IP addresses to clients
dhcp-range=192.168.3.10,192.168.3.100,96h
\# Broadcast gateway and dns server information
dhcp-option=option:router,192.168.3.1
dhcp-option=option:dns-server,192.168.3.1
</pre>
Apply changes:
`sudo service dnsmasq restart`
<hr>
Your proxied machine's network settings should now look similar to this:
<img src="@!urlTo('tutorials/transparent-dhcp/step2_proxied_vm.png')!@"/>
<hr>
3. **Set up traffic redirection to mitmproxy**
To redirect traffic to mitmproxy, we need to add two iptables rules:
<pre class="terminal">
iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 80 \
-j REDIRECT --to-port 8080
iptables -t nat -A PREROUTING -i eth1 -p tcp --dport 443 \
-j REDIRECT --to-port 8080
</pre>
4. If required, <a href="@!urlTo('ssl.html')!@">install the mitmproxy
certificates on the test device</a>.
5. Finally, we can run <code>mitmproxy -T</code>.
The proxied machine cannot to leak any data outside of HTTP or DNS requests.

BIN
doc-src/tutorials/transparent-dhcp/step1_proxy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 241 KiB

BIN
doc-src/tutorials/transparent-dhcp/step1_vbox_eth0.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doc-src/tutorials/transparent-dhcp/step1_vbox_eth1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doc-src/tutorials/transparent-dhcp/step2_proxied_vm.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB