From 39e2278e935a83f6ee09ba289166a9bc990ac446 Mon Sep 17 00:00:00 2001 From: Thomas Kriechbaumer Date: Sun, 12 Apr 2020 22:38:34 +0200 Subject: [PATCH] improve getting-started docs --- docs/src/content/concepts-certificates.md | 6 +-- docs/src/content/overview-getting-started.md | 49 +++++++++++++++++++ docs/src/content/overview-installation.md | 29 ++++++----- .../addons/onboardingapp/templates/index.html | 17 +++---- 4 files changed, 74 insertions(+), 27 deletions(-) create mode 100644 docs/src/content/overview-getting-started.md diff --git a/docs/src/content/concepts-certificates.md b/docs/src/content/concepts-certificates.md index 4e9aa652b..20b03dc65 100644 --- a/docs/src/content/concepts-certificates.md +++ b/docs/src/content/concepts-certificates.md @@ -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) diff --git a/docs/src/content/overview-getting-started.md b/docs/src/content/overview-getting-started.md new file mode 100644 index 000000000..ff018c3b6 --- /dev/null +++ b/docs/src/content/overview-getting-started.md @@ -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. diff --git a/docs/src/content/overview-installation.md b/docs/src/content/overview-installation.md index 5b94adfcd..1cdf62ad6 100644 --- a/docs/src/content/overview-installation.md +++ b/docs/src/content/overview-installation.md @@ -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. \ No newline at end of file +As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks. diff --git a/mitmproxy/addons/onboardingapp/templates/index.html b/mitmproxy/addons/onboardingapp/templates/index.html index aee6858cd..822e2856a 100644 --- a/mitmproxy/addons/onboardingapp/templates/index.html +++ b/mitmproxy/addons/onboardingapp/templates/index.html @@ -19,6 +19,14 @@ function changeTo(device) {
  • Done!
    • +
    +

    How to install on iOS 13+

    +

    How to install on browsers

    -
    -

    How to install on iOS v10.3

    -
    `; }