mitmproxy

Auto-generated from mitmproxy/mitmproxy by Mutable.ai Auto WikiRevise

mitmproxy is a powerful, open-source, interactive HTTPS proxy that allows users to intercept, inspect, and modify network traffic. It provides a comprehensive set of tools and features for web development, security testing, and network analysis.

The core functionality of mitmproxy is implemented in the mitmproxy directory, which contains over 100 files and 10 subdirectories. The most important components include:

• The Proxy Server: The …/server.py file defines the ConnectionHandler and LiveConnectionHandler classes, which are responsible for handling client and server connections, processing events and commands, and managing the lifecycle of network flows.
• The Protocol Layers: The …/layers directory contains the implementation of various protocol layers, such as HttpLayer, WebsocketLayer, QuicLayer, TCPLayer, UDPLayer, and DNSLayer. These layers handle the specifics of each network protocol and provide a flexible and extensible architecture for processing requests, responses, and events.
• The Network Utilities: The …/net directory provides a collection of networking-related utilities and functionality, including modules for working with DNS, HTTP, SSL/TLS, and other network protocols and concepts.
• The Core Types and Serialization: The …/coretypes directory contains utility classes and functions used throughout the mitmproxy codebase, such as BiDi for bi-directional mappings, MultiDict for dictionary-like data structures, and Serializable for object serialization and deserialization.

In addition to the core proxy functionality, mitmproxy also provides several user interfaces, including a Console Interface, a Web Interface, and a Command-Line Interface. These interfaces allow users to interact with the proxy, view and manipulate network traffic, and customize the behavior of the tool.

The mitmproxy project also supports a powerful Content Views system, which is responsible for formatting, decoding, and highlighting data for various protocols and data formats. This system includes built-in views for HTTP, WebSocket, QUIC, TCP, UDP, DNS, and a variety of other data formats.

Finally, mitmproxy provides an Addons and Scripting system that allows users to extend the functionality of the tool and customize its behavior. Addons can be used to intercept, modify, and analyze HTTP and WebSocket traffic, as well as handle other network protocols and events.

References: mitmproxy, mitmproxy/proxy, mitmproxy/net

The core functionality of the mitmproxy application is centered around the implementation of the network proxy server and the various protocol layers it supports. The key components and design choices in this area are:

References: mitmproxy/proxy/server.py, mitmproxy/proxy/layers

The core implementation of the mitmproxy network proxy is handled by the mitmproxy/mitmproxy/proxy/server.py file. This file defines several key components that work together to provide the core functionality of the proxy server:

References: mitmproxy/proxy/layers

The implementation of the various protocol layers used by the mitmproxy proxy, such as HTTP, WebSocket, QUIC, TCP, UDP, and DNS, is primarily handled in the …/layers directory.

References: mitmproxy/net, mitmproxy/net/http, mitmproxy/net/dns

The …/net directory contains a collection of Python modules that provide various networking-related utilities and functionality for the mitmproxy project. This includes modules for working with DNS, HTTP, SSL/TLS, and other network protocols and concepts.

References: mitmproxy/coretypes, mitmproxy/io

The …/coretypes directory contains several important utility classes and functions that are used throughout the mitmproxy codebase. The main components in this directory are:

References: mitmproxy/proxy/layers/modes.py

The mitmproxy/mitmproxy/proxy/layers/modes.py file defines several classes that handle different proxy modes in the mitmproxy application. These classes are responsible for managing the connection between the client and the server, and for handling the various protocols and authentication methods that may be used.

References: mitmproxy/io

The …/io directory contains the core functionality for reading, writing, and managing HTTP flow data in the mitmproxy project. The main components are:

References: mitmproxy/tools

The mitmproxy project provides several user interfaces for interacting with the proxy, including a console-based interface, a web-based interface, and a command-line interface.

References: mitmproxy/tools/console

The console-based user interface for mitmproxy is implemented in the …/console directory. This interface provides a comprehensive set of tools and features for interacting with the mitmproxy application, including:

References: mitmproxy/tools/web

The web-based user interface for mitmproxy is implemented in the …/web directory. This directory contains the main HTML template, CSS and JavaScript files for the web application, as well as the request handlers and WebSocket functionality that power the interactive features of the web UI.

References: mitmproxy/tools/cmdline.py, mitmproxy/tools/dump.py, mitmproxy/tools/main.py

The command-line interface for mitmproxy is implemented in the …/cmdline.py file. This file defines several functions that set up the argument parsers for the different mitmproxy commands: mitmproxy, mitmdump, and mitmweb.

References: mitmproxy/contentviews

The mitmproxy/mitmproxy/contentviews directory contains a collection of content views that can be used to format, decode, and highlight data in the mitmproxy tool. These content views support various protocols, such as HTTP, WebSocket, TCP, and UDP.

References: mitmproxy/contentviews

The …/contentviews directory contains a collection of content views that can be used to format, decode, and highlight data in the mitmproxy tool. These content views support various protocols, such as HTTP, WebSocket, TCP, and UDP.

References: mitmproxy/contentviews/__init__.py

The View class is the core abstraction for content views in mitmproxy. It defines the API for content views, which are responsible for formatting, decoding, and highlighting data for various protocols and data formats.

References: mitmproxy/contentviews/auto.py

The ViewAuto class is responsible for automatically selecting the most appropriate content view for the given data. It is a subclass of the base.View class.

References: mitmproxy/contentviews/base.py

The mitmproxy/mitmproxy/contentviews/base.py file defines the base functionality for content views in the mitmproxy project. Content views are responsible for transforming raw data into human-readable output.

References: mitmproxy/contentviews/css.py

The ViewCSS class provides a custom CSS prettifier implementation in the mitmproxy project. This class is responsible for formatting and displaying CSS data within the mitmproxy user interface.

References: mitmproxy/contentviews/dns.py

The ViewDns class in the …/dns.py file is responsible for rendering DNS-over-HTTPS (DoH) traffic in the mitmproxy tool. This class inherits from the base.View class and provides a custom content view for displaying the contents of DNS messages in a user-friendly format.

References: mitmproxy/contentviews/graphql.py

The ViewGraphQL class is responsible for handling the display of GraphQL queries and responses within the mitmproxy tool. This class is a subclass of base.View and provides specialized functionality for formatting and rendering GraphQL data.

References: mitmproxy/contentviews/grpc.py

The ViewGrpcProtobuf class is responsible for parsing and displaying Protocol Buffer (Protobuf) and gRPC messages in the mitmproxy application. This class inherits from the base.View class and provides a human-friendly view of Protobuf and gRPC messages.

References: mitmproxy/contentviews/hex.py

The ViewHexDump and ViewHexStream classes in the …/hex.py file provide different views for displaying hexadecimal data in the mitmproxy application.

References: mitmproxy/contentviews/http3.py

The ViewHttp3 class is responsible for parsing and displaying HTTP/3 frames in the mitmproxy tool. It is the main entry point for processing HTTP/3 data and is implemented in the …/http3.py file.

References: mitmproxy/contentviews/javascript.py

The ViewJavaScript class in …/javascript.py provides a custom implementation for rendering JavaScript content in the mitmproxy tool. This class is responsible for formatting and displaying JavaScript code in a more readable and user-friendly way.

References: mitmproxy/contentviews/json.py

The ViewJSON class is responsible for parsing and formatting JSON data within the mitmproxy content viewing system. It is a subclass of the base.View class, which provides the core functionality for content viewers in mitmproxy.

References: mitmproxy/contentviews/mqtt.py

The ViewMQTT class in the mitmproxy/mitmproxy/contentviews/mqtt.py file is responsible for handling the display of MQTT (Message Queuing Telemetry Transport) protocol packets within the mitmproxy tool.

References: mitmproxy/contentviews/msgpack.py

The ViewMsgPack class in the mitmproxy/mitmproxy/contentviews/msgpack.py file provides a view for rendering MessagePack data within the mitmproxy application. This class is responsible for parsing and formatting MessagePack data, allowing users to inspect and understand the contents of MessagePack-encoded messages.

References: mitmproxy/contentviews/multipart.py

The ViewMultipart class is responsible for parsing and displaying multipart form data in the mitmproxy application. This class is part of the mitmproxy/mitmproxy/contentviews/multipart.py module.

References: mitmproxy/contentviews/protobuf.py

The ViewProtobuf class provides a human-friendly view for displaying Protocol Buffer (Protobuf) data within the mitmproxy application. This class is responsible for parsing and formatting Protobuf data in a way that is easy for users to understand.

References: mitmproxy/contentviews/query.py

The ViewQuery class in the mitmproxy/mitmproxy/contentviews/query.py file is responsible for rendering the query parameters of an HTTP message. This class inherits from the base.View class and provides two main methods:

References: mitmproxy/contentviews/raw.py

The ViewRaw class provides a simple "Raw" view for displaying the raw content of a request or response in the mitmproxy tool. This class is defined in the …/raw.py file.

References: mitmproxy/contentviews/urlencoded.py

The ViewURLEncoded class in the …/urlencoded.py file is responsible for handling the parsing and rendering of URL-encoded form data within the mitmproxy tool.

References: mitmproxy/contentviews/wbxml.py

The ViewWBXML class in the …/wbxml.py file is responsible for parsing and displaying WBXML (Wireless Binary XML) content within the mitmproxy tool.

References: mitmproxy/contentviews/xml_html.py

The ViewXmlHtml class provides a custom XML/HTML prettifier implementation in the mitmproxy project. This class is responsible for rendering the formatted XML/HTML content within the mitmproxy application.

References: mitmproxy/contentviews/image

The …/image directory provides functionality for parsing and displaying image data within the mitmproxy application. The main component in this directory is the ViewImage class, which is responsible for rendering and displaying image content.

References: mitmproxy/addons, examples

The mitmproxy project provides a powerful addon and scripting system that allows users to extend the functionality of the tool and customize its behavior. The core of this system is the …/addons directory, which contains a collection of addons that provide a wide range of features.

References: examples/addons/anatomy.py, examples/addons/anatomy2.py

The mitmproxy/examples/addons/anatomy.py file provides a basic example of a mitmproxy addon. The addon is a simple Counter class that logs the number of flows it has seen.

References: examples/addons/commands-flows.py, examples/addons/commands-paths.py

The commands-flows.py file demonstrates how to handle HTTP flows as command arguments in mitmproxy addons. The main component is the MyAddon class, which defines a custom command called myaddon.addheader.

References: examples/addons/http-stream-simple.py, examples/addons/http-stream-modify.py, examples/addons/http-trailers.py

The http-stream-simple.py and http-stream-modify.py addons demonstrate how to work with streaming HTTP responses in mitmproxy, while the http-trailers.py addon shows how to handle HTTP trailers.

References: examples/addons/contentview-custom-grpc.py, examples/addons/contentview.py

The ViewGrpcWithRules class in …/contentview-custom-grpc.py provides a custom version of the gRPC/protobuf content view in the mitmproxy library. This custom view allows parsing of protobuf messages based on a user-defined set of rules.

References: examples/addons/websocket-simple.py, examples/addons/websocket-inject-message.py, examples/addons/tcp-simple.py

The websocket-simple.py and websocket-inject-message.py files in the …/addons directory demonstrate how to process and manipulate WebSocket connections using the mitmproxy library.

References: examples/contrib

The …/contrib directory contains a collection of community-contributed addons and examples for the mitmproxy tool. These addons provide a wide range of functionality, including:

References: mitmproxy/utils

The …/ directory contains a collection of utility functions and classes that provide various functionality to support the mitmproxy application. The utilities cover a wide range of tasks, including:

References: mitmproxy/utils/arg_check.py

The mitmproxy/mitmproxy/utils/arg_check.py file is responsible for validating and handling command-line arguments used in the mitmproxy application. It provides the following key functionality:

References: mitmproxy/utils/asyncio_utils.py

The mitmproxy/mitmproxy/utils/asyncio_utils.py file provides a set of utility functions and context managers for working with asyncio in the mitmproxy codebase.

References: mitmproxy/utils/bits.py

The setbit() and getbit() functions in the …/bits.py file provide a way to set and retrieve individual bits within a byte.

References: mitmproxy/utils/data.py

The Data class, defined in …/data.py, provides a way to access package data files relative to a module's location. This is useful for accessing configuration files, assets, or other resources that are distributed alongside the mitmproxy application.

References: mitmproxy/utils/debug.py

The mitmproxy/mitmproxy/utils/debug.py file provides a set of utility functions that can be used to debug and inspect the state of the mitmproxy application. These functions offer valuable insights into the running process, including information about threads, file descriptors, memory usage, open files, network connections, and running tasks.

References: mitmproxy/utils/emoji.py

The emoji dictionary in the …/emoji.py file provides a mapping of emoji and character names to their corresponding Unicode representations. This dictionary contains a wide range of emojis and symbols across various categories, such as:

References: mitmproxy/utils/human.py

The mitmproxy/mitmproxy/utils/human.py file provides a set of utility functions for formatting data in a human-readable way. These functions handle common data types such as file sizes, durations, and timestamps, ensuring that the output is concise and easy to understand.

References: mitmproxy/utils/magisk.py

The mitmproxy/utils/magisk.py file provides the functionality for packaging the MITMProxy certificate as a Magisk module for Android devices. Magisk is a popular Android root solution that allows for system-level modifications, and this module enables users to easily install the MITMProxy certificate on their Android devices.

References: mitmproxy/utils/signals.py

The mitmproxy/mitmproxy/utils/signals.py file provides a simple dispatching system for subscribing to and notifying events in the mitmproxy project. It supports both synchronous and asynchronous receivers, and uses weak references to avoid keeping receivers alive unnecessarily.

References: mitmproxy/utils/sliding_window.py

The window() function in …/sliding_window.py creates a sliding window over an input iterator. This function takes an Iterable[T] and two optional integer parameters, behind and ahead, and returns an Iterator[tuple[T | None, ...]].

References: mitmproxy/utils/strutils.py

The mitmproxy/mitmproxy/utils/strutils.py file provides a set of utility functions for working with strings and bytes in the mitmproxy project. The main functionalities include:

References: mitmproxy/utils/typecheck.py

The mitmproxy/mitmproxy/utils/typecheck.py file provides utility functions for type checking, specifically for handling options in the mitmproxy application.

References: mitmproxy/utils/vt_codes.py

The mitmproxy/mitmproxy/utils/vt_codes.py file provides a utility function ensure_supported() that detects if a given file object supports virtual terminal escape codes. This is an important functionality for implementing terminal-specific features, such as colored output, in a cross-platform manner.

References: mitmproxy/utils/pyinstaller

The PyInstaller Configuration subsection discusses the configuration files and utility functions related to the PyInstaller tool, which is used to create standalone executable files from the mitmproxy application.

References: web/src

The mitmproxy web application is implemented in the …/src directory, which contains the core functionality of the application, including the user interface, state management, network flow handling, and utility functions.

References: web/src/js/components

The …/components directory contains the core React components that make up the user interface of the mitmproxy web application. These components handle various functionalities, such as rendering the flow table, displaying the details of a selected flow, managing the application header and footer, and providing a command-line interface.

References: web/src/js/ducks

The Redux-based state management system used in the mitmproxy web application covers the management of user interface state, network flows, options, backend connection, and event logging.

References: web/src/js/backends, web/src/js/flow

The WebsocketBackend class in the …/websocket.tsx file is responsible for managing the WebSocket connection to the server and updating the application's state based on the data received through the WebSocket. It fetches initial data from the REST API and then listens for updates from the WebSocket connection, dispatching actions to the Redux store to update the application state accordingly.

References: web/src/js/contrib

The …/contrib directory contains two important files that provide utility functions and helper components used throughout the mitmproxy web application: