mitmproxy

README

mitmproxy

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

Usage

$ 

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