# SafeURL
SafeURL is a library that aids developers in protecting against a class of vulnerabilities known as Server Side Request Forgery. It does this by validating a URL against a configurable white or black list before making an HTTP request. SafeURL is open-source and licensed under MIT.

This library was originally created by Nick Fox at [Include Security](, with substantial improvements contributed by the [Slab]( team. As of January 2022, this library is now maintained by Slab.

## Installation
This package is not yet available in hex, so it must be installed from GitHub by adding the following to 

def deps do
    {:safeurl, github: "includesecurity/elixir-safeurl"}

## Usage
SafeURL wraps around [HTTPoison]( and
works by resolving the IP address from a supplied URL and validating it
against a blacklist or whitelist before sending the request. By default, all
internal/reserved CIDR ranges are blacklisted, and developers can add
additional CIDR ranges to these lists with the `:blacklist` parameter, or 
instead use a whitelist approach with `:whitelist`. 

# Only block private IP ranges
iex> SafeURL.get("")
{:ok, %HTTPoison.Response{...}}

# Blacklist in addition to all private ranges
iex> SafeURL.get("", blacklist: [""])
{:ok, %HTTPoison.Response{...}}

# Only allow requests to hosts on
iex> SafeURL.get("", whitelist: [""])
{:error, :restricted}

# Pass some headers and options to HTTPoison
iex> SafeURL.get("", [], [{"User-Agent", "elixir/1.11.3"}], follow_redirect: false)

If you only need to validate a URL and want to make the request yourself, you
can use `SafeURL.validate_url()` instead:

iex> SafeURL.validate_url("https://acme.corp.internal")
{:error, :restricted}