pii_scrubber 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d3b640a3c54112489c787e96db29e53c56bf4780c9183eb3e3045a626e759a1
+  data.tar.gz: 91be1a34d87cf3d9e883c1110490fb4569cb9eb4fdbbec162dc1c862ce94763f
+SHA512:
+  metadata.gz: 12752d059f4cd33bcfcae68f2b571fe76dfd80cd1697b0f386066b3ee02020f0c5988ff9646c628be71f0484fad3ada6488224c3a3417bd33bbd641588b3fb76
+  data.tar.gz: 52c5f6e8e595a95f68327156ba8947df9b6ff316369167c6c1eaf1cd43a09b53fe1342e8d5a2fa9b91b6c77e3686ae9f890a7dd92682eeacc8fe4928d663291e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PiiScrubber Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,236 @@
+# 🛡️ PiiScrubber
+
+[![Gem Version](https://badge.fury.io/rb/pii_scrubber.svg)](https://badge.fury.io/rb/pii_scrubber)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**PiiScrubber** is a high-performance, pluggable Ruby gem for detecting and sanitizing Personally Identifiable Information (PII) and API secrets from strings, nested data structures, Rails logs, Faraday HTTP requests, and LLM prompt contexts.
+
+---
+
+## ✨ Features
+
+- ✉️ **Email Addresses** (`user@example.com` → `[REDACTED:EMAIL]` or `j***@e***.com`)
+- 📱 **Phone Numbers** (`+1-800-555-0199` → `[REDACTED:PHONE]`)
+- 💳 **Credit Cards** (Supports Luhn algorithm checksum validation to eliminate false positives)
+- 🪪 **US Social Security Numbers (SSN)** (`123-45-6789`)
+- 🏦 **International Bank Account Numbers (IBAN)** (ISO 7064 Modulo-97 checksum validation for 80+ countries)
+- 🇬🇧 **UK National Insurance Numbers (NINO)** (`QQ 12 34 56 A`)
+- 🇨🇦 **Canadian Social Insurance Numbers (SIN)** (Luhn algorithm validated)
+- 🇮🇳 **Indian Identifiers**:
+  - **PAN Cards** (`ABCPE1234F` with taxpayer status validation)
+  - **Aadhaar Numbers** (`3675 9834 5017` with Verhoeff algorithm checksum)
+- 🗄️ **Database Connection Strings** (`postgres://user:pass@host:5432/db`, `mysql2://`, `mongodb://`, `redis://`)
+- 🔑 **API Keys & Cloud Secrets** (AWS Access Keys, OpenAI `sk-`, Anthropic `sk-ant-`, Hugging Face `hf_`, SendGrid `SG.`, Twilio `AC`/`SK`, Mailgun `key-`, GitLab `glpat-`, GitHub `ghp_`, Stripe `sk_live_`, Bearer Tokens, RSA Private Keys)
+- 🌐 **IP Addresses** (IPv4 & IPv6)
+- 🌲 **Data Structure Support**: Recursively scrubs `String`, `Hash`, `Array`, and embedded `JSON`.
+- 🔑 **Sensitive Key Redaction**: Automatically redacts values for hash keys matching sensitive terms (`password`, `auth_token`, `secret`, `cvv`, `pin`).
+- 🌍 **Regional Configuration Presets**: Quick switch with `:us`, `:uk`, `:eu`, `:ca`, `:in`, `:finance`, `:secrets`, or `:all`.
+- 🛠️ **Integrations**: Drop-in wrapper for `Logger` / Rails `ActiveSupport::Logger`, `Faraday` HTTP middleware, and `Rack` middleware.
+- 💻 **CLI Utility**: Scrub log files directly from the command line (`cat app.log | pii_scrubber`).
+
+---
+
+## 📦 Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "pii_scrubber"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Usage
+
+```ruby
+require "pii_scrubber"
+
+# Simple String Scrubbing
+PiiScrubber.scrub("Please contact Jane Doe at jane@example.com or call 555-123-4567.")
+# => "Please contact Jane Doe at [REDACTED:EMAIL] or call [REDACTED:PHONE]."
+
+# Nested Hash & Sensitive Key Redaction
+payload = {
+  user: {
+    username: "john_smith",
+    password: "mysecretpassword123", # Key matches sensitive key pattern
+    email: "john.smith@gmail.com",
+    api_key: "sk-proj-1234567890abcdef1234567890abcdef12345678"
+  }
+}
+
+PiiScrubber.scrub(payload)
+# => {
+#      user: {
+#        username: "john_smith",
+#        password: "[REDACTED:PASSWORD]",
+#        email: "[REDACTED:EMAIL]",
+#        api_key: "[REDACTED:API_KEY]"
+#      }
+#    }
+```
+
+---
+
+### 2. Regional Presets & International PII
+
+Easily configure detection for specific geographic regions or security profiles:
+
+```ruby
+PiiScrubber.configure do |config|
+  # Use regional preset (:us, :uk, :eu, :ca, :in, :finance, :secrets, or :all)
+  config.use_preset(:eu)
+
+  # Or selectively enable/disable detectors
+  config.enable_detector(:iban, :uk_nino)
+  config.disable_detector(:ip_address)
+end
+
+# Multi-country detection with checksum validation
+text = "IBAN: GB82WEST12345698765432, SIN: 130-692-544, DB: postgres://user:secret@localhost/db"
+PiiScrubber.scrub(text)
+# => "IBAN: [REDACTED:IBAN], SIN: [REDACTED:CANADIAN_SIN], DB: [REDACTED:DATABASE_URL]"
+```
+
+---
+
+### 3. Custom Rules & Proc Redaction Strategy
+
+```ruby
+PiiScrubber.configure do |config|
+  # Add custom rule via DSL
+  config.add_rule(:employee_code, /EMP-\d{4}/)
+
+  # Custom Proc strategy
+  config.strategy = ->(match, detector_name) { "<HIDDEN_#{detector_name.to_s.upcase}>" }
+end
+
+PiiScrubber.scrub("Employee EMP-1234 email is test@company.com")
+# => "Employee <HIDDEN_EMPLOYEE_CODE> email is <HIDDEN_EMAIL>"
+```
+
+---
+
+### 4. 🤖 Reversible Anonymization Vault (For LLMs & APIs)
+
+When sending user input to external LLMs (OpenAI, Anthropic, Gemini) or third-party APIs, anonymize PII before sending the prompt and **restore the real PII values** when rendering the response back to the user:
+
+```ruby
+# 1. Anonymize user prompt before sending to LLM
+session = PiiScrubber.anonymize("Draft an email to Alice at alice@company.com or call 555-123-4567.")
+
+session.text
+# => "Draft an email to Alice at [PII_VAULT_EMAIL_a8f91234] or call [PII_VAULT_PHONE_b4c56789]."
+
+# 2. Pass session.text to OpenAI / LLM
+llm_response = "Confirmed! Email drafted for [PII_VAULT_EMAIL_a8f91234]."
+
+# 3. Restore original PII into LLM output
+restored_response = session.restore(llm_response)
+# => "Confirmed! Email drafted for alice@company.com."
+```
+
+#### Redis / Session Storage Serialization
+
+Vault sessions can be serialized and stored across asynchronous HTTP requests or background jobs:
+
+```ruby
+# Save to Redis / Cache
+redis.set("vault:#{session.id}", session.to_h.to_json)
+
+# Restore in background worker
+saved_hash = JSON.parse(redis.get("vault:#{session.id}"))
+session = PiiScrubber::Vault::Session.from_h(saved_hash)
+final_output = session.restore(async_llm_response)
+```
+
+`pii_scrubber` supports three redaction strategies:
+1. `:placeholder` (Default): `[REDACTED:EMAIL]`
+2. `:mask`: Partial masking (`j***@g***.com` or `************0366`)
+3. `:hash`: HMAC-SHA256 deterministic hash (`[ANON:a3b1f9e8]`)
+
+```ruby
+PiiScrubber.configure do |config|
+  config.strategy = :mask
+  config.mask_char = "*"
+  config.detectors = [:email, :credit_card, :api_key]
+  config.ignored_keys = [:company_email] # Skip scrubbing specific hash keys
+end
+
+PiiScrubber.scrub("Email: john@gmail.com")
+# => "Email: j***@g***.com"
+```
+
+#### HMAC Anonymization Strategy
+
+Useful when you need consistent anonymized tokens for tracking without revealing PII:
+
+```ruby
+PiiScrubber.scrub("User email: john@gmail.com", strategy: :hash, hmac_salt: "my_secret_salt")
+# => "User email: [ANON:c74d0e2b]"
+```
+
+---
+
+### 3. Rails Logger Integration
+
+Sanitize all Rails production logs automatically by updating `config/environments/production.rb`:
+
+```ruby
+# config/environments/production.rb
+Rails.application.configure do
+  config.logger = ActiveSupport::Logger.new(STDOUT)
+  config.logger.formatter = PiiScrubber::Integrations::LoggerFormatter.new
+end
+```
+
+---
+
+### 4. Faraday HTTP Client Integration
+
+Prevent sensitive headers (`Authorization`, `Cookie`) and PII in request/response bodies from leaking into third-party services:
+
+```ruby
+conn = Faraday.new(url: "https://api.example.com") do |faraday|
+  faraday.use PiiScrubber::Integrations::FaradayMiddleware, strategy: :placeholder
+  faraday.adapter Faraday.default_adapter
+end
+```
+
+---
+
+### 5. CLI Executable
+
+PiiScrubber comes with a command-line tool to clean log files on standard input or file paths:
+
+```bash
+# Pipe stdin
+echo "User email is test@example.com and IP is 192.168.1.100" | pii_scrubber
+
+# Process file with masking strategy
+pii_scrubber -s mask production.log
+```
+
+---
+
+## 🧪 Running Tests
+
+To run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/pii_scrubber

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/pii_scrubber"
+
+options = {
+  strategy: :placeholder,
+  mask_char: "*"
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: pii_scrubber [options] [file...]"
+
+  opts.on("-s", "--strategy STRATEGY", %i[placeholder mask hash], "Redaction strategy: placeholder, mask, or hash") do |s|
+    options[:strategy] = s
+  end
+
+  opts.on("-m", "--mask-char CHAR", "Mask character (default: '*')") do |c|
+    options[:mask_char] = c
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "pii_scrubber v#{PiiScrubber::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+end.parse!
+
+def process_stream(stream, options)
+  stream.each_line do |line|
+    print PiiScrubber.scrub(line, **options)
+  end
+end
+
+if ARGV.empty?
+  process_stream($stdin, options)
+else
+  ARGV.each do |filename|
+    File.open(filename, "r") do |file|
+      process_stream(file, options)
+    end
+  end
+end

data/lib/pii_scrubber/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module PiiScrubber
+  class Configuration
+    attr_accessor :detectors, :strategy, :mask_char, :hmac_salt, :ignored_keys, :custom_rules, :sensitive_key_patterns, :redact_sensitive_hash_keys
+
+    ALL_DETECTORS = %i[
+      database_url
+      api_key
+      iban
+      credit_card
+      canadian_sin
+      ssn
+      uk_nino
+      indian_pan
+      indian_aadhaar
+      email
+      phone
+      ip_address
+    ].freeze
+
+    PRESETS = {
+      all: ALL_DETECTORS,
+      us: %i[email phone ssn credit_card api_key ip_address database_url],
+      uk: %i[email phone uk_nino iban credit_card api_key ip_address database_url],
+      eu: %i[email phone iban credit_card api_key ip_address database_url],
+      ca: %i[email phone canadian_sin credit_card api_key ip_address database_url],
+      in: %i[email phone indian_pan indian_aadhaar credit_card api_key ip_address database_url],
+      finance: %i[credit_card iban],
+      secrets: %i[api_key database_url]
+    }.freeze
+
+    def initialize
+      @detectors = ALL_DETECTORS.dup
+      @strategy = :placeholder
+      @mask_char = "*"
+      @hmac_salt = nil
+      @ignored_keys = []
+      @custom_rules = []
+      @redact_sensitive_hash_keys = true
+      @sensitive_key_patterns = [
+        /password/i,
+        /secret/i,
+        /auth_token/i,
+        /access_token/i,
+        /bearer_token/i,
+        /private_key/i,
+        /cvv/i,
+        /card_number/i
+      ]
+    end
+
+    def use_preset(preset_name)
+      preset = PRESETS[preset_name.to_sym]
+      raise ArgumentError, "Unknown preset: #{preset_name}. Valid presets: #{PRESETS.keys.join(', ')}" unless preset
+
+      @detectors = preset.dup
+    end
+
+    def enable_detector(*names)
+      names.each do |name|
+        sym = name.to_sym
+        @detectors << sym unless @detectors.include?(sym)
+      end
+    end
+
+    def disable_detector(*names)
+      syms = names.map(&:to_sym)
+      @detectors.reject! { |d| syms.include?(d) }
+    end
+
+    def add_rule(name, pattern, &validator)
+      @custom_rules << { name: name.to_sym, pattern: pattern, validator: validator }
+    end
+  end
+end

data/lib/pii_scrubber/detectors/api_key.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class ApiKey < Base
+      PATTERNS = [
+        # AWS Access Key ID
+        /\b(AKIA[0-9A-Z]{16})\b/,
+        # OpenAI API Key
+        /\b(sk-[a-zA-Z0-9]{32,}|sk-proj-[a-zA-Z0-9\-_]{32,})\b/,
+        # Anthropic API Key
+        /\b(sk-ant-api[0-9a-zA-Z\-_]{32,})\b/,
+        # Google API Key
+        /\b(AIzaSy[0-9A-Za-z\-_]{35})\b/,
+        # GitHub Tokens
+        /\b(gh[pousr]_[a-zA-Z0-9]{36,40})\b/,
+        # Stripe Keys
+        /\b([sr]k_live_[0-9a-zA-Z]{24,34})\b/,
+        # JWT Bearer Token
+        /\b(Bearer\s+eyJ[a-zA-Z0-9\-_]+\.eyJ[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+)\b/,
+        # Generic Slack / Slack Bot Token
+        /\b(xox[baprs]-[0-9a-zA-Z]{10,48})\b/,
+        # Hugging Face Access Token
+        /\b(hf_[a-zA-Z0-9]{34,})\b/,
+        # SendGrid API Key
+        /\b(SG\.[a-zA-Z0-9_\-]{16,32}\.[a-zA-Z0-9_\-]{32,64})\b/,
+        # Twilio API Key / SID
+        /\b((?:AC|SK)[a-f0-9]{32})\b/,
+        # Mailgun API Key
+        /\b(key-[a-zA-Z0-9]{32})\b/,
+        # GitLab Personal Access Token
+        /\b(glpat-[0-9a-zA-Z\-_]{20,})\b/,
+        # RSA / PEM Private Keys
+        /-----BEGIN (?:RSA|EC|DSA|OPENSSH) PRIVATE KEY-----[[\s\S]]*?-----END (?:RSA|EC|DSA|OPENSSH) PRIVATE KEY-----/
+      ].freeze
+
+      def initialize
+        super(name: :api_key)
+      end
+
+      def patterns
+        PATTERNS
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PiiScrubber
+  module Detectors
+    class Base
+      attr_reader :name
+
+      def initialize(name:)
+        @name = name.to_sym
+      end
+
+      # Returns array of Regexp objects for matching
+      def patterns
+        []
+      end
+
+      # Validates if the regex match is genuinely a PII instance (prevents false positives)
+      def valid?(_match)
+        true
+      end
+
+      # Generates replacement text for the match based on strategy
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        if strategy.is_a?(Proc)
+          return strategy.call(match, name)
+        end
+
+        case strategy
+        when :placeholder
+          "[REDACTED:#{name.to_s.upcase}]"
+        when :mask
+          mask_value(match, mask_char: mask_char)
+        when :hash
+          digest = hmac_salt ? Digest::SHA256.hexdigest("#{hmac_salt}:#{match}")[0..7] : Digest::SHA256.hexdigest(match)[0..7]
+          "[ANON:#{digest}]"
+        else
+          "[REDACTED:#{name.to_s.upcase}]"
+        end
+      end
+
+      protected
+
+      def mask_value(val, mask_char: "*")
+        return mask_char * val.length if val.length <= 4
+
+        # Keep first and last character visible, mask middle
+        first = val[0]
+        last = val[-1]
+        masked_length = [val.length - 2, 1].max
+        "#{first}#{mask_char * masked_length}#{last}"
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/canadian_sin.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class CanadianSin < Base
+      # Matches 9-digit Canadian Social Insurance Numbers (e.g. 046-454-286, 046 454 286, 046454286)
+      SIN_REGEX = /\b[0-9]{3}[ -]?[0-9]{3}[ -]?[0-9]{3}\b/
+
+      def initialize
+        super(name: :canadian_sin)
+      end
+
+      def patterns
+        [SIN_REGEX]
+      end
+
+      def valid?(match)
+        digits = match.scan(/\d/).map(&:to_i)
+        return false unless digits.size == 9
+
+        # First digit cannot be 0 or 8 in valid Canadian SINs
+        return false if [0, 8].include?(digits.first)
+
+        luhn_valid?(digits)
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        digits = match.scan(/\d/)
+        return super if digits.size != 9
+
+        last_three = digits.last(3).join
+        "#{mask_char * 3}-#{mask_char * 3}-#{last_three}"
+      end
+
+      private
+
+      def luhn_valid?(digits)
+        checksum = 0
+        reverse_digits = digits.reverse
+
+        reverse_digits.each_with_index do |digit, index|
+          if index.odd?
+            doubled = digit * 2
+            checksum += doubled > 9 ? doubled - 9 : doubled
+          else
+            checksum += digit
+          end
+        end
+
+        (checksum % 10).zero?
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/credit_card.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class CreditCard < Base
+      # Matches 13-19 digit card numbers separated by optional dashes or spaces
+      CREDIT_CARD_REGEX = /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b/
+      GENERIC_CARD_REGEX = /\b(?:\d[ -]*?){13,19}\b/
+
+      def initialize
+        super(name: :credit_card)
+      end
+
+      def patterns
+        [CREDIT_CARD_REGEX, GENERIC_CARD_REGEX]
+      end
+
+      def valid?(match)
+        digits = match.scan(/\d/).map(&:to_i)
+        return false unless digits.size >= 13 && digits.size <= 19
+
+        luhn_valid?(digits)
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        digits = match.scan(/\d/)
+        return super if digits.size < 4
+
+        # Show last 4 digits
+        last_four = digits.last(4).join
+        "#{mask_char * 12}#{last_four}"
+      end
+
+      private
+
+      # Luhn algorithm implementation for checking credit card checksum
+      def luhn_valid?(digits)
+        checksum = 0
+        reverse_digits = digits.reverse
+
+        reverse_digits.each_with_index do |digit, index|
+          if index.odd?
+            doubled = digit * 2
+            checksum += doubled > 9 ? doubled - 9 : doubled
+          else
+            checksum += digit
+          end
+        end
+
+        (checksum % 10).zero?
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/database_url.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class DatabaseUrl < Base
+      # Matches connection strings with embedded user/password credentials
+      DATABASE_URL_REGEX = /\b(?:postgres(?:ql)?|mysql2?|mongodb(?:\+srv)?|rediss?|amqps?|mssql|sqlserver):\/\/(?:[^:\s\/]+:)?(?:[^@\s\/]+)@[^\s\/:]+(?::\d+)?(?:\/[^\s"']*)?/i
+
+      def initialize
+        super(name: :database_url)
+      end
+
+      def patterns
+        [DATABASE_URL_REGEX]
+      end
+
+      def valid?(match)
+        # Ensure it contains @ separating credentials from host
+        match.include?("@") && match.include?("://")
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        case strategy
+        when :mask
+          # Mask password while preserving scheme, username, host and database
+          match.sub(%r{://(?:([^:@\s/]+):)?([^@\s/]+)@}) do
+            user_part = $1 ? "#{$1}:" : ""
+            "://#{user_part}#{mask_char * 8}@"
+          end
+        when :placeholder
+          "[REDACTED:DATABASE_URL]"
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/email.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class Email < Base
+      EMAIL_REGEX = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/
+
+      def initialize
+        super(name: :email)
+      end
+
+      def patterns
+        [EMAIL_REGEX]
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        user, domain = match.split("@", 2)
+        return super unless user && domain
+
+        masked_user = mask_value(user, mask_char: mask_char)
+        domain_parts = domain.split(".")
+        masked_domain_name = mask_value(domain_parts[0], mask_char: mask_char)
+        tld = domain_parts[1..].join(".")
+
+        "#{masked_user}@#{masked_domain_name}.#{tld}"
+      end
+    end
+  end
+end