mirror of
https://github.com/mitmproxy/mitmproxy.git
synced 2024-11-23 13:19:48 +00:00
improve getting-started docs
This commit is contained in:
Thomas Kriechbaumer
Thomas Kriechbaumer
parent
30645fa1ac
commit
39e2278e93
@ -36,12 +36,12 @@ documentation for some common platforms. The mitmproxy CA cert is located in
|
||||
`~/.mitmproxy` after it has been generated at the first start of mitmproxy.
|
||||
|
||||
- [IOS](http://jasdev.me/intercepting-ios-traffic)
|
||||
On iOS 10.3 and onwards, you also need to enable full trust for the mitmproxy
|
||||
On recent iOS versions you also need to enable full trust for the mitmproxy
|
||||
root certificate:
|
||||
1. Go to Settings > General > About > Certificate Trust Settings.
|
||||
2. Under "Enable full trust for root certificates", turn on trust for
|
||||
the mitmproxy certificate.
|
||||
- [IOS Simulator](https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore)
|
||||
the mitmproxy certificate.
|
||||
- [iOS Simulator](https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore)
|
||||
- [Java](https://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html)
|
||||
- [Android/Android Simulator](http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets)
|
||||
- [Windows](https://web.archive.org/web/20160612045445/http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7)
|
||||
|
||||
49
docs/src/content/overview-getting-started.md
Normal file
49
docs/src/content/overview-getting-started.md
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
title: "Getting Started"
|
||||
menu: "overview"
|
||||
menu:
|
||||
overview:
|
||||
weight: 3
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
You have already [installed]({{< relref "overview-installation">}}) mitmproxy on
|
||||
your machine.
|
||||
|
||||
# Launch the tool you need
|
||||
|
||||
You can start any of our three tools from the command line / terminal:
|
||||
|
||||
* [mitmproxy]({{< relref "tools-mitmproxy">}}) -> gives you an interactive TUI
|
||||
* [mitmdump]({{< relref "tools-mitmdump">}}) -> gives you a plain and simple terminal output
|
||||
* [mitmweb]({{< relref "tools-mitmweb">}}) -> gives you a browser-based GUI
|
||||
|
||||
When we talk about "mitmproxy" we usually refer to any of the three tools - they
|
||||
are just different front-ends to the same core proxy.
|
||||
|
||||
# Configure your browser or device
|
||||
|
||||
For the basic setup as [regular proxy]({{< relref
|
||||
"concepts-modes#regular-proxy">}}), you need to configure your browser or device
|
||||
to route all web traffic through mitmproxy as HTTP proxy. Browser versions and
|
||||
configurations options frequently change, so we recommend to simply search the
|
||||
web on how to configure an HTTP proxy for your system. Some operating system
|
||||
have a global settings, some browser have their own, other applications use
|
||||
environment variables, etc.
|
||||
|
||||
You can check that your web traffic is going through mitmproxy by browsing to
|
||||
http://mitm.it - it should present you with a [simple page]({{< relref
|
||||
"concepts-certificates/#quick-setup">}}) to install the mitmproxy Certificate
|
||||
Authority - which is also the next steps. Follow the instructions for your OS /
|
||||
system and install the CA (and make sure to enable it, some system require
|
||||
multiple steps!).
|
||||
|
||||
# Verifying everything works
|
||||
|
||||
At this point your running mitmproxy instance should already show the first HTTP
|
||||
flows from your client. You can test that all TLS-encrypted web traffic is
|
||||
working as expected by browsing to https://mitmproxy.org - it should show up as
|
||||
new flow and you can inspect it.
|
||||
|
||||
Done.
|
||||
@ -34,20 +34,18 @@ the repository maintainers directly for issues with native packages.
|
||||
|
||||
## Windows
|
||||
|
||||
|
||||
All the mitmproxy tools are fully supported under
|
||||
[WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/about).
|
||||
We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
|
||||
follow the mitmproxy installation instructions for Linux.
|
||||
All the mitmproxy tools are fully supported under [WSL (Windows Subsystem for
|
||||
Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). We recommend to
|
||||
[install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and
|
||||
then follow the mitmproxy installation instructions for Linux.
|
||||
|
||||
We also distribute native Windows packages for all tools other than the
|
||||
mitmproxy console app, which only works under WSL. To install mitmproxy on Windows,
|
||||
download the installer from [mitmproxy.org](https://mitmproxy.org/).
|
||||
mitmproxy console app, which only works under WSL. To install mitmproxy on
|
||||
Windows, download the installer from [mitmproxy.org](https://mitmproxy.org/).
|
||||
After installation, you'll find shortcuts for mitmweb and mitmdump in the start
|
||||
menu. Both executables are added to your PATH and can be invoked from the
|
||||
command line.
|
||||
|
||||
|
||||
# Advanced Installation
|
||||
|
||||
## Development Setup
|
||||
@ -57,7 +55,6 @@ GitHub master branch, please see the our
|
||||
[README](https://github.com/mitmproxy/mitmproxy#installation)
|
||||
on GitHub.
|
||||
|
||||
|
||||
## Installation from the Python Package Index (PyPI)
|
||||
|
||||
If your mitmproxy addons require the installation of additional Python packages,
|
||||
@ -65,10 +62,10 @@ you can install mitmproxy from [PyPI](https://pypi.org/project/mitmproxy/).
|
||||
|
||||
While there are plenty of options around[^1], we recommend the installation using pipx:
|
||||
|
||||
[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python
|
||||
packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to
|
||||
[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python
|
||||
packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to
|
||||
provide support for it.
|
||||
|
||||
|
||||
1. Install a recent version of Python (we require at least 3.6).
|
||||
2. Install [pipx](https://pipxproject.github.io/pipx/).
|
||||
3. `pipx install mitmproxy`
|
||||
@ -82,8 +79,10 @@ You can use the official mitmproxy images from
|
||||
|
||||
## Security Considerations for Binary Packages
|
||||
|
||||
Our pre-compiled binary packages and Docker images include a self-contained Python 3 environment, a recent version of
|
||||
OpenSSL that support ALPN and HTTP/2, and other dependencies that would otherwise be cumbersome to compile and install.
|
||||
Our pre-compiled binary packages and Docker images include a self-contained
|
||||
Python 3 environment, a recent version of OpenSSL that support ALPN and HTTP/2,
|
||||
and other dependencies that would otherwise be cumbersome to compile and
|
||||
install.
|
||||
|
||||
Dependencies in the binary packages are frozen on release, and can't be updated
|
||||
in situ. This means that we necessarily capture any bugs or security issues that
|
||||
@ -92,4 +91,4 @@ dependencies (though we may do so if we become aware of a really serious issue).
|
||||
If you use our binary packages, please make sure you update regularly to ensure
|
||||
that everything remains current.
|
||||
|
||||
As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.
|
||||
As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.
|
||||
|
||||
@ -19,6 +19,14 @@ function changeTo(device) {
|
||||
<li>Done!</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="col-md-4">
|
||||
<h3 class="text-center">How to install on iOS 13+</h3>
|
||||
<ul>
|
||||
<li>Install and active the new Profile</li>
|
||||
<li>Goto Settings -> General -> About -> Certificate Trust Settings</li>
|
||||
<li>Toggle mitmproxy to ON</li>
|
||||
<li>Done!</li>
|
||||
</div>
|
||||
<div class="col-md-4">
|
||||
<h3 class="text-center">How to install on browsers</h3>
|
||||
<ul>
|
||||
@ -27,15 +35,6 @@ function changeTo(device) {
|
||||
<li>Firefox on macOS has its own CA store and needs to be installed with Firefox-specific instructions that can be found <a href="https://wiki.mozilla.org/MozillaRootCertificate#Mozilla_Firefox">HERE</a> .</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="col-md-4">
|
||||
<h3 class="text-center">How to install on iOS v10.3</h3>
|
||||
<ul>
|
||||
<li>After certificate installation, open Settings</li>
|
||||
<li>Navigate to General and then About</li>
|
||||
<li>Select Certificate Trust Settings</li>
|
||||
<li>Each root that has been installed via a profile will be listed below the heading Enable Full Trust For Root Certificates. Toggle mitmproxy on</li>
|
||||
<li>Done!</li>
|
||||
</div>
|
||||
</div>
|
||||
</div>`;
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user