mitm

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: BSD-3-Clause Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultListenAddr = "127.0.0.1:9090"
	// DefaultMaxBody is the largest body kept per request or response;
	// larger bodies stream through uncaptured.
	DefaultMaxBody int64 = 10 << 20
)
View Source
const CertSiteHost = "chapar.mitm"

CertSiteHost is the made-up host that serves the CA download page to any client sending its traffic through the proxy.

View Source
const DefaultMaxBytes int64 = 256 << 20

DefaultMaxBytes is how many body bytes the store keeps before dropping the oldest flows.

View Source
const DefaultMaxFlows = 5000

DefaultMaxFlows is how many flows the store keeps before dropping the oldest.

Variables

View Source
var ErrManualTrust = errors.New("install the certificate manually on this system")

ErrManualTrust means this OS has no automatic install; show the steps from TrustSteps instead.

View Source
var ErrSystemProxyUnknown = errors.New("system proxy setting can't be read on this system")

ErrSystemProxyUnknown means this OS's setting can't be read.

Functions

func CAExists

func CAExists(dir string) bool

CAExists reports whether dir holds a CA key and certificate.

func CanInstallTrust

func CanInstallTrust() bool

CanInstallTrust reports whether InstallTrust works on this OS.

func ClientEnv

func ClientEnv(addr string, ca *CA) string

ClientEnv is a shell snippet that points CLI tools at the proxy and makes them trust the CA without touching the OS store.

func Curl

func Curl(f *Flow) string

Curl returns a shell command that sends the flow's request again. Every value is single-quoted, so it pastes safely into sh, bash and zsh. A binary body is piped in through base64.

func HAR

func HAR(flows []*Flow, creatorVersion string) ([]byte, error)

HAR encodes flows as a HAR 1.2 log. Pending flows and tunnels that were not decrypted are left out: they have no request or response to show. Bodies are the decoded ones Chapar kept; a binary body is base64.

func InstallTrust

func InstallTrust(ctx context.Context, ca *CA) error

InstallTrust adds the CA to the user's trust store. On macOS it adds it to the login keychain as a trusted root, which makes macOS ask for the user's password. It blocks until the user answers.

func LANAddrs

func LANAddrs() []string

LANAddrs lists this machine's IPv4 addresses on active non-loopback interfaces, the ones other devices can reach.

func MatchHost

func MatchHost(pats []string, host string) bool

MatchHost reports whether host matches one of pats. A plain pattern matches the host and its subdomains; "*.example.com" matches only subdomains; other wildcards use path.Match.

func RemoveCA

func RemoveCA(dir string) error

RemoveCA deletes the CA files in dir.

func RemoveTrust

func RemoveTrust(ctx context.Context, ca *CA) error

RemoveTrust takes the CA out of the user's trust store.

Types

type CA

type CA struct {
	// contains filtered or unexported fields
}

CA is the root certificate the proxy signs per-host certificates with. It satisfies go-mitmproxy's cert.CA interface.

func CreateCA

func CreateCA(dir string) (*CA, error)

CreateCA generates a new CA and writes it to dir, replacing any CA there.

func LoadCA

func LoadCA(dir string) (*CA, error)

LoadCA reads the CA stored in dir.

func LoadOrCreateCA

func LoadOrCreateCA(dir string) (*CA, error)

LoadOrCreateCA loads the CA in dir, creating one when none exists.

func (*CA) CertDER

func (ca *CA) CertDER() []byte

CertDER returns the CA certificate in DER form.

func (*CA) CertPEM

func (ca *CA) CertPEM() []byte

CertPEM returns the CA certificate in PEM form.

func (*CA) CertPath

func (ca *CA) CertPath() string

CertPath is the PEM file holding only the CA certificate.

func (*CA) Fingerprint

func (ca *CA) Fingerprint() string

Fingerprint is the SHA-256 of the certificate as colon-separated hex.

func (*CA) GetCert

func (ca *CA) GetCert(host string) (*tls.Certificate, error)

GetCert returns a certificate for host signed by the CA.

func (*CA) GetRootCA

func (ca *CA) GetRootCA() *x509.Certificate

GetRootCA returns the CA certificate.

func (*CA) Name

func (ca *CA) Name() string

Name is the CA's common name, as the OS trust store lists it.

func (*CA) NotAfter

func (ca *CA) NotAfter() time.Time

NotAfter is when the CA expires.

func (*CA) TrustedByOS

func (ca *CA) TrustedByOS() (bool, error)

TrustedByOS reports whether the OS trust store accepts certificates this CA issues. It verifies a fresh leaf against the system roots, which on macOS and Windows asks the platform verifier, so keychain trust settings count. Any verify error means "not trusted": the platform verifiers don't report an untrusted root as one error type.

type Config

type Config struct {
	ListenAddr string
	MaxFlows   int
	// MaxMemoryBytes caps the bodies kept across all flows.
	MaxMemoryBytes int64
	MaxBodyBytes   int64
	// IgnoreHosts are passed through without decrypting. "example.com"
	// also covers its subdomains; "*" patterns use path.Match.
	IgnoreHosts []string
}

Config is how the proxy runs.

type Flow

type Flow struct {
	ID    uint64
	Start time.Time
	End   time.Time
	State State
	Error string

	Method string
	URL    string
	Scheme string
	Host   string // without port
	Port   string
	Path   string // path and query
	Proto  string

	ReqHeader http.Header
	ReqBody   []byte
	// ReqStreamed is set when the body was larger than the capture
	// limit and passed through without being kept.
	ReqStreamed bool

	Status     int
	RespHeader http.Header
	// RespBody is decoded (gzip, br, deflate, zstd removed).
	RespBody     []byte
	RespSize     int64 // bytes on the wire, before decoding
	RespStreamed bool

	Kind Kind
	// Tunnel marks a CONNECT that was passed through without decrypting.
	Tunnel bool

	ClientAddr string
	App        string
}

Flow is one captured request and its response. A published Flow is never modified: the store swaps in a new value instead, so the UI can read a snapshot without locking.

func (*Flow) Duration

func (f *Flow) Duration() time.Duration

Duration is how long the flow took, or has taken so far.

func (*Flow) HTTPS

func (f *Flow) HTTPS() bool

HTTPS reports whether the flow was sent over TLS.

type Kind

type Kind string

Kind groups flows by content for the page's filter chips.

const (
	KindJSON   Kind = "json"
	KindXML    Kind = "xml"
	KindHTML   Kind = "html"
	KindCSS    Kind = "css"
	KindJS     Kind = "js"
	KindImage  Kind = "image"
	KindMedia  Kind = "media"
	KindFont   Kind = "font"
	KindForm   Kind = "form"
	KindText   Kind = "text"
	KindWS     Kind = "ws"
	KindTunnel Kind = "tunnel"
	KindOther  Kind = "other"
)

func Classify

func Classify(ct, urlPath string) Kind

Classify picks a Kind from the response content type, falling back to the request path's extension.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service owns the proxy server, its CA and the captured flows.

func NewService

func NewService(caDir string) *Service

NewService returns a stopped proxy keeping its CA in caDir.

func (*Service) Addr

func (s *Service) Addr() string

Addr is the address the proxy listens on, or "" when stopped.

func (*Service) CA

func (s *Service) CA() (*CA, error)

CA returns the CA, loading it from disk on first use. It does not create one; see EnsureCA.

func (*Service) CADir

func (s *Service) CADir() string

CADir is where the CA files live.

func (*Service) ClientAddrs

func (s *Service) ClientAddrs() []string

ClientAddrs lists the host:port addresses clients can reach the proxy at, or nil when it is stopped. Listening on every interface, that is this machine's network addresses first, then loopback; a wildcard address like [::]:9090 is no use to someone setting up a phone.

func (*Service) DeleteCA

func (s *Service) DeleteCA() error

DeleteCA removes the CA files. The proxy must be stopped.

func (*Service) EnsureCA

func (s *Service) EnsureCA() (*CA, error)

EnsureCA loads the CA, creating it when there is none.

func (*Service) LastError

func (s *Service) LastError() error

LastError is why the proxy last stopped on its own, if it did.

func (*Service) Paused

func (s *Service) Paused() bool

Paused reports whether recording is paused.

func (*Service) RegenerateCA

func (s *Service) RegenerateCA() (*CA, error)

RegenerateCA replaces the CA with a new one. A running proxy signs with the new CA from its next connection on.

func (*Service) Running

func (s *Service) Running() bool

Running reports whether the proxy is listening.

func (*Service) ServeCertSite

func (s *Service) ServeCertSite(w http.ResponseWriter, r *http.Request)

ServeCertSite serves the CA download page: "/" is the page, and "/ca.pem", "/ca.crt" and "/ca.cer" are the certificate.

func (*Service) SetIgnoreHosts

func (s *Service) SetIgnoreHosts(hosts []string)

SetIgnoreHosts changes the passthrough list of a running proxy.

func (*Service) SetPaused

func (s *Service) SetPaused(v bool)

SetPaused stops or resumes recording new flows; traffic keeps flowing through the proxy either way.

func (*Service) SetWake

func (s *Service) SetWake(fn func())

SetWake registers fn to run (from any goroutine) when state changes.

func (*Service) Start

func (s *Service) Start(cfg Config) error

Start begins listening. It creates the CA when there is none.

func (*Service) Stop

func (s *Service) Stop() error

Stop shuts the proxy down and closes open client connections, including tunnels the server no longer tracks.

func (*Service) Store

func (s *Service) Store() *Store

Store holds the captured flows.

type State

type State int

State is where a captured flow is in its lifetime.

const (
	StatePending State = iota
	StateDone
	StateFailed
)

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store keeps captured flows in memory, oldest first, up to a number of flows and a total body size.

func NewStore

func NewStore(max int) *Store

NewStore returns a store keeping at most max flows; max <= 0 uses DefaultMaxFlows.

func (*Store) Add

func (s *Store) Add(f *Flow) uint64

Add stores f, assigning its ID, and returns that ID.

func (*Store) Bytes

func (s *Store) Bytes() int64

Bytes is the size of the bodies held.

func (*Store) Clear

func (s *Store) Clear()

Clear drops every flow.

func (*Store) Get

func (s *Store) Get(id uint64) (*Flow, bool)

Get returns the flow with ID id.

func (*Store) Len

func (s *Store) Len() int

Len is the number of flows held.

func (*Store) Remove

func (s *Store) Remove(ids map[uint64]bool)

Remove drops the flows whose IDs are in ids.

func (*Store) SetLimits

func (s *Store) SetLimits(maxFlows int, maxBytes int64)

SetLimits changes how many flows and how many body bytes the store keeps, dropping the oldest flows if needed. Values <= 0 use the defaults.

func (*Store) SetOnChange

func (s *Store) SetOnChange(fn func())

SetOnChange registers fn to run after each change, from the goroutine that made it. It must not block.

func (*Store) Snapshot

func (s *Store) Snapshot() []*Flow

Snapshot returns the flows held, oldest first. The slice is a copy; the flows themselves are shared and must not be modified.

func (*Store) Update

func (s *Store) Update(id uint64, fn func(f *Flow))

Update replaces the flow with ID id by the result of fn, which gets a copy to change. It does nothing when the flow has been dropped.

func (*Store) Version

func (s *Store) Version() uint64

Version increases on every change; compare it to skip rebuilding views.

type SystemProxy

type SystemProxy struct {
	Enabled bool
	Host    string
	Port    int
}

SystemProxy is the OS-wide HTTPS proxy setting. Chapar only reads it.

func ReadSystemProxy

func ReadSystemProxy() (SystemProxy, error)

ReadSystemProxy returns the OS-wide HTTPS proxy setting.

func (SystemProxy) PointsTo

func (sp SystemProxy) PointsTo(port int) bool

PointsTo reports whether the setting sends traffic to a proxy on this machine at port.

type TrustStep

type TrustStep struct {
	Text    string
	Command string // optional, ready to paste in a terminal
}

TrustStep is one manual step to trust the CA.

func TrustSteps

func TrustSteps(ca *CA) []TrustStep

TrustSteps lists how to trust the CA by hand on this OS.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL