From 74b3b842fefec6a05d17bbdf365cd92c82fd3503 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Fri, 4 Sep 2015 16:17:55 +0200 Subject: rewrite basic docs for readthedocs --- docs/dev/exceptions.rst | 9 +++++++++ docs/dev/models.rst | 19 +++++++++++++++++++ docs/dev/protocols.rst | 15 +++++++++++++++ docs/dev/proxy.rst | 12 ++++++++++++ 4 files changed, 55 insertions(+) create mode 100644 docs/dev/exceptions.rst create mode 100644 docs/dev/models.rst create mode 100644 docs/dev/protocols.rst create mode 100644 docs/dev/proxy.rst (limited to 'docs/dev') diff --git a/docs/dev/exceptions.rst b/docs/dev/exceptions.rst new file mode 100644 index 00000000..d1e4bfe5 --- /dev/null +++ b/docs/dev/exceptions.rst @@ -0,0 +1,9 @@ +.. _exceptions: + +Exceptions +========== + +.. automodule:: libmproxy.exceptions + :show-inheritance: + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/dev/models.rst b/docs/dev/models.rst new file mode 100644 index 00000000..1ac7d042 --- /dev/null +++ b/docs/dev/models.rst @@ -0,0 +1,19 @@ +.. _models: + +Models +====== + +.. warning:: + The documentation for models has not been converted to rst yet and **many attributes/features + are missing**. + Please read the source code instead. + +.. automodule:: libmproxy.models + :show-inheritance: + :members: + :undoc-members: + + +.. automodule:: netlib.http.semantics + :members: Request, Response + :undoc-members: \ No newline at end of file diff --git a/docs/dev/protocols.rst b/docs/dev/protocols.rst new file mode 100644 index 00000000..498f634d --- /dev/null +++ b/docs/dev/protocols.rst @@ -0,0 +1,15 @@ +.. _protocols: + +Protocols +========= + +.. automodule:: libmproxy.protocol + + .. autoclass:: Layer + :members: + :special-members: + + .. autoclass:: ServerConnectionMixin + :members: + + .. autoexception:: Kill \ No newline at end of file diff --git a/docs/dev/proxy.rst b/docs/dev/proxy.rst new file mode 100644 index 00000000..c0cdb259 --- /dev/null +++ b/docs/dev/proxy.rst @@ -0,0 +1,12 @@ +.. _proxy: + +Proxy Server +============ + +.. automodule:: libmproxy.proxy + + .. autoclass:: ProxyServer + .. autoclass:: DummyServer + .. autoclass:: ProxyConfig + .. autoclass:: RootContext + :members: \ No newline at end of file -- cgit v1.2.3 From 1fb28594ed2799a27140a3cc86858556f17a7b41 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sat, 5 Sep 2015 13:27:11 +0200 Subject: doc: headers class --- docs/dev/models.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/dev') diff --git a/docs/dev/models.rst b/docs/dev/models.rst index 1ac7d042..ef370f09 100644 --- a/docs/dev/models.rst +++ b/docs/dev/models.rst @@ -16,4 +16,9 @@ Models .. automodule:: netlib.http.semantics :members: Request, Response - :undoc-members: \ No newline at end of file + :undoc-members: + + .. autoclass:: Headers + :members: + :special-members: + :no-undoc-members: \ No newline at end of file -- cgit v1.2.3 From 1165e35e1b6a3ae59afb6d9e259f75a201406174 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sat, 5 Sep 2015 20:15:35 +0200 Subject: docs++ --- docs/dev/models.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/dev') diff --git a/docs/dev/models.rst b/docs/dev/models.rst index ef370f09..850d89f5 100644 --- a/docs/dev/models.rst +++ b/docs/dev/models.rst @@ -19,6 +19,7 @@ Models :undoc-members: .. autoclass:: Headers + :show-inheritance: :members: :special-members: :no-undoc-members: \ No newline at end of file -- cgit v1.2.3 From b4013659a81a48908eb3e060f04143ba1f9689bb Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sun, 6 Sep 2015 03:20:58 +0200 Subject: docs :tada: --- docs/dev/architecture.rst | 14 ++++++++++++++ docs/dev/sslkeylogfile.rst | 14 ++++++++++++++ docs/dev/testing.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 docs/dev/architecture.rst create mode 100644 docs/dev/sslkeylogfile.rst create mode 100644 docs/dev/testing.rst (limited to 'docs/dev') diff --git a/docs/dev/architecture.rst b/docs/dev/architecture.rst new file mode 100644 index 00000000..ba902fab --- /dev/null +++ b/docs/dev/architecture.rst @@ -0,0 +1,14 @@ +.. _architecture: + +Architecture +============ + +To give you a better understanding of how mitmproxy works, mitmproxy's +high-level architecture is detailed in the following graphic: + +.. image:: ../schematics/architecture.png + +:download:`architecture.pdf <../schematics/architecture.pdf>` + +Please don't refrain from asking any further +questions on the mailing list, the Slack channel or the GitHub issue tracker. \ No newline at end of file diff --git a/docs/dev/sslkeylogfile.rst b/docs/dev/sslkeylogfile.rst new file mode 100644 index 00000000..d61a10c0 --- /dev/null +++ b/docs/dev/sslkeylogfile.rst @@ -0,0 +1,14 @@ +.. _sslkeylogfile: + +TLS Master Secrets +================== + +The SSL master keys can be logged by mitmproxy so that external programs can decrypt TLS connections +both from and to the proxy. Key logging is enabled by setting the environment variable +:envvar:`SSLKEYLOGFILE` so that it points to a writable text file. +Recent versions of WireShark can use these log files to decrypt packets. +You can specify the key file path in WireShark via +:samp:`Edit -> Preferences -> Protocols -> SSL -> (Pre)-Master-Secret log filename`. + +Note that :envvar:`SSLKEYLOGFILE` is respected by other programs as well, e.g. Firefox and Chrome. +If this creates any issues, you can set :envvar:`MITMPROXY_SSLKEYLOGFILE` alternatively. \ No newline at end of file diff --git a/docs/dev/testing.rst b/docs/dev/testing.rst new file mode 100644 index 00000000..242e0584 --- /dev/null +++ b/docs/dev/testing.rst @@ -0,0 +1,46 @@ +.. _testing: + +Testing +======= + +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_ test framework. +At the point where you send your pull request, a command like this: + +>>> nosetests --with-cov --cov-report term-missing ./test + +Should give output something like this: + +.. code-block:: none + + > ---------- 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 + + +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. + +.. _nose: https://nose.readthedocs.org/en/latest/ \ No newline at end of file -- cgit v1.2.3 From 31ee4607c892f85c5d139e54acbc3ca4f9fb6bcb Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Mon, 7 Sep 2015 10:30:40 +0200 Subject: remove old docs --- docs/dev/addingviews.html | 52 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/dev/addingviews.html (limited to 'docs/dev') diff --git a/docs/dev/addingviews.html b/docs/dev/addingviews.html new file mode 100644 index 00000000..12623a31 --- /dev/null +++ b/docs/dev/addingviews.html @@ -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. -- cgit v1.2.3 From c4286b15dc3d95f52b7ce5b5292796109fa77f3f Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Mon, 7 Sep 2015 10:52:18 +0200 Subject: docs: minor fixes --- docs/dev/architecture.rst | 2 +- docs/dev/exceptions.rst | 2 +- docs/dev/models.rst | 2 +- docs/dev/protocols.rst | 2 +- docs/dev/proxy.rst | 2 +- docs/dev/sslkeylogfile.rst | 6 +++--- docs/dev/testing.rst | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/dev') diff --git a/docs/dev/architecture.rst b/docs/dev/architecture.rst index ba902fab..e7995141 100644 --- a/docs/dev/architecture.rst +++ b/docs/dev/architecture.rst @@ -11,4 +11,4 @@ high-level architecture is detailed in the following graphic: :download:`architecture.pdf <../schematics/architecture.pdf>` Please don't refrain from asking any further -questions on the mailing list, the Slack channel or the GitHub issue tracker. \ No newline at end of file +questions on the mailing list, the Slack channel or the GitHub issue tracker. diff --git a/docs/dev/exceptions.rst b/docs/dev/exceptions.rst index d1e4bfe5..dab10e74 100644 --- a/docs/dev/exceptions.rst +++ b/docs/dev/exceptions.rst @@ -6,4 +6,4 @@ Exceptions .. automodule:: libmproxy.exceptions :show-inheritance: :members: - :undoc-members: \ No newline at end of file + :undoc-members: diff --git a/docs/dev/models.rst b/docs/dev/models.rst index 850d89f5..9929e4b2 100644 --- a/docs/dev/models.rst +++ b/docs/dev/models.rst @@ -22,4 +22,4 @@ Models :show-inheritance: :members: :special-members: - :no-undoc-members: \ No newline at end of file + :no-undoc-members: diff --git a/docs/dev/protocols.rst b/docs/dev/protocols.rst index 498f634d..1f8cca9a 100644 --- a/docs/dev/protocols.rst +++ b/docs/dev/protocols.rst @@ -12,4 +12,4 @@ Protocols .. autoclass:: ServerConnectionMixin :members: - .. autoexception:: Kill \ No newline at end of file + .. autoexception:: Kill diff --git a/docs/dev/proxy.rst b/docs/dev/proxy.rst index c0cdb259..dbd6fe67 100644 --- a/docs/dev/proxy.rst +++ b/docs/dev/proxy.rst @@ -9,4 +9,4 @@ Proxy Server .. autoclass:: DummyServer .. autoclass:: ProxyConfig .. autoclass:: RootContext - :members: \ No newline at end of file + :members: diff --git a/docs/dev/sslkeylogfile.rst b/docs/dev/sslkeylogfile.rst index d61a10c0..04b86cc4 100644 --- a/docs/dev/sslkeylogfile.rst +++ b/docs/dev/sslkeylogfile.rst @@ -3,12 +3,12 @@ TLS Master Secrets ================== -The SSL master keys can be logged by mitmproxy so that external programs can decrypt TLS connections -both from and to the proxy. Key logging is enabled by setting the environment variable +The SSL master keys can be logged by mitmproxy so that external programs can decrypt TLS +connections both from and to the proxy. Key logging is enabled by setting the environment variable :envvar:`SSLKEYLOGFILE` so that it points to a writable text file. Recent versions of WireShark can use these log files to decrypt packets. You can specify the key file path in WireShark via :samp:`Edit -> Preferences -> Protocols -> SSL -> (Pre)-Master-Secret log filename`. Note that :envvar:`SSLKEYLOGFILE` is respected by other programs as well, e.g. Firefox and Chrome. -If this creates any issues, you can set :envvar:`MITMPROXY_SSLKEYLOGFILE` alternatively. \ No newline at end of file +If this creates any issues, you can set :envvar:`MITMPROXY_SSLKEYLOGFILE` alternatively. diff --git a/docs/dev/testing.rst b/docs/dev/testing.rst index 242e0584..36c85426 100644 --- a/docs/dev/testing.rst +++ b/docs/dev/testing.rst @@ -43,4 +43,4 @@ 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. -.. _nose: https://nose.readthedocs.org/en/latest/ \ No newline at end of file +.. _nose: https://nose.readthedocs.org/en/latest/ -- cgit v1.2.3