Arp Spoofing in Hanami with Mutual Tls

Arp spoofing is a Layer 2 attack where an adversary sends falsified ARP messages to associate their MAC address with the IP of a legitimate host, such as a Hanami service or a database endpoint. In a Hanami application that relies on mutual TLS (mTLS) for client authentication, an attacker who successfully spoofs the gateway or another service IP can intercept traffic that would otherwise be protected by mTLS. The presence of mTLS does not prevent Layer 2 manipulation; it only ensures that presented certificates are validated. If an attacker stays on the same broadcast domain and tricks the Hanami host into sending frames to the attacker’s MAC, the attacker can terminate or manipulate the TLS session in a man-in-the-middle fashion, provided they can also handle or terminate TLS using compromised keys or present a valid cert if the server does not enforce strict client cert validation.

The combination of Hanami (a Ruby web framework) and mutual TLS can expose risks when deployment topologies do not account for network-level threats. For example, in a Kubernetes or containerized setup, if a Hanami pod’s network policy is misconfigured or if an adjacent pod is compromised, ARP spoofing becomes feasible. The Hanami app may trust the source IP or the identity encoded in the client certificate, but ARP spoofing bypasses IP-based trust by altering layer 2 mappings. This can lead to session hijacking, where an attacker captures or alters mTLS-encrypted requests between services. Because Hanami typically runs behind a reverse proxy or load balancer, attackers might target the node’s ARP cache to reroute traffic before it reaches the mTLS verification layer, effectively downgrading the security of an otherwise encrypted channel.

In practice, middleBrick scans can detect conditions that make ARP spoofing more feasible, such as missing network segmentation or overly permissive pod communication rules, by correlating runtime findings with the OpenAPI/Swagger spec analysis. Even though mTLS is enforced, an unauthenticated scan might uncover endpoints that do not require client certificates or that accept connections from unexpected network paths. These findings highlight where ARP spoofing could be leveraged to bypass intended trust boundaries. Remediation involves ensuring strict mTLS enforcement, validating client certificates on every request, and hardening the network layer to prevent ARP manipulation.

To mitigate ARP spoofing risks in Hanami with mutual TLS, focus on making the application resilient to layer 2 attacks by enforcing mTLS strictly and reducing the impact of a compromised network path. Below are concrete code examples for Hanami applications using common Ruby TLS libraries and Rack middleware.

Enforcing Mutual TLS in Hanami with SSLClientCert

Ensure that Hanami validates client certificates on every request. Use the ssl_client_cert from Rack and reject requests without a valid cert. Configure your reverse proxy or load balancer to terminate TLS and forward the client certificate in headers if needed, but always validate in Hanami.

# config/boot.rb or an initializer
require 'openssl'

module Security
  CERT_STORE = OpenSSL::X509::Store.new
  CERT_STORE.add_file('path/to/ca-bundle.pem')

  def self.verify_client_cert(cert)
    return false unless cert
    store = CERT_STORE
    cert.verify(store)
  rescue OpenSSL::X509::CertificateError
    false
  end
end

In your Hanami controller, you can add a before action to enforce client certificate presence and validity:

# app/controllers/application_controller.rb
class ApplicationController < Hanami::Controller
  before :verify_mtls

  private

  def verify_mtls
    cert = request.env['SSL_CLIENT_CERT']
    unless Security.verify_client_cert(cert)
      halt 403, { error: 'invalid_client_cert' }.to_json
    end
  end
end

If you use a reverse proxy (e.g., NGINX, HAProxy) in front of Hanami, configure it to require client certificates and forward the verified cert to the app via headers. Example NGINX configuration snippet:

# NGINX configuration
server {
    listen 443 ssl;
    ssl_certificate /etc/ssl/certs/server.crt;
    ssl_certificate_key /etc/ssl/private/server.key;

    ssl_verify_client on;
    ssl_client_certificate /etc/ssl/certs/ca-bundle.pem;

    location / {
        proxy_pass http://hanami_app;
        proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
        # Ensure no fallback to non-TLS backends
    }
}

For containerized deployments, apply network policies to reduce ARP spoofing opportunities. Use Kubernetes NetworkPolicy to restrict pod-to-pod communication to only required paths, and ensure that Hanami pods do not accept traffic from unexpected sources. While this does not replace mTLS, it limits the attack surface available for ARP manipulation.

Finally, rotate certificates regularly and use short-lived client certificates where possible. Combine this with continuous monitoring of security scores by using the middleBrick Pro plan for ongoing scans and alerts, and integrate the GitHub Action to fail builds if risk scores degrade. The MCP Server can also be used to scan APIs directly from your IDE, helping you verify that mTLS configurations remain intact during development.