proxy

Documentation

Overview

Package proxy allows you to retrieve a system configured proxy for a given protocol and target URL.

The priority of retrieval is the following:

Windows:
	Configuration File
	Environment Variable: HTTPS_PROXY, HTTP_PROXY, FTP_PROXY, or ALL_PROXY. `NO_PROXY` is respected.
	Internet Options: Automatically detect settings (WPAD)
	Internet Options: Use automatic configuration script (PAC)
	Internet Options: Manual proxy server
	WINHTTP: (netsh winhttp)

Linux:
	Configuration File
	Environment Variable: HTTPS_PROXY, HTTP_PROXY, FTP_PROXY, or ALL_PROXY. `NO_PROXY` is respected.

MacOS:
	Configuration File
	Environment Variable: HTTPS_PROXY, HTTP_PROXY, FTP_PROXY, or ALL_PROXY. `NO_PROXY` is respected.
	Network Settings: scutil

Example Usage

The following is a complete example using assert in a standard test function:

	package main

	import (
		"github.com/rapid7/go-get-proxied/proxy"
	)

	func main() {
    	p := proxy.NewProvider("").Get("https", "https://rapid7.com")
		if p != nil {
			fmt.Printf("Found proxy: %s\n", p)
		}
   }

Copyright 2018, Rapid7, Inc. License: BSD-3-clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Copyright 2018, Rapid7, Inc. License: BSD-3-clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Copyright 2018, Rapid7, Inc. License: BSD-3-clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Copyright 2018, Rapid7, Inc. License: BSD-3-clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Index

• Variables
• func IsLoopbackHost(host string) bool
• func ParseTargetURL(targetUrl, defaultScheme string) *url.URL
• func ParseURL(rawUrl string, defaultScheme string) (*url.URL, error)
• func RegisterDialerType(scheme string, f func(*url.URL, Dialer) (Dialer, error))
• func SplitHostPort(u *url.URL) (host string, port uint16, err error)
• type Auth
• type Dialer
  • func FromURL(u *url.URL, forward Dialer) (Dialer, error)
• type Provider
  • func NewProvider(configFile string) Provider
• type Proxy
  • func NewProxy(u *url.URL, src string) (Proxy, error)

Variables

var Direct = direct{}

Direct is a direct proxy: one that makes network connections directly.

Functions

func IsLoopbackHost

func IsLoopbackHost(host string) bool

Determines if the given host string (either hostname or IP) references a loop back address. The following are considered loop back addresses:

• 127.0.0.1/8
• [::1]
• localhost

Params:

host: Hostname or IP.

Returns:

Returns true if the host references a loop back address, false otherwise.

noinspection SpellCheckingInspection

func ParseTargetURL

func ParseTargetURL(targetUrl, defaultScheme string) *url.URL

Sanitize the given target URL string to include only the Scheme, Host, and Port. Params:

targetUrl: An optionally valid URL

Returns:

If any of the following exists in the given URL string, it will be omitted from the return value:
	* Username
	* Password
	* Query params
	* Fragment
The given URL string need not be a valid URL

func ParseURL

func ParseURL(rawUrl string, defaultScheme string) (*url.URL, error)

Parse the optionally valid URL string. Should the URL not contain a Scheme, an empty one will be provided. Should all hope be lost after that, expect error to be populated. Params:

rawUrl: An optionally valid URL

Returns:

url.URL: The parsed URL if we managed to construct a valid one.
error: If URL was invalid, even after providing a Scheme.

func RegisterDialerType

func RegisterDialerType(scheme string, f func(*url.URL, Dialer) (Dialer, error))

func SplitHostPort

func SplitHostPort(u *url.URL) (host string, port uint16, err error)

Split the optionally valid URL into a host and port. Should the URL be invalid or have no Host entry, "", 0, err will be returned. Params:

u: An optionally valid URL

Returns:

Returns host, port, err.
	If URL is valid: host, port, nil
	If URL is invalid: "", 0, error

Types

type Auth

type Auth struct {
	User, Password string
}

type Dialer

type Dialer interface {
	// Dial connects to the given address via the proxy.
	Dial(network, addr string) (c net.Conn, err error)
}

Dialer object to use with http client A Dialer is a means to establish a connection.

func FromURL

func FromURL(u *url.URL, forward Dialer) (Dialer, error)

type Provider

type Provider interface {
	/*
		Returns the Proxy configuration for the given traffic protocol and targetUrl.
		If none is found, or an error occurs, nil is returned.
		Params:
			protocol: The protocol of traffic the proxy is to be used for. (i.e. http, https, ftp, socks)
			targetUrl: The URL the proxy is to be used for. (i.e. https://test.endpoint.rapid7.com)
		Returns:
			Proxy: A proxy was found.
			nil: A proxy was not found, or an error occurred.
	*/
	GetProxy(protocol string, targetUrl string) Proxy

	/*
		Returns the Proxy configuration for HTTP traffic and the given targetUrl.
		If none is found, or an error occurs, nil is returned.
		Params:
			targetUrl: The URL the proxy is to be used for. (i.e. http://test.endpoint.rapid7.com)
		Returns:
			Proxy: A proxy was found.
			nil: A proxy was not found, or an error occurred.
	*/
	GetHTTPProxy(targetUrl string) Proxy

	/*
		Returns the Proxy configuration for HTTPS traffic and the given targetUrl.
		If none is found, or an error occurs, nil is returned.
		Params:
			targetUrl: The URL the proxy is to be used for. (i.e. https://test.endpoint.rapid7.com)
		Returns:
			Proxy: A proxy was found.
			nil: A proxy was not found, or an error occurred.
	*/
	GetHTTPSProxy(targetUrl string) Proxy

	/*
		Returns the Proxy configuration for FTP traffic and the given targetUrl.
		If none is found, or an error occurs, nil is returned.
		Params:
			targetUrl: The URL the proxy is to be used for. (i.e. ftp://test.endpoint.rapid7.com)
		Returns:
			Proxy: A proxy was found.
			nil: A proxy was not found, or an error occurred.
	*/
	GetFTPProxy(targetUrl string) Proxy

	/*
		Returns the Proxy configuration for generic TCP/UDP traffic and the given targetUrl.
		If none is found, or an error occurs, nil is returned.
		Params:
			targetUrl: The URL the proxy is to be used for. (i.e. ftp://test.endpoint.rapid7.com)
		Returns:
			Proxy: A proxy was found.
			nil: A proxy was not found, or an error occurred.
	*/
	GetSOCKSProxy(targetUrl string) Proxy
	/*
		Set the timeouts used by this provider making a call which requires external resources (i.e. WPAD/PAC).
		Should any of these timeouts be exceeded, that particular call will be cancelled.
		To this end, this timeout does not represent the complete timeout for any call to this provider,
		but rather are applied to individual implementations uniquely.
		Additionally, this timeout is not guaranteed to be respected by the implementation, and may vary.
		Params:
			resolve: Time in milliseconds to use for name resolution. Provider default is 5000.
			connect: Time in milliseconds to use for server connection requests. Provider default is 5000.
					 TCP/IP can time out while setting up the socket during the
					 three leg SYN/ACK exchange, regardless of the value of this parameter.
			send: Time in milliseconds to use for sending requests. Provider default is 20000.
			receive: Time in milliseconds to receive a response to a request. Provider default is 20000.
	*/
	SetTimeouts(resolve int, connect int, send int, receive int)
}

func NewProvider

func NewProvider(configFile string) Provider

Create a new Provider which is used to retrieve Proxy configurations. Params:

configFile: Optional. Path to a configuration file which specifies proxies.

type Proxy

type Proxy interface {
	// The Proxy's protocol
	Protocol() string
	// The Proxy's host (hostname or IP)
	Host() string
	// The Proxy's port
	Port() uint16
	// username, true: A username was specified
	// username, false: A username was not specified, username should be considered "nil"
	Username() (string, bool)
	// password, true: A password was specified
	// password, false: A password was not specified, password should be considered "nil"
	Password() (string, bool)
	// Human readable location where this Proxy was found
	Src() string
	// A fully qualified URL for this Proxy
	URL() *url.URL
	// A human readable representation of this Proxy. User info (if any) will be obfuscated. Use URL() if you need the URL with user info.
	String() string
	MarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

Represents a Proxy which can be used to proxy communications.

func NewProxy

func NewProxy(u *url.URL, src string) (Proxy, error)