Credential Stuffing in Hanami with Api Keys

Credential stuffing is an automated attack technique in which previously breached username and password pairs are systematically attempted against a service to gain unauthorized access. When a Hanami web application relies on Api Keys for authentication without additional protections, the risk of successful credential stuffing escalates because the boundary between user credentials and machine credentials blurs. In Hanami, developers sometimes use Api Keys as bearer tokens in request headers, treating them as equivalent to passwords. However, if these keys are leaked, reused across services, or derived from low-entropy values, they become targets for stuffing campaigns.

Hanami’s architecture often encourages explicit routing and domain modeling, which is beneficial, but if Api Key validation is performed in a way that does not rate-limit or monitor abnormal request volumes, an attacker can automate thousands of attempts using stolen key sets obtained from other breaches. Because Hanami applications may expose public endpoints that accept Api Keys without multi-factor controls, an attacker does not need to exploit an implementation flaw in Hanami itself to succeed; they simply need a valid key that has been inadvertently exposed in logs, client-side code, or insecure storage. This becomes a credential stuffing vector when the same Api Key is reused across multiple APIs or services, and one of those services suffers a data breach.

Another subtlety is that Hanami’s API components might validate Api Keys via headers or query parameters. If the validation logic does not enforce strict scope separation and binding to a particular client identity, an attacker may conduct stuffing by cycling through keys that appear valid but are actually orphaned or over-privileged. The unauthenticated attack surface that middleBrick scans targets such weaknesses by checking whether Api Key–protected endpoints exhibit insufficient rate limiting or data exposure, which are common precursors to successful credential stuffing in Hanami-based services.

Remediation focuses on ensuring Api Keys are treated as high-sensitivity credentials, validating them with strict policies, and avoiding anti-patterns that facilitate credential stuffing. Below are concrete, realistic code examples for a Hanami application that demonstrate secure handling of Api Keys.

1. Secure Api Key validation with header-based authentication

Instead of accepting keys via query parameters, use a custom header and enforce strong validation logic. This reduces the risk of keys being leaked in server logs or browser history.

# lib/app/actions/api/base.rb
module App
  module Actions
    module Api
      class Base < Hanami::Action
        private

        def authenticate_api_key!(request)
          provided_key = request.headers['X-API-Key']
          return halt 401, { error: 'Unauthorized' }.to_json unless provided_key

          # Use constant-time comparison to avoid timing attacks
          expected_key = ENV.fetch('API_KEY')
          unless secure_compare(provided_key, expected_key)
            halt 401, { error: 'Invalid API key' }.to_json
          end
        end

        def secure_compare(a, b)
          return false unless a.bytesize == b.bytesize
          l = a.unpack 'C*'
          res = 0
          b.each_byte { |byte| res |= byte ^ l.shift }
          res == 0
        end
      end
    end
  end
end

2. Rate limiting and scope-aware validation

Implement per-key rate limiting and ensure each key is bound to a defined scope, reducing the effectiveness of stuffing attempts that rely on rapid retries.

# lib/app/actions/api/items/show.rb
module App
  module Actions
    module Api
      class ItemsShow < Api::Base
        def handle(request)
          authenticate_api_key!(request)
          key_scope = lookup_key_scope(request.headers['X-API-Key'])
          halt 403, { error: 'Forbidden scope' }.to_json unless key_scope.include?('read:items')

          # proceed with safe data retrieval
          @item = ItemRepository.new.find(params[:id])
          @render 'items/show'
        end

        private

        def lookup_key_scope(key)
          # Map key to scopes, e.g., from a secure store or constant mapping
          case key
          when ENV.fetch('API_KEY_READ_ITEMS')
            ['read:items']
          when ENV.fetch('API_KEY_ADMIN')
            ['read:items', 'write:items', 'admin']
          else
            []
          end
        end
      end
    end
  end
end

3. Rotate keys and avoid hardcoded values

Do not embed keys directly in source code. Use environment variables and automate rotation. Below is an example of loading keys securely and ensuring they are not committed to version control.

# config/initializers/api_keys.rb
module ApiKeyConfig
  KEYS = {
    read_items:  ENV.fetch('HANAMI_API_KEY_READ_ITEMS'),
    write_items: ENV.fetch('HANAMI_API_KEY_WRITE_ITEMS'),
    admin:       ENV.fetch('HANAMI_API_KEY_ADMIN')
  }.freeze

  def self.for(scope)
    KEYS.fetch(scope)
  rescue KeyError
    raise 'Missing required API key configuration'
  end
end

4. MiddleBrick integration for continuous detection

Use the middleBrick CLI to scan your Hanami endpoints regularly, especially if you expose Api Key–protected routes. Run middlebrick scan <your-api-url> to obtain a security risk score and findings related to authentication, rate limiting, and data exposure. For teams managing many services, the Pro plan enables continuous monitoring and CI/CD integration, so new endpoints are automatically evaluated before deployment.