proxy

package module
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2025 License: MIT Imports: 32 Imported by: 0

README

Proxy Go Package

proxy is a Go package designed to create a man-in-the-middle (MITM) proxy tool for intercepting, modifying, and forwarding traffic over multiple protocols including HTTP, HTTPS, TLS, WebSocket, and TCP. This package is ideal for security testing, traffic analysis, and protocol research.

Features

This package supports the following features:

  • HTTP/HTTPS MITM: Intercepts and modifies HTTP and HTTPS requests/responses, supporting TLS decryption and encryption.
  • TLS MITM: Handles TLS handshake, decrypts and re-encrypts traffic for protocol analysis and tampering.
  • WebSocket MITM: Supports WebSocket connections, intercepting and modifying WebSocket protocol upgrade requests and data transmission.
  • TCP MITM: Intercepts and modifies raw TCP traffic, useful for any TCP-based protocol.
  • Protocol Support: MITM attacks for HTTP/HTTPS, WebSocket, TLS, and TCP protocols.

Installation

Make sure your Go environment is correctly set up, then install the package via the following command:

go get github.com/vpxuser/proxy

Usage

Here’s a simple example of how to use the package:

Start HTTP/HTTPS MITM Proxy
package main

import "github.com/vpxuser/proxy"

func main() {
	httpProxy := proxy.NewHttpProxy()
	httpProxy.Port = "8080"
	httpProxy.Serve(&proxy.Manual{})
}
Configure TLS Handshake and Certificates

proxy supports using custom certificates for TLS MITM. You can provide your own CA certificate and private key:

cert, err := os.ReadFile("config/ca.crt")
if err != nil {
    panic(err)
}

block, _ := pem.Decode(cert)

certificate, err := x509.ParseCertificate(block.Bytes)
if err != nil {
    panic(err)
}

httpProxy.Cert = certificate

key, err := os.ReadFile("config/ca.key")
if err != nil {
    panic(err)
}

block, _ := pem.Decode(key)

privateKey, err := x509.ParsePKCS1PrivateKey(block.Bytes)
if err != nil {
    panic(err)
}

httpProxy.Key = privateKey
HTTP MITM Proxy

You can modify HTTP Request and Response

httpProxy.OnRequest().Do(func(req *http.Request, ctx *proxy.Context) (*http.Request, *http.Response) {
    reqRaw, err := httputil.DumpRequest(req, true)
    if err != nil {
        log.Error(err)
    return req, nil
    }
    log.Debugf("HTTP Request : \n%s", reqRaw)
    return req, nil
})

httpProxy.OnResponse().Do(func(resp *http.Response, ctx *proxy.Context) *http.Response {
    respRaw, err := httputil.DumpResponse(resp, true)
    if err != nil {
        log.Error(err)
    return resp
    }
    log.Debugf("HTTP Response : \n%s", respRaw)
    return resp
})
WebSocket MITM Proxy

The package also supports WebSocket protocol MITM. You can easily intercept and modify WebSocket messages.

httpProxy.OnWebSocket().Do(func(frame ws.Frame, reverse bool, ctx *proxy.Context) ws.Frame {
    log.Debugf("WebSocket Frame Payload : %s", frame.Payload)
    return frame
})
TCP MITM Proxy

For TCP traffic, the proxy package allows you to intercept and modify any TCP-based protocol traffic.

httpProxy.OnRaw().Do(func(raw []byte, reverse bool, ctx *proxy.Context) []byte {
    log.Debugf("TCP Raw : %s", raw)
    return raw
})

Configuration Options

  • Listen Address and Port: Use proxy.HttpProxy.Port to configure the address and port to listen on.
  • Certificates and Keys: Use proxy.HttpProxy.Cert and proxy.HttpProxy.Key to configure the certificates and private key for TLS MITM.
  • Logging: The package logs events to the console by default, but custom logging can be configured.

Man-in-the-Middle Attack Workflow

This tool works by acting as a middleman between the client and the target server. It intercepts, parses, and modifies the traffic. For HTTPS and TLS traffic, it uses a self-signed certificate to generate encrypted connections and decrypts/encrypts traffic using symmetric keys. For TCP and WebSocket protocols, it directly forwards data while optionally modifying it.

Notes

  1. For Legal Security Testing Only: Please use this tool only for authorized security testing. Never use it for malicious purposes.
  2. MITM Limitations: Some websites or services may use certificate pinning, HSTS, and other mechanisms to prevent MITM attacks.
  3. Performance: The proxy may introduce some latency due to the processing of traffic. The performance depends on the amount of traffic and the complexity of processing logic.

Example Projects

If you want to see real-world examples of how to use this package, check out the following projects:

Contributing

We welcome contributions via issues and pull requests! Any contributions to improve this tool are highly appreciated.

License

This project is licensed under the MIT License. See the LICENSE file for details.

You can adjust the package details and examples as needed. If you need more specific changes or further information, feel free to ask!

Documentation

Index

Constants

View Source 
const CertificatePEM = `` /* 1536-byte string literal not displayed */
View Source 
const PrivateKeyPEM = `` /* 1674-byte string literal not displayed */

Variables

View Source 
var Certificate *x509.Certificate
View Source 
var PrivateKey *rsa.PrivateKey

Functions

func Debug 

func Debug(args ...any)

func Debugf 

func Debugf(format string, args ...any)

func Error 

func Error(args ...any)

func Errorf 

func Errorf(format string, args ...any)

func Fatal 

func Fatal(args ...any)

func Fatalf 

func Fatalf(format string, args ...any)

func Info 

func Info(args ...any)

func Infof 

func Infof(format string, args ...any)

func IsDomain 

func IsDomain(hostname string) bool

func ListenAndServe 

func ListenAndServe(network, addr string, cfg *Config) error

func Panic 

func Panic(args ...any)

func Panicf 

func Panicf(format string, args ...any)

func Serve 

func Serve(inner net.Listener, cfg *Config) error

func SetLogLevel 

func SetLogLevel(level Level)

func Trace 

func Trace(args ...any)

func Tracef 

func Tracef(format string, args ...any)

func Warn 

func Warn(args ...any)

func Warnf 

func Warnf(format string, args ...any)

Types

type Config 

type Config struct {
	DefaultSAN string
	// contains filtered or unexported fields
}

func NewConfig 

func NewConfig() *Config

func (*Config) WithOptions 

func (c *Config) WithOptions(opts ...ConfigOption) *Config

func (*Config) WithRawMatcher 

func (c *Config) WithRawMatcher(matcher ...RawMatcher) *RawFilter

func (*Config) WithReqMatcher 

func (c *Config) WithReqMatcher(matcher ...ReqMatcher) *ReqFilter

func (*Config) WithRespMatcher 

func (c *Config) WithRespMatcher(matcher ...RespMatcher) *RespFilter

func (*Config) WithWsMatcher 

func (c *Config) WithWsMatcher(matcher ...WsMatcher) *WsFilter

type ConfigOption 

type ConfigOption func(*Config)

func WithDialer 

func WithDialer(dialer Dialer) ConfigOption

func WithDispatcher 

func WithDispatcher(dispatcher Dispatcher) ConfigOption

func WithHttpHandler 

func WithHttpHandler(httpHandler HttpHandler) ConfigOption

func WithLimiter 

func WithLimiter(limiter Limiter) ConfigOption

func WithNegotiator 

func WithNegotiator(negotiator Negotiator) ConfigOption

func WithTLSConfigFn 

func WithTLSConfigFn(tlsConfig TLSConfig) ConfigOption

func WithTcpHandler 

func WithTcpHandler(tcpHandler TcpHandler) ConfigOption

func WithWsHandler 

func WithWsHandler(wsHandler WsHandler) ConfigOption

type Conn 

type Conn struct {
	net.Conn
	// contains filtered or unexported fields
}

func NewConn 

func NewConn(inner net.Conn) *Conn

func (*Conn) Peek 

func (c *Conn) Peek(n int) ([]byte, error)

func (*Conn) Read 

func (c *Conn) Read(p []byte) (int, error)

type Context 

type Context struct {
	Id   string
	Conn *Conn
	*Config
	DstHost string
	DstPort string
	Req     *http.Request
	// contains filtered or unexported fields
}

func NewContext 

func NewContext() *Context

func (*Context) Debug 

func (c *Context) Debug(args ...any)

func (*Context) Debugf 

func (c *Context) Debugf(format string, args ...any)

func (*Context) Error 

func (c *Context) Error(args ...any)

func (*Context) Errorf 

func (c *Context) Errorf(format string, args ...any)

func (*Context) Fatal 

func (c *Context) Fatal(args ...any)

func (*Context) Fatalf 

func (c *Context) Fatalf(format string, args ...any)

func (*Context) Info 

func (c *Context) Info(args ...any)

func (*Context) Infof 

func (c *Context) Infof(format string, args ...any)

func (*Context) Panic 

func (c *Context) Panic(args ...any)

func (*Context) Panicf 

func (c *Context) Panicf(format string, args ...any)

func (*Context) SetLogLevel 

func (c *Context) SetLogLevel(level Level)

func (*Context) SetLogger 

func (c *Context) SetLogger(logger Logger)

func (*Context) Trace 

func (c *Context) Trace(args ...any)

func (*Context) Tracef 

func (c *Context) Tracef(format string, args ...any)

func (*Context) Warn 

func (c *Context) Warn(args ...any)

func (*Context) Warnf 

func (c *Context) Warnf(format string, args ...any)

type Dialer 

type Dialer interface {
	Dial(string, string, ...DialerOption) (net.Conn, error)
	WithOptions(...DialerOption) Dialer
}

func FromURL 

func FromURL(proxyURL string, dialer proxy.Dialer) (Dialer, error)

type DialerOption 

type DialerOption func(*dialerConfig)

func WithTLSConfig 

func WithTLSConfig(cfg *tls.Config) DialerOption

type DispatchFn 

type DispatchFn func(*Context)

func (DispatchFn) Dispatch 

func (f DispatchFn) Dispatch(ctx *Context)

type Dispatcher 

type Dispatcher interface {
	Dispatch(*Context)
}

type HandleHttpFn 

type HandleHttpFn func(*Context)

func (HandleHttpFn) HandleHttp 

func (f HandleHttpFn) HandleHttp(ctx *Context)

type HandleTcpFn 

type HandleTcpFn func(*Context)

func (HandleTcpFn) HandleTcp 

func (f HandleTcpFn) HandleTcp(ctx *Context)

type HandleWsFn 

type HandleWsFn func(*Context)

func (HandleWsFn) HandleWs 

func (f HandleWsFn) HandleWs(ctx *Context)

type HandshakeFn 

type HandshakeFn func(*Context) error
var Socks5Handler HandshakeFn = func(ctx *Context) error { return socks5Handshake(ctx) }

func (HandshakeFn) Handshake 

func (f HandshakeFn) Handshake(ctx *Context) error

type HttpHandler 

type HttpHandler interface {
	HandleHttp(*Context)
}

type Level 

type Level logrus.Level
const (
	PanicLevel Level = iota
	FatalLevel
	ErrorLevel
	WarnLevel
	InfoLevel
	DebugLevel
	TraceLevel
)

type Limiter 

type Limiter interface {
	Acquire()
	Release()
	InUse() int
	Capacity() int
	Available() int
}

type Listener 

type Listener struct {
	net.Listener
	// contains filtered or unexported fields
}

func Listen 

func Listen(network, addr string, cfg *Config) (*Listener, error)

func NewListener 

func NewListener(inner net.Listener, cfg *Config) *Listener

func (*Listener) Accept 

func (l *Listener) Accept() (net.Conn, error)

func (*Listener) Serve 

func (l *Listener) Serve() error

type Logger 

type Logger interface {
	Log(*Context, Level, ...any)
	Logf(*Context, Level, string, ...any)
	SetLevel(Level)
}

type Logrus 

type Logrus struct {
	*logrus.Logger
}

func (*Logrus) Log 

func (l *Logrus) Log(ctx *Context, level Level, args ...any)

func (*Logrus) Logf 

func (l *Logrus) Logf(ctx *Context, level Level, format string, args ...any)

func (*Logrus) SetLevel 

func (l *Logrus) SetLevel(level Level)

type Negotiator 

type Negotiator interface {
	Handshake(*Context) error
}

type RawFilter 

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

func (*RawFilter) Do 

func (r *RawFilter) Do(handle RawHandlerFn)

type RawHandlerFn 

type RawHandlerFn func([]byte, *Context) []byte

type RawMatchFn 

type RawMatchFn func([]byte, *Context) bool

func RawHostIs 

func RawHostIs(hosts ...string) RawMatchFn

func (RawMatchFn) Match 

func (f RawMatchFn) Match(raw []byte, ctx *Context) bool

type RawMatcher 

type RawMatcher interface {
	Match(raw []byte, ctx *Context) bool
}

type ReqFilter 

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

func (*ReqFilter) Handle 

func (r *ReqFilter) Handle(handle ReqHandlerFn)

type ReqHandlerFn 

type ReqHandlerFn func(*http.Request, *Context) (*http.Request, *http.Response)

type ReqMatchFn 

type ReqMatchFn func(*http.Request, *Context) bool

func Not 

func Not(matcher ReqMatcher) ReqMatchFn

func ReqHostIs 

func ReqHostIs(hosts ...string) ReqMatchFn

func (ReqMatchFn) MatchReq 

func (f ReqMatchFn) MatchReq(req *http.Request, ctx *Context) bool

func (ReqMatchFn) MatchResp 

func (f ReqMatchFn) MatchResp(resp *http.Response, ctx *Context) bool

type ReqMatcher 

type ReqMatcher interface {
	MatchReq(*http.Request, *Context) bool
	RespMatcher
}

type Resolver 

type Resolver struct {
	ReverseLookup *sync.Map
}

func NewResolver 

func NewResolver() *Resolver

type RespFilter 

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

func (*RespFilter) Handle 

func (r *RespFilter) Handle(handle RespHandlerFn)

type RespHandlerFn 

type RespHandlerFn func(*http.Response, *Context) *http.Response

type RespMatchFn 

type RespMatchFn func(*http.Response, *Context) bool

func StatusCodeIs 

func StatusCodeIs(codes ...int) RespMatchFn

func (RespMatchFn) MatchResp 

func (f RespMatchFn) MatchResp(resp *http.Response, ctx *Context) bool

type RespMatcher 

type RespMatcher interface {
	MatchResp(*http.Response, *Context) bool
}

type TLSConfig 

type TLSConfig interface {
	From(string) (*tls.Config, error)
}

type TLSConfigFn 

type TLSConfigFn func(string) (*tls.Config, error)

func From 

func From(cert *x509.Certificate, privateKey crypto.PrivateKey) TLSConfigFn

func FromCA 

func FromCA(cert *x509.Certificate, privateKey *rsa.PrivateKey) TLSConfigFn

func FromSelfSigned 

func FromSelfSigned() TLSConfigFn

func (TLSConfigFn) From 

func (f TLSConfigFn) From(san string) (*tls.Config, error)

type TcpHandler 

type TcpHandler interface {
	HandleTcp(*Context)
}

type TokenBucket 

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

func NewTokenBucket 

func NewTokenBucket(max int) *TokenBucket

func (*TokenBucket) Acquire 

func (tb *TokenBucket) Acquire()

func (*TokenBucket) Available 

func (tb *TokenBucket) Available() int

func (*TokenBucket) Capacity 

func (tb *TokenBucket) Capacity() int

func (*TokenBucket) InUse 

func (tb *TokenBucket) InUse() int

func (*TokenBucket) Release 

func (tb *TokenBucket) Release()

type WsFilter 

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

func (*WsFilter) Handle 

func (w *WsFilter) Handle(handle WsHandlerFn)

type WsHandler 

type WsHandler interface {
	HandleWs(*Context)
}

type WsHandlerFn 

type WsHandlerFn func(ws.Frame, *Context) ws.Frame

type WsMatchFn 

type WsMatchFn func(ws.Frame, *Context) bool

func WsHostIs 

func WsHostIs(hosts ...string) WsMatchFn

func (WsMatchFn) Match 

func (f WsMatchFn) Match(frame ws.Frame, ctx *Context) bool

type WsMatcher 

type WsMatcher interface {
	Match(frame ws.Frame, ctx *Context) bool
}

Source Files

View all Source files

Directories

Path Synopsis
examples
printer command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.