package module
v1.3.0 Latest Latest

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

Go to latest
Published: Jun 13, 2024 License: MIT Imports: 29 Imported by: 0



SOCKS5/4/4a validating proxy pool + SOCKS5 server

Animated Screenshot of Prox5 Example

GoDoc Go Report Card IRC Test Status five


Prox5 is a golang library for managing, validating, and utilizing a very large amount of arbitrary SOCKS proxies.

Notably it features interface compatible dialer functions that dial out from different proxies for every connection, and a SOCKS5 server that utilizes those functions.


Using prox5 to proxy connections from certain offsec tools may cause denial of service. Please spazz out responsibly.


Table of Contents

  1. Overview
    1. Validation Engine
    2. Auto Scaler
    3. Rate Limiting
    4. Accessing Validated Proxies
  2. Additional info
    1. The Secret Sauce
    2. External Integrations
  3. Status and Final Thoughts


Validation Engine

  1. TCP Dial to the endpoint, if successful, reuse net.Conn down for step 2
  2. HTTPS GET request to a list of IP echo endpoints
  3. Store the IP address discovered during step 2
  4. Allocate a new prox5.Proxy type || update an existing one, store latest info
  5. Enqueue a pointer to this proxy.Proxy instance, instantiating it for further use

Auto Scaler

The validation has an optional auto scale feature that allows for the automatic tuning of validation worker count as more proxies are dispensed. This feature is still new, but seems to work well. It can be enabled with [...].EnableAutoScaler().

Please refer to the autoscale related items within the documentation for more info.

Rate Limiting

Using Rate5, prox5 naturally reduces the frequency of proxies that fail to validate. It does this by reducing the frequency proxies are accepted into the validation pipeline the more they fail to verify or fail to successfully connect to an endpoint. This is not yet adjustable, but will be soon. See the documentation for Rate5, and the source code for this project (defs.go is a good place to start) for more info.

Accessing Validated Proxies

  • Retrieve validated 4/4a/5 proxies as simple strings for generic use
  • Use one of the dialer functions with any golang code that calls for a net.Dialer
  • Spin up a SOCKS5 server that will then make rotating use of your validated proxies

Additional info

The Secret Sauce

What makes Prox5 special is largely the Mystery Dialer. This dialer satisfies the net.Dialer and ContextDialer interfaces. The implementation is a little bit different from your average dialer. Here's roughly what happens when you dial out with a ProxyEngine;

  • Loads up a previously verified proxy
  • Attempts to make connection with the dial endpoint using said proxy
  • Upon failure, prox5:
    • repeats this process mid-dial
    • does not drop connection to the client
  • Once a proxy has been successfully used to connect to the target endpoint, prox5 passes the same net.Conn onto the client

External Integrations


Take a look at mullsox for an easy way to access all of the mullvad proxies reachable from any one VPN endpoint. It is trivial to feed the results of GetAndVerifySOCKS into prox5.

Here's a snippet that should just about get you there:

package main

import (


func main() {
	p5 := prox5.NewProxyEngine()
	mc := mullsox.NewChecker()

	if err := mc.Update(); err != nil {

	incoming, _ := mc.GetAndVerifySOCKS()

	var count = 0
	for line := range incoming {
		if p5.LoadSingleProxy(line.String()) {

	if count == 0 {
		println("failed to load any proxies")

	if err := p5.Start(); err != nil {
	go func() {
		if err := p5.StartSOCKS5Server("", "", ""); err != nil {
	time.Sleep(time.Millisecond * 500)
	println("proxies loaded and socks server started")

Take a look at ProxyGonanza

(TODO: code example here)

Status and Final Thoughts

This project is in development.

It "works" and has been used in "production", but still needs some love.

Please break it and let me know what broke.

The way you choose to use this lib is yours. The API is fairly extensive for you to be able to customize runtime configuration without having to do any surgery.

Things like the amount of validation workers that are concurrently operating, timeouts, and proxy re-use policies may be tuned in real-time.

Please see the docs and the example for more details.




This section is empty.


View Source
var ErrNoProxies = fmt.Errorf("no proxies available")


This section is empty.


type Proxy

type Proxy struct {
	// Endpoint is the address:port of the proxy that we connect to
	Endpoint string
	// ProxiedIP is the address that we end up having when making proxied requests through this proxy
	// TODO: parse this and store as flat int type
	ProxiedIP string
	// contains filtered or unexported fields

Proxy represents an individual proxy

func (*Proxy) GetProto

func (sock *Proxy) GetProto() ProxyProtocol

GetProto retrieves the known protocol value of the Proxy.

func (*Proxy) String added in v0.6.0

func (sock *Proxy) String() string

GetProto safely retrieves the protocol value of the Proxy.

func (*Proxy) UniqueKey

func (sock *Proxy) UniqueKey() string

UniqueKey is an implementation of the Identity interface from Rate5. See:

type ProxyChannels added in v0.7.0

type ProxyChannels struct {
	// SOCKS5 is a constant stream of verified SOCKS5 proxies
	SOCKS5 proxyList
	// SOCKS4 is a constant stream of verified SOCKS4 proxies
	SOCKS4 proxyList
	// SOCKS4a is a constant stream of verified SOCKS5 proxies
	SOCKS4a proxyList
	// HTTP is a constant stream of verified SOCKS5 proxies
	HTTP proxyList

ProxyChannels will likely be unexported in the future.

func (ProxyChannels) Slice added in v0.9.0

func (pc ProxyChannels) Slice() []*proxyList

Slice returns a slice of all proxyLists in ProxyChannels, note that HTTP is not included.

type ProxyEngine added in v0.7.8

type ProxyEngine struct {
	Valids      ProxyChannels
	DebugLogger logger.Logger

	Status uint32

	// Pending is a constant stream of proxy strings to be verified
	Pending proxyList
	// contains filtered or unexported fields

ProxyEngine represents a proxy pool

func NewProxyEngine added in v0.7.0

func NewProxyEngine() *ProxyEngine

NewProxyEngine returns a ProxyEngine with default options. After calling this you may use the various "setters" to change the options before calling ProxyEngine.Start().

func (*ProxyEngine) AddCheckEndpoints added in v0.7.8

func (p5 *ProxyEngine) AddCheckEndpoints(endpoints []string)

AddCheckEndpoints appends entries to the running list of whatismyip style endpoitns for validation. (must return only the WAN IP)

func (*ProxyEngine) AddUserAgents added in v0.7.8

func (p5 *ProxyEngine) AddUserAgents(uagents []string)

AddUserAgents appends to the list of useragents we randomly choose from during proxied requests

func (*ProxyEngine) ClearSOCKSList added in v0.7.8

func (p5 *ProxyEngine) ClearSOCKSList()

ClearSOCKSList clears the map of proxies that we have on record. Other operations (proxies that are still in buffered channels) will continue.

func (*ProxyEngine) Close added in v0.9.6

func (p5 *ProxyEngine) Close() error

func (*ProxyEngine) CloseAllConns added in v0.9.0

func (p5 *ProxyEngine) CloseAllConns()

CloseAllConns will (maybe) close all connections in progress by the dialers (including the SOCKS server if in use). Note this does not effect the proxy pool, it will continue to operate as normal. this is hacky FIXME

func (*ProxyEngine) DebugChannel deprecated added in v0.7.8

func (p5 *ProxyEngine) DebugChannel() chan string

DebugChannel will return a channel which will receive debug messages once debug is enabled. This will alter the flow of debug messages, they will no longer print to console, they will be pushed into this channel. Make sure you pull from the channel eventually to avoid build up of blocked goroutines.

Deprecated: use DebugLogger instead. This will be removed in a future version.

func (*ProxyEngine) DebugEnabled added in v0.7.8

func (p5 *ProxyEngine) DebugEnabled() bool

DebugEnabled returns the current state of our debug switch.

func (*ProxyEngine) Dial added in v0.7.8

func (p5 *ProxyEngine) Dial(network, addr string) (net.Conn, error)

Dial is a simple stub adapter to implement a net.Dialer.

func (*ProxyEngine) DialContext added in v0.7.8

func (p5 *ProxyEngine) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext is a simple stub adapter to implement a net.Dialer.

func (*ProxyEngine) DialTimeout added in v0.7.8

func (p5 *ProxyEngine) DialTimeout(network, addr string, timeout time.Duration) (net.Conn, error)

DialTimeout is a simple stub adapter to implement a net.Dialer with a timeout.

func (*ProxyEngine) DisableAutoScaler added in v0.7.8

func (p5 *ProxyEngine) DisableAutoScaler()

DisableAutoScaler disables the autoscaler.

func (*ProxyEngine) DisableDebug added in v0.7.8

func (p5 *ProxyEngine) DisableDebug()

DisableDebug enables printing of verbose messages during operation. WARNING: if you are using a DebugChannel, you must read all of the messages in the channel's cache or this will block.

func (*ProxyEngine) DisableDebugRedaction added in v0.7.8

func (p5 *ProxyEngine) DisableDebugRedaction()

func (*ProxyEngine) DisableHTTPClientTLSVerification added in v0.9.0

func (p5 *ProxyEngine) DisableHTTPClientTLSVerification()

func (*ProxyEngine) DisableRecyclerShuffling added in v0.9.0

func (p5 *ProxyEngine) DisableRecyclerShuffling()

func (*ProxyEngine) DisableRecycling added in v0.7.8

func (p5 *ProxyEngine) DisableRecycling()

DisableRecycling disables recycling used proxies back into the pending channel for revalidation after dispensed.

func (*ProxyEngine) EnableAutoScaler added in v0.7.8

func (p5 *ProxyEngine) EnableAutoScaler()

EnableAutoScaler enables the autoscaler. This will automatically scale up the number of workers based on the threshold of dial attempts versus validated proxies.

func (*ProxyEngine) EnableDebug added in v0.7.8

func (p5 *ProxyEngine) EnableDebug()

EnableDebug enables printing of verbose messages during operation

func (*ProxyEngine) EnableDebugRedaction added in v0.7.8

func (p5 *ProxyEngine) EnableDebugRedaction()

func (*ProxyEngine) EnableHTTPClientTLSVerification added in v0.9.0

func (p5 *ProxyEngine) EnableHTTPClientTLSVerification()

func (*ProxyEngine) EnableRecyclerShuffling added in v0.9.0

func (p5 *ProxyEngine) EnableRecyclerShuffling()

func (*ProxyEngine) EnableRecycling added in v0.7.8

func (p5 *ProxyEngine) EnableRecycling()

EnableRecycling enables recycling used proxies back into the pending channel for revalidation after dispensed.

func (*ProxyEngine) GetAnySOCKS added in v0.7.8

func (p5 *ProxyEngine) GetAnySOCKS() *Proxy

GetAnySOCKS retrieves any version SOCKS proxy as a Proxy type Will block if one is not available!

func (*ProxyEngine) GetAutoScalerStateString added in v0.7.8

func (p5 *ProxyEngine) GetAutoScalerStateString() string

func (*ProxyEngine) GetAutoScalerStatus added in v0.7.8

func (p5 *ProxyEngine) GetAutoScalerStatus() bool

func (*ProxyEngine) GetDebugRedactStatus added in v0.7.8

func (p5 *ProxyEngine) GetDebugRedactStatus() bool

func (*ProxyEngine) GetDialerBailout added in v0.7.8

func (p5 *ProxyEngine) GetDialerBailout() int

GetDialerBailout retrieves the dialer bailout policy. See SetDialerBailout for more info.

func (*ProxyEngine) GetDispenseMiddleware added in v0.7.8

func (p5 *ProxyEngine) GetDispenseMiddleware() func(*Proxy) (*Proxy, bool)

func (*ProxyEngine) GetHTTPClient added in v0.7.8

func (p5 *ProxyEngine) GetHTTPClient() *http.Client

GetHTTPClient retrieves a pointer to an http.Client powered by mysteryDialer.

func (*ProxyEngine) GetHTTPTLSVerificationStatus added in v0.9.0

func (p5 *ProxyEngine) GetHTTPTLSVerificationStatus() bool

func (*ProxyEngine) GetHTTPTunnel added in v0.7.8

func (p5 *ProxyEngine) GetHTTPTunnel() string

GetHTTPTunnel checks for an available HTTP CONNECT proxy in our pool.

func (*ProxyEngine) GetMaxWorkers added in v0.7.8

func (p5 *ProxyEngine) GetMaxWorkers() int

GetMaxWorkers returns maximum amount of workers that validate proxies concurrently. Note this is read-only during runtime.

func (*ProxyEngine) GetRandomEndpoint added in v0.7.8

func (p5 *ProxyEngine) GetRandomEndpoint() string

GetRandomEndpoint returns a random whatismyip style endpoint from our ProxyEngine's options

func (*ProxyEngine) GetRecyclerShuffleStatus added in v0.9.0

func (p5 *ProxyEngine) GetRecyclerShuffleStatus() bool

func (*ProxyEngine) GetRecyclingStatus added in v0.7.8

func (p5 *ProxyEngine) GetRecyclingStatus() bool

GetRecyclingStatus retrieves the current recycling status, see EnableRecycling.

func (*ProxyEngine) GetRemoveAfter added in v0.7.8

func (p5 *ProxyEngine) GetRemoveAfter() int

GetRemoveAfter retrieves the removeafter policy, the amount of times a recycled proxy is marked as bad until it is removed entirely.

  • returns -1 if recycling is disabled.

func (*ProxyEngine) GetServerTimeout added in v0.7.8

func (p5 *ProxyEngine) GetServerTimeout() time.Duration

GetServerTimeout returns the current value of serverTimeout.

func (*ProxyEngine) GetServerTimeoutStr added in v0.7.8

func (p5 *ProxyEngine) GetServerTimeoutStr() string

GetServerTimeoutStr returns the current value of serverTimeout (in seconds string).

func (*ProxyEngine) GetStaleTime added in v0.7.8

func (p5 *ProxyEngine) GetStaleTime() time.Duration

GetStaleTime returns the duration of time after which a proxy will be considered "stale".

func (*ProxyEngine) GetStatistics added in v0.7.8

func (p5 *ProxyEngine) GetStatistics() Statistics

GetStatistics returns all Statistics atomics.

func (*ProxyEngine) GetTotalBad added in v0.8.0

func (p5 *ProxyEngine) GetTotalBad() int64

func (*ProxyEngine) GetTotalValidated added in v0.7.8

func (p5 *ProxyEngine) GetTotalValidated() int64

GetTotalValidated retrieves our grand total validated proxy count.

func (*ProxyEngine) GetValidationTimeout added in v0.7.8

func (p5 *ProxyEngine) GetValidationTimeout() time.Duration

GetValidationTimeout returns the current value of validationTimeout.

func (*ProxyEngine) GetValidationTimeoutStr added in v0.7.8

func (p5 *ProxyEngine) GetValidationTimeoutStr() string

GetValidationTimeoutStr returns the current value of validationTimeout (in seconds string).

func (*ProxyEngine) GetWorkers added in v0.7.8

func (p5 *ProxyEngine) GetWorkers() (maxWorkers, runningWorkers, idleWorkers int)

GetWorkers retrieves pond worker Statistics:

  • return MaxWorkers, RunningWorkers, IdleWorkers

func (*ProxyEngine) IsRunning added in v0.7.8

func (p5 *ProxyEngine) IsRunning() bool

IsRunning returns true if our background goroutines defined in daemons.go are currently operational

func (*ProxyEngine) LoadMultiLineString added in v0.7.8

func (p5 *ProxyEngine) LoadMultiLineString(socks string) int

LoadMultiLineString loads a multiine string object with proxy per line. Expects one of the following formats for each line:

  • [fe80::2ef0:5dff:fe7f:c299]:1080
  • [fe80::2ef0:5dff:fe7f:c299]:1080:user:pass

func (*ProxyEngine) LoadProxyTXT added in v0.7.8

func (p5 *ProxyEngine) LoadProxyTXT(seedFile string) (count int)

LoadProxyTXT loads proxies from a given seed file and feeds them to the mapBuilder to be later queued automatically for validation. Expects one of the following formats for each line:

  • [fe80::2ef0:5dff:fe7f:c299]:1080
  • [fe80::2ef0:5dff:fe7f:c299]:1080:user:pass

func (*ProxyEngine) LoadSingleProxy added in v0.7.8

func (p5 *ProxyEngine) LoadSingleProxy(sock string) bool

LoadSingleProxy loads a SOCKS proxy into our map. Expects one of the following formats:

  • [fe80::2ef0:5dff:fe7f:c299]:1080
  • [fe80::2ef0:5dff:fe7f:c299]:1080:user:pass

func (*ProxyEngine) Pause added in v0.7.8

func (p5 *ProxyEngine) Pause() error

Pause will cease the creation of any new proxy validation operations.

  • You will be able to start the proxy pool again with ProxyEngine.Resume(), it will have the same Statistics, options, and ratelimits.
  • During pause you are still able to dispense proxies.
  • Options may be changed and proxy lists may be loaded when paused.
  • Pausing an already paused ProxyEngine is a nonop.

func (*ProxyEngine) RandomUserAgent added in v0.7.8

func (p5 *ProxyEngine) RandomUserAgent() string

RandomUserAgent retrieves a random user agent from our list in string form.

func (*ProxyEngine) Resume added in v0.7.8

func (p5 *ProxyEngine) Resume() error

Resume will resume pause proxy pool operations, attempting to resume a running ProxyEngine is returns an error.

func (*ProxyEngine) RoundTrip added in v0.7.8

func (p5 *ProxyEngine) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip is Mr. WorldWide. Obviously. See:

func (*ProxyEngine) SetAndEnableDebugLogger added in v0.9.5

func (p5 *ProxyEngine) SetAndEnableDebugLogger(l logger.Logger)

func (*ProxyEngine) SetAutoScalerMaxScale added in v0.7.94

func (p5 *ProxyEngine) SetAutoScalerMaxScale(max int)

SetAutoScalerMaxScale sets the relative maximum amount that the autoscaler will scale up.

func (*ProxyEngine) SetAutoScalerThreshold added in v0.7.94

func (p5 *ProxyEngine) SetAutoScalerThreshold(threshold int)

SetAutoScalerThreshold sets the threshold of validated proxies versus dials that will trigger the autoscaler.

func (*ProxyEngine) SetCheckEndpoints added in v0.7.8

func (p5 *ProxyEngine) SetCheckEndpoints(newendpoints []string)

SetCheckEndpoints replaces the running list of whatismyip style endpoitns for validation. (must return only the WAN IP)

func (*ProxyEngine) SetDebugLogger deprecated added in v0.7.8

func (p5 *ProxyEngine) SetDebugLogger(l logger.Logger)

SetDebugLogger sets the debug logger for the ProxyEngine. See the Logger interface for implementation details.

Deprecated: use SetLogger instead. This will be removed in a future version.

func (*ProxyEngine) SetDialerBailout added in v0.7.8

func (p5 *ProxyEngine) SetDialerBailout(dialattempts int)

SetDialerBailout sets the amount of times the mysteryDialer will dial out and fail before it bails out.

  • The dialer will attempt to redial a destination with a different proxy a specified amount of times before it gives up

func (*ProxyEngine) SetDispenseMiddleware added in v0.7.8

func (p5 *ProxyEngine) SetDispenseMiddleware(f func(*Proxy) (*Proxy, bool))

SetDispenseMiddleware will add a function that sits within the dialing process of the mysteryDialer and anyhing using it. This means this function will be called mid-dial during connections. Return true to approve proxy, false to skip it. Take care modiying the proxy in-flight as it is a pointer.

func (*ProxyEngine) SetLogger added in v0.9.5

func (p5 *ProxyEngine) SetLogger(l logger.Logger)

SetLogger sets the debug logger for the ProxyEngine. See the Logger interface for implementation details.

func (*ProxyEngine) SetMaxWorkers added in v0.7.8

func (p5 *ProxyEngine) SetMaxWorkers(num int)

SetMaxWorkers set the maximum workers for proxy checking.

func (*ProxyEngine) SetRemoveAfter added in v0.7.8

func (p5 *ProxyEngine) SetRemoveAfter(timesfailed int)

SetRemoveAfter sets the removeafter policy, the amount of times a recycled proxy is marked as bad before it is removed entirely.

  • Default is 10
  • To disable deleting entirely, set this value to -1
  • Only applies when recycling is enabled

func (*ProxyEngine) SetServerTimeout added in v0.7.8

func (p5 *ProxyEngine) SetServerTimeout(timeout time.Duration)

SetServerTimeout sets the serverTimeout option. * serverTimeout defines the timeout for outgoing connections made with the mysteryDialer. * To disable timeout on outgoing mysteryDialer connections, set this to time.Duration(0).

func (*ProxyEngine) SetStaleTime added in v0.7.8

func (p5 *ProxyEngine) SetStaleTime(newtime time.Duration)

SetStaleTime replaces the duration of time after which a proxy will be considered "stale". stale proxies will be skipped upon retrieval.

func (*ProxyEngine) SetUserAgents added in v0.7.8

func (p5 *ProxyEngine) SetUserAgents(uagents []string)

SetUserAgents sets the list of useragents we randomly choose from during proxied requests

func (*ProxyEngine) SetValidationTimeout added in v0.7.8

func (p5 *ProxyEngine) SetValidationTimeout(timeout time.Duration)

SetValidationTimeout sets the validationTimeout option.

func (*ProxyEngine) Socks4Str added in v0.7.8

func (p5 *ProxyEngine) Socks4Str() string

Socks4Str gets a SOCKS4 proxy that we have fully verified. Will block if one is not available!

func (*ProxyEngine) Socks4aStr added in v0.7.8

func (p5 *ProxyEngine) Socks4aStr() string

Socks4aStr gets a SOCKS4 proxy that we have fully verified. Will block if one is not available!

func (*ProxyEngine) Socks5Str added in v0.7.8

func (p5 *ProxyEngine) Socks5Str() string

Socks5Str gets a SOCKS5 proxy that we have fully verified (dialed and then retrieved our IP address from a what-is-my-ip endpoint. Will block if one is not available!

func (*ProxyEngine) Start added in v0.7.8

func (p5 *ProxyEngine) Start() error

Start starts our proxy pool operations. Trying to start a running ProxyEngine will return an error.

func (*ProxyEngine) StartSOCKS5Server added in v0.7.8

func (p5 *ProxyEngine) StartSOCKS5Server(listen, username, password string) error

StartSOCKS5Server starts our rotating proxy SOCKS5 server. listen is standard Go listen string, e.g: "". username and password are used for authenticatig to the SOCKS5 server.

type ProxyProtocol added in v0.7.0

type ProxyProtocol int8
const (
	// ProtoNull is a null value for ProxyProtocol.
	ProtoNull ProxyProtocol = iota

func (ProxyProtocol) String added in v0.7.0

func (p ProxyProtocol) String() string

type SocksLogger added in v0.7.0

type SocksLogger struct {
	// contains filtered or unexported fields

func (SocksLogger) Printf added in v0.7.0

func (s SocksLogger) Printf(format string, a ...interface{})

Printf is used to handle socks server logging.

type Statistics

type Statistics struct {
	// Valid4 is the amount of SOCKS4 proxies validated
	Valid4 *atomic.Int64
	// Valid4a is the amount of SOCKS4a proxies validated
	Valid4a *atomic.Int64
	// Valid5 is the amount of SOCKS5 proxies validated
	Valid5 *atomic.Int64
	// ValidHTTP is the amount of HTTP proxies validated
	ValidHTTP *atomic.Int64
	// Dispensed is a simple ticker to keep track of proxies dispensed via our getters
	Dispensed *atomic.Int64
	// Stale is the amount of proxies that failed our stale policy upon dispensing
	Stale *atomic.Int64
	// Checked is the amount of proxies we've checked.
	Checked *atomic.Int64
	// contains filtered or unexported fields

Statistics is used to encapsulate various proxy engine stats

func (*Statistics) GetUptime

func (stats *Statistics) GetUptime() time.Duration

GetUptime returns the total lifetime duration of our pool.

type Swamp deprecated

type Swamp struct {

Swamp is a deprecated alias for ProxyEngine

Deprecated: use ProxyEngine instead.

func NewDefaultSwamp deprecated

func NewDefaultSwamp() *Swamp

NewDefaultSwamp returns a new ProxyEngine instance.

Deprecated: use NewProxyEngine instead.


Path Synopsis

Jump to

Keyboard shortcuts

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