Add :detailed_error option

Author: martosaur

README.md

@@ -49,20 +49,20 @@ iex> SafeURL.allowed?("https://includesecurity.com")
 true
 
 iex> SafeURL.validate("http://google.com/", schemes: ~w[https])
-{:error, :restricted}
+{:error, :unsafe_scheme}
 
 iex> SafeURL.validate("http://230.10.10.10/")
-{:error, :restricted}
+{:error, :unsafe_reserved}
 
 iex> SafeURL.validate("http://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.HTTPoison.get("https://10.0.0.1/ssrf.txt")
+{:error, :unsafe_reserved}
 
-iex> SafeURL.get("https://google.com/")
+iex> SafeURL.HTTPoison.get("https://google.com/")
 {:ok, %HTTPoison.Response{...}}
 ```
 
@@ -86,6 +86,8 @@ following options:
 - `:dns_module` - Any module that implements the `SafeURL.DNSResolver` behaviour.
   Defaults to `DNS` from the [`:dns`][lib-dns] package.
 
+- `:detailed_error` - Return specific error if validation fails. If set to `false`, `validate/2` will return `{:error, :restricted}` regardless of the reason. Defaults to `true`.
+
 These options can be passed to the function directly or set globally in your `config.exs`
 file:
 
@@ -103,7 +105,7 @@ Find detailed documentation on [HexDocs][docs].
 
 ## HTTP Clients
 
-While SafeURL already provides a convenient [`get/4`][docs-get] method to validate hosts
+While SafeURL already provides a convenient [`SafeURL.HTTPoison.get/3`][docs-get] 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.
 
@@ -137,29 +139,15 @@ iex> CustomClient.get("http://230.10.10.10/data.json", [], safeurl: [block_reser
 
 ### Tesla
 
-For [Tesla][lib-tesla], you can write a custom middleware to halt requests that are not
-allowed:
-
-```elixir
-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:
+For [Tesla][lib-tesla], `SafeURL` provides a helper middleware out-of-the-box, which you can plug anywhere you're using `Tesla`:
 
 ```elixir
 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"]
+  plug SafeURL.TeslaMiddleware, schemes: ~w[https], allowlist: ["10.0.0.0/24"]
 
   def fetch(id) do
     get("/documents/#{id}")

lib/safeurl/safeurl.ex

@@ -8,9 +8,7 @@ defmodule SafeURL do
   allowed to make requests.
 
   You can use `allowed?/2` or `validate/2` to check if a
-  URL is safe to call. If the `HTTPoison` application is
-  available, you can also call `get/4` directly which will
-  validate the host before making an HTTP request.
+  URL is safe to call.
 
 
   ## Examples
@@ -19,18 +17,18 @@ defmodule SafeURL do
       true
 
       iex> SafeURL.validate("http://google.com/", schemes: ~w[https])
-      {:error, :restricted}
+      {:error, :unsafe_scheme}
 
       iex> SafeURL.validate("http://230.10.10.10/")
-      {:error, :restricted}
+      {:error, :unsafe_reserved}
 
       iex> SafeURL.validate("http://230.10.10.10/", block_reserved: false)
       :ok
 
       # If HTTPoison is available:
 
       iex> SafeURL.HTTPoison.get("https://10.0.0.1/ssrf.txt")
-      {:error, :restricted}
+      {:error, :unsafe_reserved}
 
       iex> SafeURL.HTTPoison.get("https://google.com/")
       {:ok, %HTTPoison.Response{...}}
@@ -57,6 +55,10 @@ defmodule SafeURL do
       `SafeURL.DNSResolver` behaviour. Defaults to `DNS` from
       the `:dns` package.
 
+    * `:detailed_error` - Return specific error if validation fails. If set to
+      `false`, `validate/2` will return `{:error, :restricted}` regardless of
+      the reason. Defaults to `true`.
+
 
   If `:block_reserved` is `true` and additional hosts/ranges
   are supplied with `:blocklist`, both of them are included in
@@ -105,12 +107,11 @@ defmodule SafeURL do
     "240.0.0.0/4"
   ]
 
-
+  @type error() :: :unsafe_scheme | :unsafe_allowlist | :unsafe_blocklist | :unsafe_reserved
 
   # Public API
   # ----------
 
-
   @doc """
   Validate a string URL against a blocklist or allowlist.
 
@@ -139,29 +140,19 @@ defmodule SafeURL do
   """
   @spec allowed?(binary(), Keyword.t()) :: boolean()
   def allowed?(url, opts \\ []) do
-    uri = URI.parse(url)
-    opts = build_options(opts)
-    address = resolve_address(uri.host, opts.dns_module)
-
-    cond do
-      uri.scheme not in opts.schemes ->
-        false
-
-      opts.allowlist != [] ->
-        ip_in_ranges?(address, opts.allowlist)
-
-      true ->
-        !ip_in_ranges?(address, opts.blocklist)
+    case validate(url, opts) do
+      :ok -> true
+      {:error, _} -> false
     end
   end
 
-
   @doc """
-  Alternative method of validating a URL, returning atoms instead
+  Alternative method of validating a URL, returning result tuple 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
+  be called. If it is, it returns `:ok`, otherwise an error tuple with a
+  specific reason. If `:detailed_error` is set to `false`, the error is always
   `{:error, :restricted}`.
 
   ## Examples
@@ -180,48 +171,61 @@ defmodule SafeURL do
   See [`Options`](#module-options) section above.
 
   """
-  @spec validate(binary(), Keyword.t()) :: :ok | {:error, :restricted}
+  @spec validate(binary(), Keyword.t()) :: :ok | {:error, error() | :restricted}
   def validate(url, opts \\ []) do
-    if allowed?(url, opts) do
-      :ok
-    else
-      {:error, :restricted}
+    uri = URI.parse(url)
+    opts = build_options(opts)
+    address = resolve_address(uri.host, opts.dns_module)
+
+    result =
+      cond do
+        uri.scheme not in opts.schemes ->
+          {:error, :unsafe_scheme}
+
+        opts.allowlist != [] ->
+          if ip_in_ranges?(address, opts.allowlist), do: :ok, else: {:error, :unsafe_allowlist}
+
+        opts.blocklist != [] and ip_in_ranges?(address, opts.blocklist) ->
+          {:error, :unsafe_blocklist}
+
+        opts.block_reserved and ip_in_ranges?(address, @reserved_ranges) ->
+          {:error, :unsafe_reserved}
+
+        true ->
+          :ok
+      end
+
+    with {:error, _} <- result do
+      if opts.detailed_error, do: result, else: {:error, :restricted}
     end
   end
 
-
   # Private Helpers
   # ---------------
 
-
   # Return a map of calculated options
   defp build_options(opts) do
     schemes = get_option(opts, :schemes)
     allowlist = get_option(opts, :allowlist)
     blocklist = get_option(opts, :blocklist)
     dns_module = get_option(opts, :dns_module)
-
-    blocklist =
-      if get_option(opts, :block_reserved) do
-        blocklist ++ @reserved_ranges
-      else
-        blocklist
-      end
-
-    %{schemes: schemes, allowlist: allowlist, blocklist: blocklist, dns_module: dns_module}
+    block_reserved = get_option(opts, :block_reserved)
+    detailed_error = get_option(opts, :detailed_error)
+
+    %{
+      schemes: schemes,
+      allowlist: allowlist,
+      blocklist: blocklist,
+      dns_module: dns_module,
+      block_reserved: block_reserved,
+      detailed_error: detailed_error
+    }
   end
 
-
   # 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
-      Application.get_env(:safeurl, key)
-    end
-  end
-
+  defp get_option(opts, key),
+    do: Keyword.get_lazy(opts, key, fn -> Application.get_env(:safeurl, key) end)
 
   # Resolve hostname in DNS to an IP address (if not already an IP)
   defp resolve_address(hostname, dns_module) do
@@ -241,7 +245,6 @@ defmodule SafeURL do
     end
   end
 
-
   defp ip_in_ranges?({_, _, _, _} = addr, ranges) when is_list(ranges) do
     Enum.any?(ranges, fn range ->
       range

mix.exs

@@ -50,6 +50,7 @@ defmodule SafeURL.MixProject do
       blocklist: [],
       allowlist: [],
       dns_module: DNS,
+      detailed_error: true
     ]
   end
 

test/safeurl/tesla_middleware_test.exs

@@ -22,7 +22,7 @@ defmodule SafeURL.TeslaMiddlewareTest do
       Tesla.client([Tesla.Middleware.Logger, {TeslaMiddleware, dns_module: TestDNSResolver}])
 
     assert capture_log(fn ->
-             assert {:error, :restricted} = Tesla.get(client, "http://blocked")
-           end) =~ "http://blocked -> error: :restricted"
+             assert {:error, :unsafe_reserved} = Tesla.get(client, "http://blocked")
+           end) =~ "http://blocked -> error: :unsafe_reserved"
   end
 end

test/safeurl_test.exs

@@ -8,59 +8,58 @@ defmodule SafeURLTest do
     def resolve(_domain), do: {:ok, [{192, 0, 78, 24}]}
   end
 
-
-  # setup_all do
-  #   global_whitelist = ["10.0.0.0/24"]
-  #   global_blacklist = ["8.8.0.0/16"]
-
-  #   Application.put_env(:safeurl, :whitelist, global_whitelist)
-  # end
-
-  describe "#allowed?" do
+  describe "validate/2?" do
     test "returns true for only allowed schemes" do
       opts = [dns_module: TestDNSResolver]
-      assert SafeURL.allowed?("http://includesecurity.com", opts)
-      assert SafeURL.allowed?("https://includesecurity.com", opts)
-      refute SafeURL.allowed?("ftp://includesecurity.com", opts)
+      assert :ok = SafeURL.validate("http://includesecurity.com", opts)
+      assert :ok = SafeURL.validate("https://includesecurity.com", opts)
+      assert {:error, :unsafe_scheme} = SafeURL.validate("ftp://includesecurity.com", opts)
 
       opts = [schemes: ~w[ftp], dns_module: TestDNSResolver]
-      assert SafeURL.allowed?("ftp://includesecurity.com", opts)
-      refute SafeURL.allowed?("http://includesecurity.com", opts)
+      assert :ok = SafeURL.validate("ftp://includesecurity.com", opts)
+      assert {:error, :unsafe_scheme} = SafeURL.validate("http://includesecurity.com", opts)
     end
 
     test "returns false for reserved ranges" do
-      refute SafeURL.allowed?("http://0.0.0.0/")
-      refute SafeURL.allowed?("http://10.0.0.1/")
-      refute SafeURL.allowed?("http://127.0.0.1/")
-      refute SafeURL.allowed?("http://169.254.9.1/")
-      refute SafeURL.allowed?("http://192.168.1.1/")
+      assert {:error, :unsafe_reserved} = SafeURL.validate("http://0.0.0.0/")
+      assert {:error, :unsafe_reserved} = SafeURL.validate("http://10.0.0.1/")
+      assert {:error, :unsafe_reserved} = SafeURL.validate("http://127.0.0.1/")
+      assert {:error, :unsafe_reserved} = SafeURL.validate("http://169.254.9.1/")
+      assert {:error, :unsafe_reserved} = SafeURL.validate("http://192.168.1.1/")
     end
 
     test "returns true for reserved ranges if overridden" do
       opts = [block_reserved: false]
 
-      assert SafeURL.allowed?("http://0.0.0.0/", opts)
-      assert SafeURL.allowed?("http://10.0.0.1/", opts)
-      assert SafeURL.allowed?("http://127.0.0.1/", opts)
-      assert SafeURL.allowed?("http://169.254.9.1/", opts)
-      assert SafeURL.allowed?("http://192.168.1.1/", opts)
+      assert :ok = SafeURL.validate("http://0.0.0.0/", opts)
+      assert :ok = SafeURL.validate("http://10.0.0.1/", opts)
+      assert :ok = SafeURL.validate("http://127.0.0.1/", opts)
+      assert :ok = SafeURL.validate("http://169.254.9.1/", opts)
+      assert :ok = SafeURL.validate("http://192.168.1.1/", opts)
     end
 
     test "blocking custom IP ranges" do
       opts = [blocklist: ["5.5.0.0/16", "100.0.0.0/24"], dns_module: TestDNSResolver]
 
-      assert SafeURL.allowed?("http://includesecurity.com", opts)
-      assert SafeURL.allowed?("http://3.3.3.3", opts)
-      refute SafeURL.allowed?("http://5.5.5.5", opts)
-      refute SafeURL.allowed?("http://100.0.0.50", opts)
+      assert :ok = SafeURL.validate("http://includesecurity.com", opts)
+      assert :ok = SafeURL.validate("http://3.3.3.3", opts)
+      assert {:error, :unsafe_blocklist} = SafeURL.validate("http://5.5.5.5", opts)
+      assert {:error, :unsafe_blocklist} = SafeURL.validate("http://100.0.0.50", opts)
     end
 
     test "only allows IPs in the allowlist when present" do
       opts = [allowlist: ["10.0.0.0/24"], dns_module: TestDNSResolver]
 
-      assert SafeURL.allowed?("http://10.0.0.1/", opts)
-      refute SafeURL.allowed?("http://72.254.45.178", opts)
-      refute SafeURL.allowed?("https://includesecurity.com", opts)
+      assert :ok = SafeURL.validate("http://10.0.0.1/", opts)
+      assert {:error, :unsafe_allowlist} = SafeURL.validate("http://72.254.45.178", opts)
+      assert {:error, :unsafe_allowlist} = SafeURL.validate("https://includesecurity.com", opts)
+    end
+
+    test "detailed_errors can be switched off" do
+      opts = [blocklist: ["5.5.0.0/16"], dns_module: TestDNSResolver, detailed_error: false]
+      assert {:error, :restricted} = SafeURL.validate("ftp://includesecurity.com", opts)
+      assert {:error, :restricted} = SafeURL.validate("http://5.5.5.5", opts)
+      assert {:error, :restricted} = SafeURL.validate("http://0.0.0.0/", opts)
     end
   end
 end