Replay Attack in Grape with Mutual Tls

A replay attack in the context of a Grape API protected by Mutual Transport Layer Security (mTLS) occurs when an adversary intercepts a valid client request—complete with client certificate authentication and all headers—and retransmits it later to produce an unauthorized effect. Even though mTLS provides strong server-side assurance of client identity (the server verifies the client certificate chain, and optionally the client can verify the server), it does not inherently prevent an attacker from replaying a captured request. The vulnerability arises because mTLS authenticates the request at a point in time but does not by itself enforce request uniqueness or freshness.

Consider a payment endpoint POST /payments that initiates a transfer based on parameters such as account_id and amount. With mTLS, the client presents a certificate that the server validates successfully. If the request is not protected against replay—via nonce, timestamp, or idempotency key—an attacker who observes and stores this request can simply retransmit it with the same mTLS client certificate. The server will again accept it as coming from a trusted client, leading to duplicate payments or other business logic abuse. In Grape, this is a business-logic and session handling issue rather than a flaw in TLS itself, but the presence of mTLS can create a false sense of security if developers assume transport authentication equals request integrity.

Replay risks are especially relevant when mTLS is used without additional application-level protections and when requests have side effects. Attack surfaces expand in distributed setups where requests traverse multiple proxies or load balancers that may terminate TLS; if request replay protection is implemented only at the application layer and not consistently across all paths, replay becomes feasible. The interplay between mTLS’s strong identity guarantees and the absence of replay countermeasures means attackers can focus on capturing and reusing authenticated requests, making explicit replay defenses essential.

To mitigate replay in Grape with mTLS, combine robust mTLS configuration with application-level freshness guarantees. Below is a concrete Grape setup with mTLS enabled and a replay-safe endpoint.

# config/initializers/api.rb
require 'securerandom'
require 'openssl'

class ReplayProtection
  def initialize(store = Concurrent::Hash.new)
    @store = store
  end

  def verify(request)
    nonce = request.headers['X-Request-Nonce']
    timestamp = request.headers['X-Request-Timestamp']
    return [false, 'Missing replay headers'] unless nonce && timestamp
    return [false, 'Stale timestamp'] if (Time.now.to_i - Integer(timestamp)).abs > 30
    return [false, 'Replay detected'] if @store[nonce]
    @store[nonce] = true
    [true, nil]
  end
end

class ProtectedAPI < Grape::API
  before { header['X-Request-Nonce'] = SecureRandom.uuid }
  before { header['X-Request-Timestamp'] = Time.now.to_i.to_s }

  helpers do
    def verify_replay
      checker = ReplayProtection.new(ENV.fetch('NONCE_STORE', Concurrent::Hash.new))
      valid, message = checker.call(request)
      error!('Forbidden', 403) unless valid
    end
  end

  resource :payments do
    desc 'Initiate a payment (mTLS + replay protection)'
    before { verify_replay }
    params do
      requires :account_id, type: Integer
      requires :amount, type: Float
    end
    post do
      # business logic
      { status: 'ok', account_id: params[:account_id], amount: params[:amount] }
    end
  end
end

On the server side, configure your TLS termination to request and validate client certificates. In a typical Ruby/TLS setup (e.g., using Puma with SSL), you would enforce client verification so that only clients with trusted certificates can reach the Grape app. The example above adds per-request nonces and timestamps checked server-side; this works with mTLS because the TLS layer already ensures the client possesses the correct private key corresponding to a trusted certificate. For production, store nonces in a distributed, TTL-backed store (e.g., Redis) instead of a local Concurrent::Hash to handle multi-instance deployments and to avoid memory growth.

Additionally, include an idempotency key header (e.g., Idempotency-Key) for operations with side effects, and enforce uniqueness server-side within a reasonable window. Combine these with mTLS to ensure that even if a request is replayed with a valid client certificate, the server will reject it if the nonce/timestamp or idempotency key has already been processed.

Finally, document and test these protections explicitly; mTLS handles transport authentication, but replay defenses must be implemented at the application level. Tools like middleBrick can help validate that your Grape endpoints include appropriate freshness mechanisms and that mTLS is correctly enforced in runtime scans.