SSRF Protection in Elixir 🛡️
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 allow or block list before making an HTTP request.
See the Documentation on HexDocs.
To get started, add safeurl
to your project dependencies in mix.exs
. Optionally, you may
also add HTTPoison
to your dependencies for making requests directly
through SafeURL:
def deps do
[
{:safeurl, "~> 0.3"},
{:httpoison, "~> 1.8"}, # Optional
]
end
To use SafeURL with your favorite HTTP Client, see the HTTP Clients section.
SafeURL
blocks private/reserved IP addresses are by default, and users can add additional
CIDR ranges to the blocklist, or alternatively allow specific CIDR ranges to which the
application is allowed to make requests.
You can use allowed?/2
or validate/2
to check if a URL is safe to call. If you have the
HTTPoison
application available, you can also call get/4
which will
validate the host automatically before making a web request, and return an error otherwise.
iex> SafeURL.allowed?("https://includesecurity.com")
true
iex> SafeURL.validate("https://google.com/", schemes: ~w[https])
{:error, :restricted}
iex> SafeURL.validate("https://230.10.10.10/")
{:error, :restricted}
iex> SafeURL.validate("https://230.10.10.10/", block_reserved: false)
:ok
# When HTTPoison is available:
iex> SafeURL.get("https://10.0.0.1/ssrf.txt")
{:error, :restricted}
iex> SafeURL.get("https://google.com/")
{:ok, %HTTPoison.Response{...}}
SafeURL
can be configured to customize and override validation behaviour by passing the
following options:
-
:block_reserved
- Block reserved/private IP ranges. Defaults totrue
. -
:blocklist
- List of CIDR ranges to block. This is additive with:block_reserved
. Defaults to[]
. -
:allowlist
- List of CIDR ranges to allow. If specified, blocklist will be ignored. Defaults to[]
. -
:schemes
- List of allowed URL schemes. Defaults to["http, "https"]
. -
:dns_module
- Any module that implements theSafeURL.DNSResolver
behaviour. Defaults toDNS
from the:dns
package.
These options can be passed to the function directly or set globally in your config.exs
file:
config :safeurl,
block_reserved: true,
blocklist: ~w[100.0.0.0/16],
schemes: ~w[https],
dns_module: MyCustomDNSResolver
Find detailed documentation on HexDocs.
While SafeURL already provides a convenient get/4
method to validate hosts
before making GET HTTP requests, you can also write your own wrappers, helpers or
middleware to work with the HTTP Client of your choice.
For HTTPoison, you can create a wrapper module that validates hosts before making HTTP requests:
defmodule CustomClient do
def request(method, url, body, headers \\ [], opts \\ []) do
{safeurl_opts, opts} = Keyword.pop(opts, :safeurl, [])
with :ok <- SafeURL.validate(url, safeurl_opts) do
HTTPoison.request(method, url, body, headers, opts)
end
end
def get(url, headers \\ [], opts \\ []), do: request(:get, url, "", headers, opts)
def post(url, body, headers \\ [], opts \\ []), do: request(:post, url, body, headers, opts)
# ...
end
And you can use it as:
iex> CustomClient.get("https://230.10.10.10/data.json", [], safeurl: [block_reserved: false], recv_timeout: 500)
{:ok, %HTTPoison.Response{...}}
For Tesla, you can write a custom middleware to halt requests that are not allowed:
defmodule MyApp.Middleware.SafeURL do
@behaviour Tesla.Middleware
@impl true
def call(env, next, opts) do
with :ok <- SafeURL.validate(env.url, opts), do: Tesla.run(next)
end
end
And you can plug it in anywhere you're using Tesla:
defmodule DocumentService do
use Tesla
plug Tesla.Middleware.BaseUrl, "https://document-service/"
plug Tesla.Middleware.JSON
plug MyApp.Middleware.SafeURL, schemes: ~w[https], allowlist: ["10.0.0.0/24"]
def fetch(id) do
get("/documents/#{id}")
end
end
In some cases you might want to use a custom strategy for DNS resolution. You can do so by
passing your own implementation of SafeURL.DNSResolver
in the global or local
config.
Example use-cases of this are:
- Using a specific DNS server
- Avoiding network access in specific environments
- Mocking DNS resolution in tests
You can do so by implementing DNSResolver
:
defmodule TestDNSResolver do
@behaviour SafeURL.DNSResolver
@impl true
def resolve("google.com"), do: {:ok, [{192, 168, 1, 10}]}
def resolve("github.com"), do: {:ok, [{192, 168, 1, 20}]}
def resolve(_domain), do: {:ok, [{192, 168, 1, 99}]}
end
config :safeurl, dns_module: TestDNSResolver
For more examples, see SafeURL.DNSResolver
docs.
- Fork, Enhance, Send PR
- Lock issues with any bugs or feature requests
- Implement something from Roadmap
- Spread the word ❤️
SafeURL is officially maintained by the team at Slab. It was originally created by Nick Fox at Include Security.