Edit on GitHub

Options

The mitmproxy tools share a common YAML configuration file located at ~/.mitmproxy/config.yaml. This file controls options - typed values that determine the behaviour of mitmproxy. The options mechanism is very comprehensive - in fact, options control all of mitmproxy’s runtime behaviour. Most command-line flags are simply aliases for underlying options, and interactive settings changes made in mitmproxy and mitmweb just change values in our runtime options store. This means that almost any facet of mitmproxy’s behaviour can be controlled through options.

The canonical reference for options is the --options flag, which is exposed by each of the mitmproxy tools. Passing this flag will dump an annotated YAML configuration to console, which includes all options and their default values.

The options mechanism is extensible - third-party addons can define options that are treated exactly like mitmproxy’s own. This means that addons can also be configured through the central configuration file, and their options will appear in the options editors in interactive tools.

Tools

Both mitmproxy and mitmweb have built-in editors that let you view and manipulate the complete configuration state of mitmproxy. Values you change interactively have immediate effect in the running instance, and can be made persistent by saving the settings out to a YAML configuration file (please see the specific tool’s interactive help for details on how to do this).

For all tools, options can be set directly by name using the --set command-line option. Please see the command-line help (--help) for usage. Example:

mitmproxy --set anticomp=true
mitmweb --set ignore_hosts=example.com --set ignore_hosts=example.org

Available Options

This list might not reflect what is actually available in your current mitmproxy environment. For an up-to-date list please use the --options flag for each of the mitmproxy tools.

Name Type Description
add_upstream_certs_to_client_chain
mitmproxy mitmdump mitmweb		 bool Add all certificates of the upstream server to the certificate chain that will be served to the proxy client, as extras.
Default: False
allow_hosts
mitmproxy mitmdump mitmweb		 sequence of str Opposite of --ignore-hosts.
Default: []
anticache
mitmproxy mitmdump mitmweb		 bool Strip out request headers that might cause the server to return 304-not-modified.
Default: False
anticomp
mitmproxy mitmdump mitmweb		 bool Try to convince servers to send us un-compressed data.
Default: False
block_global
mitmproxy mitmdump mitmweb		 bool Block connections from public IP addresses.
Default: True
block_list
mitmproxy mitmdump mitmweb		 sequence of str Block matching requests and return an empty response with the specified HTTP status. Option syntax is "/flow-filter/status-code", where flow-filter describes which requests this rule should be applied to and status-code is the HTTP status code to return for blocked requests. The separator ("/" in the example) can be any character. Setting a non-standard status code of 444 will close the connection without sending a response.
Default: []
block_private
mitmproxy mitmdump mitmweb		 bool Block connections from local (private) IP addresses. This option does not affect loopback addresses (connections from the local machine), which are always permitted.
Default: False
body_size_limit
mitmproxy mitmdump mitmweb		 optional str Byte size limit of HTTP request and response bodies. Understands k/m/g suffixes, i.e. 3m for 3 megabytes.
Default: None
cert_passphrase
mitmproxy mitmdump mitmweb		 optional str Passphrase for decrypting the private key provided in the --cert option. Note that passing cert_passphrase on the command line makes your passphrase visible in your system's process list. Specify it in config.yaml to avoid this.
Default: None
certs
mitmproxy mitmdump mitmweb		 sequence of str SSL certificates of the form "[domain=]path". The domain may include a wildcard, and is equal to "*" if not specified. The file at path is a certificate in PEM format. If a private key is included in the PEM, it is used, else the default key in the conf dir is used. The PEM file should contain the full certificate chain, with the leaf certificate as the first entry.
Default: []
ciphers_client
mitmproxy mitmdump mitmweb		 optional str Set supported ciphers for client <-> mitmproxy connections using OpenSSL syntax.
Default: None
ciphers_server
mitmproxy mitmdump mitmweb		 optional str Set supported ciphers for mitmproxy <-> server connections using OpenSSL syntax.
Default: None
client_certs
mitmproxy mitmdump mitmweb		 optional str Client certificate file or directory.
Default: None
client_replay
mitmproxy mitmdump mitmweb		 sequence of str Replay client requests from a saved file.
Default: []
client_replay_concurrency
mitmproxy mitmdump mitmweb		 int Concurrency limit on in-flight client replay requests. Currently the only valid values are 1 and -1 (no limit).
Default: 1
command_history
mitmproxy mitmdump mitmweb		 bool Persist command history between mitmproxy invocations.
Default: True
confdir
mitmproxy mitmdump mitmweb		 str Location of the default mitmproxy configuration files.
Default: ~/.mitmproxy
connect_addr
mitmproxy mitmdump mitmweb		 optional str Set the local IP address that mitmproxy should use when connecting to upstream servers.
Default: None
connection_strategy
mitmproxy mitmdump mitmweb		 str Determine when server connections should be established. When set to lazy, mitmproxy tries to defer establishing an upstream connection as long as possible. This makes it possible to use server replay while being offline. When set to eager, mitmproxy can detect protocols with server-side greetings, as well as accurately mirror TLS ALPN negotiation.
Default: eager
Choices: eager, lazy
console_default_contentview
mitmproxy		 str The default content view mode.
Default: auto
Choices: auto, dns, graphql, grpc, hex dump, hex stream, http/3 frames, image, javascript, json, mqtt, msgpack, multipart form, protobuf, query, raw, socket.io, url-encoded, viewcss, wbxml, xml/html
console_eventlog_verbosity
mitmproxy		 str EventLog verbosity.
Default: info
Choices: error, warn, info, alert, debug
console_flowlist_layout
mitmproxy		 str Set the flowlist layout
Default: default
Choices: default, list, table
console_focus_follow
mitmproxy mitmweb		 bool Focus follows new flows.
Default: False
console_layout
mitmproxy		 str Console layout.
Default: single
Choices: horizontal, single, vertical
console_layout_headers
mitmproxy		 bool Show layout component headers
Default: True
console_mouse
mitmproxy		 bool Console mouse interaction.
Default: True
console_palette
mitmproxy		 str Color palette.
Default: solarized_dark
Choices: dark, light, lowdark, lowlight, solarized_dark, solarized_light
console_palette_transparent
mitmproxy		 bool Set transparent background for palette.
Default: True
console_strip_trailing_newlines
mitmproxy		 bool Strip trailing newlines from edited request/response bodies.
Default: False
content_view_lines_cutoff
mitmproxy mitmdump mitmweb		 int Flow content view lines limit. Limit is enabled by default to speedup flows browsing.
Default: 512
dns_name_servers
mitmproxy mitmdump mitmweb		 sequence of str Name servers to use for lookups. Default: operating system's name servers
Default: []
dns_use_hosts_file
mitmproxy mitmdump mitmweb		 bool Use the hosts file for DNS lookups in regular DNS mode/wireguard mode.
Default: True
dumper_default_contentview
mitmdump		 str The default content view mode.
Default: auto
Choices: auto, dns, graphql, grpc, hex dump, hex stream, http/3 frames, image, javascript, json, mqtt, msgpack, multipart form, protobuf, query, raw, socket.io, url-encoded, viewcss, wbxml, xml/html
dumper_filter
mitmdump		 optional str Limit which flows are dumped.
Default: None
export_preserve_original_ip
mitmproxy mitmdump mitmweb		 bool When exporting a request as an external command, make an effort to connect to the same IP as in the original request. This helps with reproducibility in cases where the behaviour depends on the particular host we are connecting to. Currently this only affects curl exports.
Default: False
flow_detail
mitmdump		 int The display detail level for flows in mitmdump: 0 (quiet) to 4 (very verbose). 0: no output 1: shortened request URL with response status code 2: full request URL with response status code and HTTP headers 3: 2 + truncated response content, content of WebSocket and TCP messages (content_view_lines_cutoff: 512) 4: 3 + nothing is truncated
Default: 1
hardump
mitmproxy mitmdump mitmweb		 str Save a HAR file with all flows on exit. You may select particular flows by setting save_stream_filter. For mitmdump, enabling this option will mean that flows are kept in memory.
Default:
http2
mitmproxy mitmdump mitmweb		 bool Enable/disable HTTP/2 support. HTTP/2 support is enabled by default.
Default: True
http2_ping_keepalive
mitmproxy mitmdump mitmweb		 int Send a PING frame if an HTTP/2 connection is idle for more than the specified number of seconds to prevent the remote site from closing it. Set to 0 to disable this feature.
Default: 58
http3
mitmproxy mitmdump mitmweb		 bool Enable/disable support for QUIC and HTTP/3. Enabled by default.
Default: True
http_connect_send_host_header
mitmproxy mitmdump mitmweb		 bool Include host header with CONNECT requests. Enabled by default.
Default: True
ignore_hosts
mitmproxy mitmdump mitmweb		 sequence of str Ignore host and forward all traffic without processing it. In transparent mode, it is recommended to use an IP address (range), not the hostname. In regular mode, only SSL traffic is ignored and the hostname should be used. The supplied value is interpreted as a regular expression and matched on the ip or the hostname.
Default: []
intercept
mitmproxy mitmweb		 optional str Intercept filter expression.
Default: None
intercept_active
mitmproxy mitmweb		 bool Intercept toggle
Default: False
keep_alt_svc_header
mitmproxy mitmdump mitmweb		 bool Reverse Proxy: Keep Alt-Svc headers as-is, even if they do not point to mitmproxy. Enabling this option may cause clients to bypass the proxy.
Default: False
keep_host_header
mitmproxy mitmdump mitmweb		 bool Reverse Proxy: Keep the original host header instead of rewriting it to the reverse proxy target.
Default: False
keepserving
mitmdump		 bool Continue serving after client playback, server playback or file read. This option is ignored by interactive tools, which always keep serving.
Default: False
key_size
mitmproxy mitmdump mitmweb		 int TLS key size for certificates and CA.
Default: 2048
listen_host
mitmproxy mitmdump mitmweb		 str Address to bind proxy server(s) to (may be overridden for individual modes, see `mode`).
Default:
listen_port
mitmproxy mitmdump mitmweb		 optional int Port to bind proxy server(s) to (may be overridden for individual modes, see `mode`). By default, the port is mode-specific. The default regular HTTP proxy spawns on port 8080.
Default: None
map_local
mitmproxy mitmdump mitmweb		 sequence of str Map remote resources to a local file using a pattern of the form "[/flow-filter]/url-regex/file-or-directory-path", where the separator can be any character.
Default: []
map_remote
mitmproxy mitmdump mitmweb		 sequence of str Map remote resources to another remote URL using a pattern of the form "[/flow-filter]/url-regex/replacement", where the separator can be any character.
Default: []
mode
mitmproxy mitmdump mitmweb		 sequence of str The proxy server type(s) to spawn. Can be passed multiple times. Mitmproxy supports "regular" (HTTP), "transparent", "socks5", "reverse:SPEC", "upstream:SPEC", and "wireguard[:PATH]" proxy servers. For reverse and upstream proxy modes, SPEC is host specification in the form of "http[s]://host[:port]". For WireGuard mode, PATH may point to a file containing key material. If no such file exists, it will be created on startup. You may append `@listen_port` or `@listen_host:listen_port` to override `listen_host` or `listen_port` for a specific proxy mode. Features such as client playback will use the first mode to determine which upstream server to use.
Default: ['regular']
modify_body
mitmproxy mitmdump mitmweb		 sequence of str Replacement pattern of the form "[/flow-filter]/regex/[@]replacement", where the separator can be any character. The @ allows to provide a file path that is used to read the replacement string.
Default: []
modify_headers
mitmproxy mitmdump mitmweb		 sequence of str Header modify pattern of the form "[/flow-filter]/header-name/[@]header-value", where the separator can be any character. The @ allows to provide a file path that is used to read the header value string. An empty header-value removes existing header-name headers.
Default: []
normalize_outbound_headers
mitmproxy mitmdump mitmweb		 bool Normalize outgoing HTTP/2 header names, but emit a warning when doing so. HTTP/2 does not allow uppercase header names. This option makes sure that HTTP/2 headers set in custom scripts are lowercased before they are sent.
Default: True
onboarding
mitmproxy mitmdump mitmweb		 bool Toggle the mitmproxy onboarding app.
Default: True
onboarding_host
mitmproxy mitmdump mitmweb		 str Onboarding app domain. For transparent mode, use an IP when a DNS entry for the app domain is not present.
Default: mitm.it
protobuf_definitions
mitmproxy mitmdump mitmweb		 optional str Path to a .proto file that's used to resolve Protobuf field names when pretty-printing.
Default: None
proxy_debug
mitmproxy mitmdump mitmweb		 bool Enable debug logs in the proxy core.
Default: False
proxyauth
mitmproxy mitmdump mitmweb		 optional str Require proxy authentication. Format: "username:pass", "any" to accept any user/pass combination, "@path" to use an Apache htpasswd file, or "ldap[s]:url_server_ldap[:port]:dn_auth:password:dn_subtree[?search_filter_key=...]" for LDAP authentication.
Default: None
rawtcp
mitmproxy mitmdump mitmweb		 bool Enable/disable raw TCP connections. TCP connections are enabled by default.
Default: True
readfile_filter
mitmproxy mitmdump mitmweb		 optional str Read only matching flows.
Default: None
request_client_cert
mitmproxy mitmdump mitmweb		 bool Requests a client certificate (TLS message 'CertificateRequest') to establish a mutual TLS connection between client and mitmproxy (combined with 'client_certs' option for mitmproxy and upstream).
Default: False
rfile
mitmproxy mitmdump mitmweb		 optional str Read flows from file.
Default: None
save_stream_file
mitmproxy mitmdump mitmweb		 optional str Stream flows to file as they arrive. Prefix path with + to append. The full path can use python strftime() formating, missing directories are created as needed. A new file is opened every time the formatted string changes.
Default: None
save_stream_filter
mitmproxy mitmdump mitmweb		 optional str Filter which flows are written to file.
Default: None
scripts
mitmproxy mitmdump mitmweb		 sequence of str Execute a script.
Default: []
server
mitmproxy mitmdump mitmweb		 bool Start a proxy server. Enabled by default.
Default: True
server_replay
mitmproxy mitmdump mitmweb		 sequence of str Replay server responses from a saved file.
Default: []
server_replay_extra
mitmproxy mitmdump mitmweb		 str Behaviour for extra requests during replay for which no replayable response was found. Setting a numeric string value will return an empty HTTP response with the respective status code.
Default: forward
Choices: forward, kill, 204, 400, 404, 500
server_replay_ignore_content
mitmproxy mitmdump mitmweb		 bool Ignore request content while searching for a saved flow to replay.
Default: False
server_replay_ignore_host
mitmproxy mitmdump mitmweb		 bool Ignore request destination host while searching for a saved flow to replay.
Default: False
server_replay_ignore_params
mitmproxy mitmdump mitmweb		 sequence of str Request parameters to be ignored while searching for a saved flow to replay.
Default: []
server_replay_ignore_payload_params
mitmproxy mitmdump mitmweb		 sequence of str Request payload parameters (application/x-www-form-urlencoded or multipart/form-data) to be ignored while searching for a saved flow to replay.
Default: []
server_replay_ignore_port
mitmproxy mitmdump mitmweb		 bool Ignore request destination port while searching for a saved flow to replay.
Default: False
server_replay_kill_extra
mitmproxy mitmdump mitmweb		 bool Kill extra requests during replay (for which no replayable response was found).[Deprecated, prefer to use server_replay_extra='kill']
Default: False
server_replay_nopop
mitmproxy mitmdump mitmweb		 bool Deprecated alias for `server_replay_reuse`.
Default: False
server_replay_refresh
mitmproxy mitmdump mitmweb		 bool Refresh server replay responses by adjusting date, expires and last-modified headers, as well as adjusting cookie expiration.
Default: True
server_replay_reuse
mitmproxy mitmdump mitmweb		 bool Don't remove flows from server replay state after use. This makes it possible to replay same response multiple times.
Default: False
server_replay_use_headers
mitmproxy mitmdump mitmweb		 sequence of str Request headers that need to match while searching for a saved flow to replay.
Default: []
show_ignored_hosts
mitmproxy mitmdump mitmweb		 bool Record ignored flows in the UI even if we do not perform TLS interception. This option will keep ignored flows' contents in memory, which can greatly increase memory usage. A future release will fix this issue, record ignored flows by default, and remove this option.
Default: False
showhost
mitmproxy mitmdump mitmweb		 bool Use the Host header to construct URLs for display. This option is disabled by default because malicious apps may send misleading host headers to evade your analysis. If this is not a concern, enable this options for better flow display.
Default: False
ssl_insecure
mitmproxy mitmdump mitmweb		 bool Do not verify upstream server SSL/TLS certificates. If this option is enabled, certificate validation is skipped and mitmproxy itself will be vulnerable to TLS interception.
Default: False
ssl_verify_upstream_trusted_ca
mitmproxy mitmdump mitmweb		 optional str Path to a PEM formatted trusted CA certificate.
Default: None
ssl_verify_upstream_trusted_confdir
mitmproxy mitmdump mitmweb		 optional str Path to a directory of trusted CA certificates for upstream server verification prepared using the c_rehash tool.
Default: None
stickyauth
mitmproxy mitmdump mitmweb		 optional str Set sticky auth filter. Matched against requests.
Default: None
stickycookie
mitmproxy mitmdump mitmweb		 optional str Set sticky cookie filter. Matched against requests.
Default: None
store_streamed_bodies
mitmproxy mitmdump mitmweb		 bool Store HTTP request and response bodies when streamed (see `stream_large_bodies`). This increases memory consumption, but makes it possible to inspect streamed bodies.
Default: False
stream_large_bodies
mitmproxy mitmdump mitmweb		 optional str Stream data to the client if request or response body exceeds the given threshold. If streamed, the body will not be stored in any way, and such responses cannot be modified. Understands k/m/g suffixes, i.e. 3m for 3 megabytes. To store streamed bodies, see `store_streamed_bodies`.
Default: None
strip_ech
mitmproxy mitmdump mitmweb		 bool Strip Encrypted ClientHello (ECH) data from DNS HTTPS records so that mitmproxy can generate matching certificates.
Default: True
tcp_hosts
mitmproxy mitmdump mitmweb		 sequence of str Generic TCP SSL proxy mode for all hosts that match the pattern. Similar to --ignore-hosts, but SSL connections are intercepted. The communication contents are printed to the log in verbose mode.
Default: []
termlog_verbosity
mitmdump mitmweb		 str Log verbosity.
Default: info
Choices: error, warn, info, alert, debug
tls_ecdh_curve_client
mitmproxy mitmdump mitmweb		 optional str Use a specific elliptic curve for ECDHE key exchange on client connections. OpenSSL syntax, for example "prime256v1" (see `openssl ecparam -list_curves`).
Default: None
tls_ecdh_curve_server
mitmproxy mitmdump mitmweb		 optional str Use a specific elliptic curve for ECDHE key exchange on server connections. OpenSSL syntax, for example "prime256v1" (see `openssl ecparam -list_curves`).
Default: None
tls_version_client_max
mitmproxy mitmdump mitmweb		 str Set the maximum TLS version for client connections.
Default: UNBOUNDED
Choices: UNBOUNDED, SSL3, TLS1, TLS1_1, TLS1_2, TLS1_3
tls_version_client_min
mitmproxy mitmdump mitmweb		 str Set the minimum TLS version for client connections. UNBOUNDED, SSL3, TLS1 and TLS1_1 are insecure.
Default: TLS1_2
Choices: UNBOUNDED, SSL3, TLS1, TLS1_1, TLS1_2, TLS1_3
tls_version_server_max
mitmproxy mitmdump mitmweb		 str Set the maximum TLS version for server connections.
Default: UNBOUNDED
Choices: UNBOUNDED, SSL3, TLS1, TLS1_1, TLS1_2, TLS1_3
tls_version_server_min
mitmproxy mitmdump mitmweb		 str Set the minimum TLS version for server connections. UNBOUNDED, SSL3, TLS1 and TLS1_1 are insecure.
Default: TLS1_2
Choices: UNBOUNDED, SSL3, TLS1, TLS1_1, TLS1_2, TLS1_3
udp_hosts
mitmproxy mitmdump mitmweb		 sequence of str Generic UDP SSL proxy mode for all hosts that match the pattern. Similar to --ignore-hosts, but SSL connections are intercepted. The communication contents are printed to the log in verbose mode.
Default: []
upstream_auth
mitmproxy mitmdump mitmweb		 optional str Add HTTP Basic authentication to upstream proxy and reverse proxy requests. Format: username:password.
Default: None
upstream_cert
mitmproxy mitmdump mitmweb		 bool Connect to upstream server to look up certificate details.
Default: True
validate_inbound_headers
mitmproxy mitmdump mitmweb		 bool Make sure that incoming HTTP requests are not malformed. Disabling this option makes mitmproxy vulnerable to HTTP smuggling attacks.
Default: True
view_filter
mitmproxy mitmweb		 optional str Limit the view to matching flows.
Default: None
view_order
mitmproxy mitmweb		 str Flow sort order.
Default: time
Choices: time, method, url, size
view_order_reversed
mitmproxy mitmweb		 bool Reverse the sorting order.
Default: False
web_columns
mitmweb		 sequence of str Columns to show in the flow list. Can be one of the following: icon, index, method, version, path, quickactions, size, status, time, timestamp, tls, comment
Default: ['tls', 'icon', 'path', 'method', 'status', 'size', 'time']
web_debug
mitmweb		 bool Enable mitmweb debugging.
Default: False
web_host
mitmweb		 str Web UI host.
Default: 127.0.0.1
web_open_browser
mitmweb		 bool Start a browser.
Default: True
web_password
mitmweb		 str Password to protect the mitmweb user interface. Values starting with `$` are interpreted as an argon2 hash, everything else is considered a plaintext password. If no password is provided, a random token is generated on startup.
Default:
web_port
mitmweb		 int Web UI port.
Default: 8081
web_static_viewer
mitmweb		 optional str The path to output a static viewer.
Default:
websocket
mitmproxy mitmdump mitmweb		 bool Enable/disable WebSocket support. WebSocket support is enabled by default.
Default: True