mitmproxy

README

mitmproxy

Man-in-the-Middle HTTP proxy implemented in Go with very few dependencies outside stdlib.

Requirements

• Go v1.15 (not tested, but should work with >1.11)

Installation

$ go install -u github.com/akabos/mitmproxy/cmd 

Usage

$ mitmproxy 

Running pre-built docker image:

$ docker run -rm -p 8080:8080 akabos/mitmproxy

Proxy headers

According to RFC 2616, the Via general-header field MUST be used by gateways and proxies to indicate the intermediate protocols and recipients between the user agent and the server on requests, and between the origin server and the client on responses. By default, mitmproxy obeys that requirement and adds an aforementioned header to each request, including those intercepted from CONNECT sessions. It also appends client IP to X-Forwarded-For header which is not defined by any RFC but is well known.

If that is not what you want, you have to explicitly disable that behaviour:

$ mitmproxy -novia -noxforwardedfor

Goals

• performance
• extensibility

Non-goals

• GUI
• transparent HTTPS proxying capabilities

TODO

• Examples
• Better test coverage

Documentation

Index

• Constants
• Variables
• func Latency(rq *http.Request) time.Duration
• func Parent(rq *http.Request) *http.Request
• func Seq(rq *http.Request) uint64
• func Subseq(rq *http.Request) uint64
• type Issuer
• type Proxy
  • func (p *Proxy) ServeHTTP(w http.ResponseWriter, rq *http.Request)
• type SelfSignedCA
  • func (ca *SelfSignedCA) Issue(cn string, dnsnames []string, ipaddresses []net.IP) (*tls.Certificate, error)

Constants

const DefaultCertCacheSize = 1 << 10

DefaultCertCacheSize is the default size for Proxy's certificates LRU cache

const DefaultIssuerBitSize = 1024

DefaultIssuerBitSize defines default bit size for issued certs.

const DefaultIssuerRootBitSize = 2048

DefaultIssuerRootBitSize defines default bit size for a self-signed root cert.

Variables

var (
	// DefaultIssuerRootTmpl is the default template for self-signed root CA certificate.
	DefaultIssuerRootTmpl = x509.Certificate{
		SerialNumber: big.NewInt(1),
		Issuer: pkix.Name{
			CommonName:   "issuer.example.org",
			Organization: []string{"MITMProxy Issuer Org"},
		},
		Subject: pkix.Name{
			CommonName:   "root.example.org",
			Organization: []string{"MITMProxy Root Org"},
		},
		NotBefore:             time.Now(),
		NotAfter:              time.Now().Add(time.Hour * 24 * 365 * 2),
		IsCA:                  true,
		BasicConstraintsValid: true,
		OCSPServer:            []string{"ocsp.example.org"},
		DNSNames:              []string{"root.example.org"},
		SignatureAlgorithm:    x509.SHA1WithRSA,
		KeyUsage:              x509.KeyUsageCertSign,
	}

	// DefaultIssuerTmpl is the default template for issued certificates.
	DefaultIssuerTmpl = x509.Certificate{
		SerialNumber: big.NewInt(1),
		Subject: pkix.Name{
			Country:      []string{"AQ"},
			Organization: []string{"MITMProxy"},
		},
		KeyUsage:    x509.KeyUsageDigitalSignature,
		ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
	}
)

var DefaultAccessLogger = log.New(os.Stdout, "", log.LstdFlags|log.Lmsgprefix)

DefaultAccessLogger is the default logger for writing access log

var DefaultErrorLogger = log.New(os.Stderr, "ERR: ", log.LstdFlags|log.Lmsgprefix|log.Lshortfile)

DefaultErrorLogger is the default logger for writing error log

var DefaultIssuer = &SelfSignedCA{}

DefaultIssuer is the default Issuer instance.

var DefaultProxy = &Proxy{}

DefaultProxy is the instance of Proxy with default parameters

var DefaultTransport = defaultTransport()

DefaultTransport defines the default transport for proxy to make HTTP(S) requests to target servers.

Functions

func Latency

func Latency(rq *http.Request) time.Duration

Latency returns effective latency of a given http.Request. Returns 0 if http.Request round trip have never been completed.

func Parent

func Parent(rq *http.Request) *http.Request

Parent returns parent CONNECT http.Request. Returns nil if request doesn't have a parent.

func Seq

func Seq(rq *http.Request) uint64

Seq returns sequence number of a request.

For plain HTTP or CONNECT requests it returns own requests' sequence number. For sub-requests generated by a CONNECT request it returns sequence number of the original CONNECT request. Sequence number MUST be present in the context. The absence of one results in panic.

func Subseq

func Subseq(rq *http.Request) uint64

Subseq returns subsequence number of a request.

It is always 0 for plain HTTP or CONNECT requests. For sub-requests generated by a CONNECT request it returns 1-based sequence number of each request.

Types

type Issuer

type Issuer interface {
	Issue(cn string, dnsnames []string, ipaddresses []net.IP) (*tls.Certificate, error)
}

Issuer defines interface for on-flight certificate generator

type Proxy

type Proxy struct {
	// Transport specifies optional transport to use for making HTTP(S) requests to target servers.
	//
	// If Transport is nil, DefaultTransport is used.
	Transport http.RoundTripper

	// AccessLogger is an optional logger used for access logging.
	//
	// If AccessLogger is nil, DefaultAccessLogger is used.
	AccessLogger *log.Logger

	// ErrorLogger is an optional logger for non-access related log messages.
	//
	// If ErrorLogger is nil, DefaultErrorLogger is used.
	ErrorLogger *log.Logger

	// NotFoundHandler specifies optional handler for non-proxy requests.
	//
	// If NotFoundHandler is nil, http.NotFound handler used.
	NotFoundHandler http.Handler

	// Issuer specifies optional certificate issuer.
	//
	// If Issuer is nil, DefaultIssuer is used.
	Issuer Issuer

	// RequestTimeout is an optional timeout for any HTTP or CONNECT request to finish. It doesn't directly affect
	// CONNECT sub-requests. If not set, there's no timeout implied.
	RequestTimeout time.Duration

	// SubRequestTimeout is an optional timeout for CONNECT sub-requests. If not set, there's no timeout implied.
	SubRequestTimeout time.Duration

	// CertCacheSize specifies the size of issued certificates LRU cache.
	//
	// If CertCacheSize < 1, DefaultCertCacheSize is used.
	CertCacheSize int

	// DisableViaHeader controls addition of Via header as defined in https://tools.ietf.org/html/rfc2616#section-14.45
	//
	// If disabled, the value of the header will pass through unchanged if present in the original request.
	DisableViaHeader bool

	// DisableXForwardedFor controls addition of Via header as described in
	// https://en.wikipedia.org/wiki/X-Forwarded-For
	//
	// If disabled, the value of the header will pass through unchanged if present in the original request.
	DisableXForwardedFor bool

	// Handle is a token the proxy use to identify itself in Via header. If not specified, hostname is used. If unable
	// to get the hostname, `mitmproxy` is used.
	Handle string
	// contains filtered or unexported fields
}

Proxy defines parameters for running a MITM HTTP proxy. The zero value for Proxy is a valid configuration.

func (*Proxy) ServeHTTP

func (p *Proxy) ServeHTTP(w http.ResponseWriter, rq *http.Request)

type SelfSignedCA

type SelfSignedCA struct {
	// Cert is a cert chain used to sign newly issued certs. The cert's primary usage must be x509.KeyUsageCertSign
	//
	// If nil, a self-signed cert will be generated.
	Cert *tls.Certificate

	// BitSize defines bit size for issued certificate keys generation.
	//
	// If 0, DefaultIssuerBitSize will be used.
	BitSize int

	// RootBitSize defines bit size for self-signed root certificate key generation.
	//
	// If 0, DefaultIssuerRootBitSize will be used.
	RootBitSize int

	// Tmpl is a template for issued certificates.
	//
	// If nil, DefaultIssuerTmpl will be used.
	Tmpl *x509.Certificate

	// RootTmpl is a template for self-signed root certificate.
	//
	// If nil, DefaultIssuerRootTmpl will be used.
	RootTmpl *x509.Certificate

	// Rand is a source of randomness for generated certs.
	//
	// If nil, crypto/rand.Reader will be used.
	Rand io.Reader
	// contains filtered or unexported fields
}

SelfSignedCA defines an Issuer. Zero value is a valid instance.

func (*SelfSignedCA) Issue

func (ca *SelfSignedCA) Issue(cn string, dnsnames []string, ipaddresses []net.IP) (*tls.Certificate, error)

Issue implements Issuer interface