safeurl

README

safeurl

A Go library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks. It implements a safeurl.Client wrapper around Go's native net/http.Client and performs validation on the incoming request against the configured allow and block lists. It also implements mitigation for DNS rebinding attacks.

Configuration options

The safeurl.Client can be configured through the safeurl.Config struct. It enables configuration of the following options:

AllowedPorts                    - list of ports the application is allowed to connect to
AllowedSchemes                  - list of schemas the application can use
AllowedHosts                    - list of hosts the application is allowed to communicate with
BlockedIPs                      - list of IP addresses the application is not allowed to connect to
AllowedIPs                      - list of IP addresses the application is allowed to connect to
AllowedCIDR                     - list of CIDR ranges the application is allowed to connect to
BlockedCIDR                     - list of CIDR ranges the application is not allowed to connect to

IsIPv6Enabled                   - specifies wether communication through IPv6 is enabled
AllowSendingCredentials         - specifies wether HTTP credentials should be sent

IsDebugLoggingEnabled          - enables debug logs

How to use the safeurl.Client?

First, you need to include the safeurl module. To do that, simply add github.com/doyensec/safeurl to your project's go.mod file.

Sample:

import (
    "fmt"
    "github.com/doyensec/safeurl"
)

func main() {
    config := safeurl.GetConfigBuilder().
        SetAllowedHosts("example.com").
        Build()

    client := safeurl.Client(config)

    resp, err := client.Get("https://example.com")
    if err != nil {
        fmt.Errorf("request return error: %v", err)
    }

    // read response body
}

Running tests

To successfully run all the unit tests, you will need to run a local DNS and HTTP server. That can be done by executing the following command:

go run testing/servers.go

Once the servers are up and running, the unit test can be ran with:

go test -v

Credits

This tool has been created by Viktor Chuchurski and Alessandro Cotto of Doyensec LLC during our 25% research time.

Documentation

Index

• func GetConfigBuilder() *configBuilder
• func GetIPsInCIRDRange(cidr string) []string
• type AllowedHostError
  • func (e *AllowedHostError) Error() string
• type AllowedIPError
  • func (e *AllowedIPError) Error() string
• type AllowedPortError
  • func (e *AllowedPortError) Error() string
• type AllowedSchemeError
  • func (e *AllowedSchemeError) Error() string
• type Config
• type IPv6BlockedError
  • func (e *IPv6BlockedError) Error() string
• type InvalidHostError
  • func (e *InvalidHostError) Error() string
• type SendingCredentialsBlockedError
  • func (e *SendingCredentialsBlockedError) Error() string
• type WrappedClient
  • func Client(config *Config) *WrappedClient
  • func (wc *WrappedClient) CloseIdleConnections()
  • func (wc *WrappedClient) Do(req *http.Request) (resp *http.Response, err error)
  • func (wc *WrappedClient) Get(url string) (resp *http.Response, err error)
  • func (wc *WrappedClient) Head(url string) (resp *http.Response, err error)
  • func (wc *WrappedClient) Post(url string, contentType string, body io.Reader) (resp *http.Response, err error)
  • func (wc *WrappedClient) PostForm(url string, data urllib.Values) (resp *http.Response, err error)

Functions

func GetConfigBuilder

func GetConfigBuilder() *configBuilder

func GetIPsInCIRDRange

func GetIPsInCIRDRange(cidr string) []string

Types

type AllowedHostError

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

func (*AllowedHostError) Error

func (e *AllowedHostError) Error() string

type AllowedIPError

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

func (*AllowedIPError) Error

func (e *AllowedIPError) Error() string

type AllowedPortError

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

func (*AllowedPortError) Error

func (e *AllowedPortError) Error() string

type AllowedSchemeError

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

func (*AllowedSchemeError) Error

func (e *AllowedSchemeError) Error() string

type Config

type Config struct {
	Timeout       time.Duration
	CheckRedirect func(req *http.Request, via []*http.Request) error
	Jar           http.CookieJar

	AllowedPorts []int

	AllowedSchemes []string

	AllowedHosts []string

	BlockedIPs []net.IP
	AllowedIPs []net.IP

	BlockedIPsCIDR []net.IPNet
	AllowedIPsCIDR []net.IPNet

	AllowSendingCredentials bool

	IsIPv6Enabled bool

	IsDebugLoggingEnabled bool
	InTestMode            bool

	TlsConfig *tls.Config
}

type IPv6BlockedError

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

func (*IPv6BlockedError) Error

func (e *IPv6BlockedError) Error() string

type InvalidHostError

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

func (*InvalidHostError) Error

func (e *InvalidHostError) Error() string

type SendingCredentialsBlockedError

type SendingCredentialsBlockedError struct {
}

func (*SendingCredentialsBlockedError) Error

func (e *SendingCredentialsBlockedError) Error() string

type WrappedClient

type WrappedClient struct {
	Client *http.Client
	// contains filtered or unexported fields
}

func Client

func Client(config *Config) *WrappedClient

func (*WrappedClient) CloseIdleConnections

func (wc *WrappedClient) CloseIdleConnections()

func (*WrappedClient) Do

func (wc *WrappedClient) Do(req *http.Request) (resp *http.Response, err error)

func (*WrappedClient) Get

func (wc *WrappedClient) Get(url string) (resp *http.Response, err error)

func (*WrappedClient) Head

func (wc *WrappedClient) Head(url string) (resp *http.Response, err error)

func (*WrappedClient) Post

func (wc *WrappedClient) Post(url string, contentType string, body io.Reader) (resp *http.Response, err error)

func (*WrappedClient) PostForm

func (wc *WrappedClient) PostForm(url string, data urllib.Values) (resp *http.Response, err error)