* docs: document addon live-reload + testing pattern
Issue #6377 asked for addon development docs covering hot reload and
testing. mitmproxy already watches scripts loaded with -s for changes
and re-imports them on save (mitmproxy/addons/script.py: Script.watcher
and the unconditional Script(s, True) at line 218), but that behavior
was undocumented, and there was no canonical example of how to unit-test
a custom addon with mitmproxy.test.taddons / mitmproxy.test.tflow.
Add a "Developing Addons" section to docs/src/content/addons/overview.md
with two subsections:
- Live Reloading: explains the file-watcher behavior, including which
errors leave the previous version unloaded and which don't.
- Testing Addons: a small example that unit-tests the Counter addon from
anatomy.py using taddons.context() and tflow.tflow(), plus a pointer
to tctx.cycle() and the existing test/mitmproxy/addons/ tests for
patterns that need the full event sequence.
No code changes.
* reduce testing section
Testing helpers are currently a bit ugly and not part of the public API, so let's not put them front center in the docs.
---------
Co-authored-by: Chris (ChrisJr404) <11917633+ChrisJr404@users.noreply.github.com>
Co-authored-by: Maximilian Hils <git@maximilianhils.com>
Change 'uvx' to 'uv tool install'
'uvx' is an alias for 'uv tool run' that installs packages in a temporary virtual environment that is deleted when the uv cache is cleaned. The correct installation command should be 'uv tool install' which installs the virtual environment in the uv tools directory and makes the executable available on the PATH.
See: https://docs.astral.sh/uv/concepts/tools/
docs(fix): fix broken upstream certificate sniffing link in how-mitmproxy-works
Updated broken link in docs/src/how-mitmproxy-works.md from [/overview/features](/overview/features/#upstream-certificates) to [/concepts/certificates/](/concepts/certificates/#upstream-certificate-sniffing) to point to the correct resource.
* wip
* wip
* docs: improve content structure
* make menu collapsible
* move anchor to the end of the heading
* layout fixes
* avoid menu items with the same name
* wip
* add CHANGELOG entry
* [autofix.ci] apply automated fixes
* fixup
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
* docs: Add --cask in brew install command
# Motivation
As a Brewfile user, the current installation command in the documentation
does not tell me that mitmproxy is a Cask, which is a bit of an
inconvenience due to how Brewfile works.
Adding a formulae in a Brewfile is done by adding the line `brew "<formulae>"`
while adding a cask in a Brewfile is done by adding the line `cask "<cask>"`
Contrarily to the behavior of the brew install command, adding a formulae line
in the Brewfile will not check for a Cask if the formulae does not exist: it
will just fail.
# Impact
The brew install command currently works by first checking if a "mitmproxy"
formulae exists in the homebrew repository, then after finding out there is
none, it checks for a "mitmproxy" cask in the homebrew repository.
Adding the explicit `--cask` argument allows to skip the unnecessary
formulae existence check, while being more convenient for Brewfile users.
# TL;DR
Adding the explicit `--cask` argument is useful to Brewfile users in such
that they directly know that mitmproxy is a Cask, while not impacting users
copy-pasting the command directly in their terminal (while also avoiding an
unwanted check for a corresponding formulae before the cask installation).
* [autofix.ci] apply automated fixes
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
* make all filter expressions case-insensitive by default
* [autofix.ci] apply automated fixes
* add test cases.
* added dedicated test case for case sensitivity check
---------
Co-authored-by: Maximilian Hils <git@maximilianhils.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
* Update Hugo installed in CI from `v0.92.1` to `v0.139.3`
The version in CI is close to 3 years old, which means it does not
encounter the same problems that newer installations of Hugo do.
* Fix Hugo deprecation error
I got the following error when building the documentation with Hugo
`v0.139.3`:
```
ERROR deprecated: data.GetJSON was deprecated in Hugo v0.123.0 and will be removed in Hugo 0.140.0. use resources.Get or resources.GetRemote with transform.Unmarshal.
```
I fixed the error by implementing the change the error recommended.
* options: add request_client_cert to enable mutual TLS
This capability was already built-in but hard-coded to be disabled. Making it configurable as option (defaulting to off) enables mTLS connections between clients and mitmproxy. If true, mitmproxy will send a TLS `CertificateRequest` message to the client during the TLS handshake, upon which a client needs to present a client certificate to mitmproxy to successfully establish an mTLS connection.
This option can be used together with the `client_certs` option to also establish an mTLS connection between mitmproxy and the upstream server. In this case, mitmproxy needs to have a full client cert, including matching private key, that is trusted and accepted by the upstream server. This is a common scenario with MQTT or IoT connections.
Example usage:
$ mitmproxy --set request_client_cert=True --set client_certs=some_directory/
With `some_directory/` containing a `mqtt.example.com.pem` x509 certificate file (including private key).
This allows a client connecting using mTLS, to be intercepted by mitmproxy, which is itself establishing an mTLS connection to the `mqtt.example.com` upstream server. Restricting the client_certs using a directory and PEM files named after the upstream domain, narrows down the mTLS requirement to this single domain, while leaving all other traffic through mitmproxy untouched (normal TLS without client certs).
* add CHANGELOG entry
* docs++
* swap section order, re-add example
---------
Co-authored-by: Maximilian Hils <git@maximilianhils.com>
Co-authored-by: Maximilian Hils <github@maximilianhils.com>
