Merge pull request #1 from slab/sn/quality

Improve code quality

Author: Include Security

.gitignore

@@ -0,0 +1,18 @@
+# Created by https://www.toptal.com/developers/gitignore/api/elixir
+# Edit at https://www.toptal.com/developers/gitignore?templates=elixir
+
+### Elixir ###
+/_build
+/cover
+/deps
+/doc
+/.fetch
+erl_crash.dump
+*.ez
+*.beam
+/config/*.secret.exs
+.elixir_ls/
+
+### Elixir Patch ###
+
+# End of https://www.toptal.com/developers/gitignore/api/elixir

lib/safeurl.ex

@@ -1,33 +1,84 @@
 defmodule SafeURL do
   @moduledoc """
-  A library for mitigating Server Side Request Forgery vulnerabilities in Elixir. Private/reserved
-  IP addresses are blacklisted by default, and users can add additional CIDR ranges to blacklist
-  or alternatively whitelist specific CIDR ranges to which the application is allowed to make requests.
-
-  Examples:
-
-    iex(10)> SafeURL.get("https://10.0.0.1/ssrf.txt")
-    {:error, :restricted}
-
-    iex(10)> SafeURL.get("https://google.com/")
-    {:ok,
-    %HTTPoison.Response{
-      body: "{...}",
-      headers: [
-        {"..."}
-      ],
-      request: %HTTPoison.Request{
-        body: "",
-        headers: [],
-        method: :get,
-        options: [],
-        params: %{},
-        url: "https://google.com/"
-      },
-      request_url: "https://google.com/",
-      status_code: 301
-    }}
+  `SafeURL` is library for mitigating Server Side Request
+  Forgery vulnerabilities in Elixir. Private/reserved IP
+  addresses are blacklisted by default, and users can add
+  additional CIDR ranges to blacklist, or alternatively
+  whitelist 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, or just call it directly via `get/4`
+  which will validate it automatically before calling, and
+  return an error if it is not.
+
+
+  ## Examples
+
+      iex> SafeURL.allowed?("https://includesecurity.com")
+      true
+
+      iex> SafeURL.validate("http://google.com/", schemes: ~w[https])
+      {:error, :restricted}
+
+      iex> SafeURL.validate("http://230.10.10.10/")
+      {:error, :restricted}
+
+      iex> SafeURL.validate("http://230.10.10.10/", blacklist_reserved: false)
+      :ok
+
+      iex> SafeURL.get("https://10.0.0.1/ssrf.txt")
+      {:error, :restricted}
+
+      iex> SafeURL.get("https://google.com/")
+      {:ok, %HTTPoison.Response{...}}
+
+
+  ## Options
+
+  `SafeURL` can be configured to customize and override
+  validation behaviour by passing the following options:
+
+    * `:blacklist_reserved` - Blacklist reserved/private IP
+      ranges. Defaults to `true`.
+
+    * `:blacklist` - List of CIDR ranges to blacklist. This is
+      additive with `:blacklist_reserved`. Defaults to `[]`.
+
+    * `:whitelist` - List of CIDR ranges to whitelist. If
+      specified, blacklists will be ignored. Defaults to `[]`.
+
+    * `:schemes` - List of allowed URL schemes. Defaults to
+      `["http, "https"]`.
+
+  If `:blacklist_reserved` is `true` and additional hosts/ranges
+  are supplied with `:blacklist`, both of them are included in
+  the final blacklist to validate the address. If whitelisted
+  ranges are supplied with `:whitelist`, all blacklists are
+  ignored and any hosts not explicitly declared in the whitelist
+  are rejected.
+
+  These options can be set globally in your `config.exs` file:
+
+      config :safeurl,
+        blacklist_reserved: true,
+        blacklist: ~w[100.0.0.0/16],
+        schemes: ~w[https]
+
+  Or they can be passed to the function directly, overriding any
+  global options if set:
+
+      iex> SafeURL.validate("http://10.0.0.1/", blacklist_reserved: false)
+      :ok
+
+      iex> SafeURL.validate("https://app.service/", whitelist: ~w[170.0.0.0/24])
+      :ok
+
+      iex> SafeURL.validate("https://app.service/", blacklist: ~w[170.0.0.0/24])
+      {:error, :restricted}
+
   """
+
   @reserved_ranges [
     "0.0.0.0/8",
     "10.0.0.0/8",
@@ -46,87 +97,188 @@ defmodule SafeURL do
     "240.0.0.0/4"
   ]
 
+
+
+  # Public API
+  # ----------
+
+
   @doc """
-  Validate a URL and execute a GET request using `HTTPoison` with the specified headers and options.
+  Validate a string URL against a blacklist or whitelist.
+
+  This method checks if a URL is safe to be called by looking at
+  its scheme and resolved IP address, and matching it against
+  reserved CIDR ranges, and any provided whitelist/blacklist.
+
+  Returns `true` if the URL meets the requirements,
+  `false` otherwise.
+
+  ## Examples
 
-  Available options and defaults:
-  * `:blacklist_private` - Blacklist private/reserved IP ranges (default: `true`)
-  * `:blacklist` - List of CIDR ranges to blacklist. Additive with `:blacklist_private` (default: `nil`)
-  * `:whitelist` - List of CIDR ranges to whitelist. If specified, blacklists will be ignored (default: `nil`)
-  * `:schemes` - List of valid URL schemes (default: `["http, "https"]`)
+      iex> SafeURL.allowed?("https://includesecurity.com")
+      true
 
-  Options specified in `httpoison_options` will be passed directly to `HTTPoison` when the request is executed.
+      iex> SafeURL.allowed?("http://10.0.0.1/")
+      false
+
+      iex> SafeURL.allowed?("http://10.0.0.1/", whitelist: ~w[10.0.0.0/8])
+      true
+
+  ## Options
 
-  If `:blacklist_private` is `true` and additional hosts/ranges are supplied with `:blacklist`, the
-  lists are additive. If whitelisted ranges are supplied with `:whitelist`, all blacklists are ignored
-  and any hosts not explicitly declared in the whitelist are rejected.
+  See [`Options`](#module-options) section above.
 
-  If the URL is safe, this function returns the `HTTPoison` result directly; otherwise, `{:error, :restricted}`.
   """
-  def get(url, options \\ [], headers \\ [], httpoison_options \\ []) do
-    if validate_url(url, options) do
-      HTTPoison.get(url, headers, httpoison_options)
+  @spec allowed?(binary(), Keyword.t()) :: boolean()
+  def allowed?(url, opts \\ []) do
+    uri = URI.parse(url)
+    opts = build_options(opts)
+    address = resolve_address(uri.host)
+
+    cond do
+      uri.scheme not in opts.schemes ->
+        false
+
+      opts.whitelist != [] ->
+        ip_in_ranges?(address, opts.whitelist)
+
+      true ->
+        !ip_in_ranges?(address, opts.blacklist)
+    end
+  end
+
+
+  @doc """
+  Alternative method of validating a URL, returning atoms instead
+  of booleans.
+
+  This calls `allowed?/2` underneath to check if a URL is safe to
+  be called. If it is, it returns `:ok`, otherwise
+  `{:error, :restricted}`.
+
+  ## Examples
+
+      iex> SafeURL.validate("https://includesecurity.com")
+      :ok
+
+      iex> SafeURL.validate("http://10.0.0.1/")
+      {:error, :restricted}
+
+      iex> SafeURL.validate("http://10.0.0.1/", whitelist: ~w[10.0.0.0/8])
+      :ok
+
+  ## Options
+
+  See [`Options`](#module-options) section above.
+
+  """
+  @spec validate(binary(), Keyword.t()) :: :ok | {:error, :restricted}
+  def validate(url, opts \\ []) do
+    if allowed?(url, opts) do
+      :ok
     else
       {:error, :restricted}
     end
   end
 
+
   @doc """
-  Validate a string URL against a blacklist or whitelist.
+  Validate a URL and execute a GET request using `HTTPoison`.
 
-  See documentation for `SafeURL.get()` for available options and defaults.
+  If the URL is safe, this function will execute the request using
+  `HTTPoison`, returning the result directly. Otherwise, it will
+  return `{:error, :restricted}`.
+
+  `headers` and `httpoison_options` will be passed directly to
+  `HTTPoison` when the request is executed.
+
+  See `allowed?/2` for more details on URL validation.
+
+  ## Examples
+
+      iex> SafeURL.get("https://10.0.0.1/ssrf.txt")
+      {:error, :restricted}
+
+      iex> SafeURL.get("https://google.com/")
+      {:ok, %HTTPoison.Response{...}}
+
+      iex> SafeURL.get("https://google.com/", schemes: ~w[ftp])
+      {:error, :restricted}
+
+  ## Options
+
+  See [`Options`](#module-options) section above.
 
-  Returns `true` if the URL meets the requirements, `false` otherwise.
   """
-  def validate_url(url, options \\ []) do
-    blacklist_private = Keyword.get(options, :blacklist_private, true)
-    blacklist = Keyword.get(options, :blacklist, [])
-    whitelist = Keyword.get(options, :whitelist, [])
-    schemes = Keyword.get(options, :schemes, ["http", "https"])
-    host_info = URI.parse(url)
-
-    # TODO: Refactor this to use idiomatic elixir control flow
-    if validate_scheme(host_info.scheme, schemes) == false do
-      false
-    else
-      addr = resolve_address(host_info.host)
-      if length(whitelist) != 0 do
-        validate_whitelist(addr, whitelist)
+  @spec get(binary(), Keyword.t(), HTTPoison.headers(), Keyword.t()) ::
+          {:ok, HTTPoison.Response.t()} | {:error, :restricted}
+  def get(url, options \\ [], headers \\ [], httpoison_options \\ []) do
+    with :ok <- validate(url, options) do
+      HTTPoison.get(url, headers, httpoison_options)
+    end
+  end
+
+
+
+
+  # Private Helpers
+  # ---------------
+
+
+  # Return a map of calculated options
+  defp build_options(opts) do
+    schemes = get_option(opts, :schemes)
+    whitelist = get_option(opts, :whitelist)
+    blacklist = get_option(opts, :blacklist)
+
+    blacklist =
+      if get_option(opts, :blacklist_reserved) do
+        blacklist ++ @reserved_ranges
       else
-        if blacklist_private == false do
-          validate_blacklist(addr, blacklist)
-        else
-          validate_blacklist(addr, @reserved_ranges ++ blacklist)
-        end
+        blacklist
       end
-    end
+
+    %{schemes: schemes, whitelist: whitelist, blacklist: blacklist}
   end
 
-  defp resolve_address(hostname) do
-    # Don't resolve hostname in DNS if it's an IP address
-    {result, value} = hostname |> to_charlist() |> :inet.parse_address()
-    if result != :ok do
-      {_, ip} = DNS.resolve(hostname)
-      # TODO: safely handle multiple IPs/round-robin DNS
-      List.first(ip)
+
+  # Get the value of a specific option, either from the application
+  # configs or overrides explicitly passed as arguments.
+  defp get_option(opts, key) do
+    if Keyword.has_key?(opts, key) do
+      Keyword.get(opts, key)
     else
-      value
+      Application.get_env(:safeurl, key)
     end
   end
 
-  defp validate_scheme(scheme, allowed_schemes) do
-    Enum.member?(allowed_schemes, scheme)
-  end
 
-  defp validate_whitelist(address, whitelist) do
-    Enum.any?(whitelist, fn range ->
-      InetCidr.contains?(InetCidr.parse(range), address)
-    end)
+  # Resolve hostname in DNS to an IP address (if not already an IP)
+  defp resolve_address(hostname) do
+    hostname
+    |> to_charlist()
+    |> :inet.parse_address()
+    |> case do
+      {:ok, ip} ->
+        ip
+
+      {:error, :einval} ->
+        # TODO: safely handle multiple IPs/round-robin DNS
+        case DNS.resolve(hostname) do
+          {:ok, ips} -> List.first(ips)
+          {:error, _reason} -> nil
+        end
+    end
   end
 
-  defp validate_blacklist(address, blacklist) do
-    !Enum.any?(blacklist, fn range ->
-      InetCidr.contains?(InetCidr.parse(range), address)
+
+  defp ip_in_ranges?({_, _, _, _} = addr, ranges) when is_list(ranges) do
+    Enum.any?(ranges, fn range ->
+      range
+      |> InetCidr.parse()
+      |> InetCidr.contains?(addr)
     end)
   end
+
+  defp ip_in_ranges?(_addr, _ranges), do: false
 end