refa: extract scrubber (#1050)

* feat(scrubber): introduce shared Sentry.Scrubber module

Adds a framework-agnostic module that owns the canonical default sensitive
key lists, the redaction placeholder, the credit-card detection heuristic,
and the recursive map/list traversal used to scrub data before it is sent
to Sentry. Existing integrations duplicate these primitives today; this
module provides a single source of truth that follow-up commits will route
PlugContext, PlugCapture, and LiveViewHook through.

The default behavior matches the existing Sentry.PlugContext defaults
("*********" placeholder, ["password", "passwd", "secret"] for params,
["authorization", "authentication", "cookie"] for headers) so no
existing scrubbing output changes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(plug_context): delegate default scrubbers to Sentry.Scrubber

Removes the duplicated denylist constants, placeholder, credit-card
regex, and recursive scrub_map/scrub_list helpers from
Sentry.PlugContext in favor of the shared Sentry.Scrubber module.
Public function signatures and the documented default key sets are
unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: solnic

lib/sentry/plug_context.ex

@@ -153,9 +153,8 @@ defmodule Sentry.PlugContext do
     end
   end
 
-  @default_scrubbed_param_keys ["password", "passwd", "secret"]
-  @default_scrubbed_header_keys ["authorization", "authentication", "cookie"]
-  @scrubbed_value "*********"
+  @default_scrubbed_param_keys Sentry.Scrubber.default_param_keys()
+  @default_scrubbed_header_keys Sentry.Scrubber.default_header_keys()
   @default_plug_request_id_header "x-request-id"
 
   @doc false
@@ -256,7 +255,7 @@ defmodule Sentry.PlugContext do
   def default_header_scrubber(conn) do
     conn.req_headers
     |> Map.new()
-    |> Map.drop(@default_scrubbed_header_keys)
+    |> Sentry.Scrubber.drop_keys()
   end
 
   @doc """
@@ -268,35 +267,6 @@ defmodule Sentry.PlugContext do
   """
   @spec default_body_scrubber(Plug.Conn.t()) :: map()
   def default_body_scrubber(conn) do
-    scrub_map(conn.params, @default_scrubbed_param_keys)
+    Sentry.Scrubber.scrub_map(conn.params)
   end
-
-  defp scrub_map(map, scrubbed_keys) do
-    Map.new(map, fn {key, value} ->
-      value =
-        cond do
-          key in scrubbed_keys -> @scrubbed_value
-          is_binary(value) and value =~ credit_card_regex() -> @scrubbed_value
-          is_struct(value) -> value |> Map.from_struct() |> scrub_map(scrubbed_keys)
-          is_map(value) -> scrub_map(value, scrubbed_keys)
-          is_list(value) -> scrub_list(value, scrubbed_keys)
-          true -> value
-        end
-
-      {key, value}
-    end)
-  end
-
-  defp scrub_list(list, scrubbed_keys) do
-    Enum.map(list, fn value ->
-      cond do
-        is_struct(value) -> value |> Map.from_struct() |> scrub_map(scrubbed_keys)
-        is_map(value) -> scrub_map(value, scrubbed_keys)
-        is_list(value) -> scrub_list(value, scrubbed_keys)
-        true -> value
-      end
-    end)
-  end
-
-  defp credit_card_regex, do: ~r/^(?:\d[ -]*?){13,16}$/
 end

lib/sentry/scrubber.ex

@@ -0,0 +1,196 @@
+defmodule Sentry.Scrubber do
+  @moduledoc """
+  Shared, framework-agnostic helpers for scrubbing sensitive data before it is
+  sent to Sentry.
+
+  *Available since v13.1.0.*
+
+  This module owns the default sensitive key lists, the placeholder used in
+  place of redacted values, the credit-card detection heuristic, and the
+  recursive map/list traversal used by the rest of the SDK to redact values.
+  Integrations such as `Sentry.PlugContext`, `Sentry.PlugCapture`, and
+  `Sentry.LiveViewHook` delegate to the functions exposed here so that
+  scrubbing rules live in a single place.
+
+  ## Defaults
+
+  The default sensitive *parameter* keys (used for body params, query strings,
+  and arbitrary maps) are:
+
+  #{Enum.map_join(["password", "passwd", "secret"], "\n", &"  * `\"#{&1}\"`")}
+
+  The default sensitive *header* keys are:
+
+  #{Enum.map_join(["authorization", "authentication", "cookie"], "\n", &"  * `\"#{&1}\"`")}
+
+  Values matching a credit-card-like pattern (13–16 digits, optionally
+  separated by spaces or dashes) are also replaced with the placeholder.
+
+  ## Custom scrubbing
+
+  All public functions accept an optional `:keys` option that overrides the
+  default list of sensitive keys. This makes it possible to compose custom
+  scrubbers on top of the defaults:
+
+      def scrub(map) do
+        map
+        |> Sentry.Scrubber.scrub_map(keys: ["password", "api_key"])
+        |> Map.drop(["internal_notes"])
+      end
+  """
+
+  @moduledoc since: "13.1.0"
+
+  @default_scrubbed_param_keys ["password", "passwd", "secret"]
+  @default_scrubbed_header_keys ["authorization", "authentication", "cookie"]
+  @scrubbed_value "*********"
+
+  @typedoc """
+  Options accepted by the scrubbing functions in this module.
+  """
+  @type option :: {:keys, [String.t()]}
+
+  @doc """
+  The placeholder string used to replace scrubbed values.
+  """
+  @spec scrubbed_value() :: String.t()
+  def scrubbed_value, do: @scrubbed_value
+
+  @doc """
+  Returns the default list of sensitive parameter keys.
+  """
+  @spec default_param_keys() :: [String.t()]
+  def default_param_keys, do: @default_scrubbed_param_keys
+
+  @doc """
+  Returns the default list of sensitive header keys.
+  """
+  @spec default_header_keys() :: [String.t()]
+  def default_header_keys, do: @default_scrubbed_header_keys
+
+  @doc """
+  Recursively scrubs a map.
+
+  Any value whose key is in the configured sensitive key list is replaced with
+  the placeholder. Values matching the credit-card pattern are also replaced.
+  Nested maps, structs, and lists are scrubbed recursively.
+
+  ## Options
+
+    * `:keys` - the list of sensitive keys to redact. Defaults to
+      `default_param_keys/0`.
+  """
+  @spec scrub_map(map(), [option()]) :: map()
+  def scrub_map(map, opts \\ []) when is_map(map) do
+    keys = Keyword.get(opts, :keys, @default_scrubbed_param_keys)
+    do_scrub_map(map, keys)
+  end
+
+  @doc """
+  Recursively scrubs a list, applying the same rules as `scrub_map/2` to any
+  maps it contains.
+
+  ## Options
+
+  See `scrub_map/2`.
+  """
+  @spec scrub_list(list(), [option()]) :: list()
+  def scrub_list(list, opts \\ []) when is_list(list) do
+    keys = Keyword.get(opts, :keys, @default_scrubbed_param_keys)
+    do_scrub_list(list, keys)
+  end
+
+  @doc """
+  Drops sensitive keys from a flat map.
+
+  This is the strategy used for HTTP headers, where the sensitive value should
+  not appear in the payload at all.
+
+  ## Options
+
+    * `:keys` - the list of sensitive keys to drop. Defaults to
+      `default_header_keys/0`.
+  """
+  @spec drop_keys(map(), [option()]) :: map()
+  def drop_keys(map, opts \\ []) when is_map(map) do
+    keys = Keyword.get(opts, :keys, @default_scrubbed_header_keys)
+    Map.drop(map, keys)
+  end
+
+  @doc """
+  Scrubs the query string portion of a URL, replacing the value of any
+  sensitive query parameter with the placeholder. URLs without a query string
+  are returned unchanged.
+
+  ## Options
+
+  See `scrub_map/2`.
+  """
+  @spec scrub_url(String.t(), [option()]) :: String.t()
+  def scrub_url(url, opts \\ []) when is_binary(url) do
+    case URI.parse(url) do
+      %URI{query: nil} ->
+        url
+
+      %URI{query: ""} ->
+        url
+
+      %URI{query: query} = uri ->
+        URI.to_string(%{uri | query: scrub_query_string(query, opts)})
+    end
+  end
+
+  @doc """
+  Scrubs an `application/x-www-form-urlencoded` query string, replacing the
+  value of any sensitive parameter with the placeholder.
+
+  ## Options
+
+  See `scrub_map/2`.
+  """
+  @spec scrub_query_string(String.t(), [option()]) :: String.t()
+  def scrub_query_string(query, opts \\ []) when is_binary(query) do
+    keys = Keyword.get(opts, :keys, @default_scrubbed_param_keys)
+
+    query
+    |> URI.query_decoder()
+    |> Enum.map(fn {key, value} ->
+      cond do
+        key in keys -> {key, @scrubbed_value}
+        is_binary(value) and value =~ credit_card_regex() -> {key, @scrubbed_value}
+        true -> {key, value}
+      end
+    end)
+    |> URI.encode_query()
+  end
+
+  ## Internal recursion
+
+  defp do_scrub_map(map, keys) do
+    Map.new(map, fn {key, value} -> {key, scrub_value(key, value, keys)} end)
+  end
+
+  defp do_scrub_list(list, keys) do
+    Enum.map(list, fn value ->
+      cond do
+        is_struct(value) -> value |> Map.from_struct() |> do_scrub_map(keys)
+        is_map(value) -> do_scrub_map(value, keys)
+        is_list(value) -> do_scrub_list(value, keys)
+        true -> value
+      end
+    end)
+  end
+
+  defp scrub_value(key, value, keys) do
+    cond do
+      key in keys -> @scrubbed_value
+      is_binary(value) and value =~ credit_card_regex() -> @scrubbed_value
+      is_struct(value) -> value |> Map.from_struct() |> do_scrub_map(keys)
+      is_map(value) -> do_scrub_map(value, keys)
+      is_list(value) -> do_scrub_list(value, keys)
+      true -> value
+    end
+  end
+
+  defp credit_card_regex, do: ~r/^(?:\d[ -]*?){13,16}$/
+end

test/sentry/scrubber_test.exs

@@ -0,0 +1,83 @@
+defmodule Sentry.ScrubberTest do
+  use ExUnit.Case, async: true
+
+  alias Sentry.Scrubber
+
+  describe "scrub_map/2" do
+    test "redacts sensitive top-level keys" do
+      assert Scrubber.scrub_map(%{"password" => "x", "ok" => 1}) ==
+               %{"password" => "*********", "ok" => 1}
+    end
+
+    test "recurses into nested maps" do
+      assert Scrubber.scrub_map(%{"outer" => %{"secret" => "shh"}}) ==
+               %{"outer" => %{"secret" => "*********"}}
+    end
+
+    test "recurses into lists of maps" do
+      assert Scrubber.scrub_map(%{"items" => [%{"passwd" => "1"}, %{"ok" => 2}]}) ==
+               %{"items" => [%{"passwd" => "*********"}, %{"ok" => 2}]}
+    end
+
+    test "redacts credit-card-shaped values" do
+      assert Scrubber.scrub_map(%{"cc" => "4111111111111111"}) ==
+               %{"cc" => "*********"}
+    end
+
+    test "scrubs structs by converting them to maps" do
+      uri = URI.parse("http://example.com")
+      assert %{"u" => scrubbed} = Scrubber.scrub_map(%{"u" => uri})
+      assert is_map(scrubbed)
+      refute Map.has_key?(scrubbed, :__struct__)
+    end
+
+    test "respects custom :keys option" do
+      assert Scrubber.scrub_map(%{"api_key" => "x", "password" => "y"}, keys: ["api_key"]) ==
+               %{"api_key" => "*********", "password" => "y"}
+    end
+
+    test "leaves non-sensitive values untouched" do
+      data = %{"name" => "alice", "age" => 30}
+      assert Scrubber.scrub_map(data) == data
+    end
+  end
+
+  describe "drop_keys/2" do
+    test "drops sensitive header keys by default" do
+      assert Scrubber.drop_keys(%{"authorization" => "Bearer x", "x-trace" => "1"}) ==
+               %{"x-trace" => "1"}
+    end
+
+    test "respects custom :keys option" do
+      assert Scrubber.drop_keys(%{"x-secret" => "1", "x-trace" => "1"}, keys: ["x-secret"]) ==
+               %{"x-trace" => "1"}
+    end
+  end
+
+  describe "scrub_url/2" do
+    test "redacts sensitive query parameters" do
+      url = "http://example.com/foo?password=secret&visible=ok"
+      scrubbed = Scrubber.scrub_url(url)
+      refute scrubbed =~ "secret"
+      assert scrubbed =~ "visible=ok"
+    end
+
+    test "passes through URLs without query strings" do
+      assert Scrubber.scrub_url("http://example.com/foo") == "http://example.com/foo"
+    end
+
+    test "preserves scheme, host, port, and path" do
+      scrubbed = Scrubber.scrub_url("https://example.com:8443/p?secret=x")
+      assert scrubbed =~ "https://example.com:8443/p?"
+      refute scrubbed =~ "secret=x"
+    end
+  end
+
+  describe "scrub_query_string/2" do
+    test "redacts sensitive params" do
+      scrubbed = Scrubber.scrub_query_string("password=hunter2&visible=ok")
+      refute scrubbed =~ "hunter2"
+      assert scrubbed =~ "visible=ok"
+    end
+  end
+end