Skip to content

ipscrub: IP address anonymizer module for NGINX

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm 
yum -y install nginx-module-ipscrub

dnf -y install https://extras.getpagespeed.com/release-latest.rpm 
dnf -y install nginx-module-ipscrub

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_ipscrub_module.so;

This document describes nginx-module-ipscrub v1.0.1 released on May 29 2018.

ipscrub is an IP address anonymizer for nginx log files. It's an nginx module that generates an IP-based hash. You can use this hash to link requests from the same source, without identifying your users by IP address.

Screenshot of nginx logs when using ipscrub

Security Model

  1. On initialization, and again every PERIOD, generate salt using 128bits from arc4random_buf().
  2. On each request, generate masked IP address as HASH(salt ++ IP address).
  3. Log masked IP address.

ipscrub uses arc4random to generate random nonces (see Theo de Raat's talk on arc4random for a great overview). On Linux this requires installing libbsd (package libbsd-dev on Ubuntu/Debian).

ALSO NOTE: the generated hash WILL change on each PERIOD transition, so you will only have continuity within each PERIOD. But because users can transition between networks at any time (e.g. wifi -> cellular), you'd have this type of issue even if you were storing raw IPs.

Threat Model

  1. Government presents you with an IP address and demands identification of user corresponding to that address.
  2. Government identifies a user e.g. by email address, and demands IP address they had at some point in time.

In threat scenario (1), the goal is to compute the masked IP corresponding to a target IP address. This will only be possible if the demand is made before the end of the current PERIOD.

Scenario (2) is defended against because the server operator does not know the salt, and cannot infer it based on the request timestamp, because the salt is generated from a nonce that is only stored in memory. The server operator would have to be an accomplice in this case, but that is more simply accomplished by the server operator just recording the unmasked IP. So this security/threat model does not defend against a malicious server operator, but that is not the point. It does defend against an honest server operator being compelled in threat scenarios (1) and (2).

Usage

Configuration

In your nginx.conf,

  1. At the top-level, load the module by adding the line load_module ngx_ipscrub_module.so; (NOTE: only if you built as a dynamic module).
  2. Set ipscrub_period_seconds <NUM SECONDS PER PERIOD>; (optional).
  3. In your log_format directives, replace $remote_addr with $remote_addr_ipscrub.
  4. Reload your nginx config.

NOTE: nginx may still leak IP addresses in the error log. If this is a concern, disable error logging or wipe the log regularly.

Running Tests

make test

Changelog

  • 1.0.1 fixed vulnerability to unmasking hashed IPs (thanks to @marcan)
  • 1.0.0 initial release

GDPR

GDPR goes into effect on May 25, 2018. It legislates the handling of personal data about your users, including IP addresses.

From https://www.eugdpr.org/gdpr-faqs.html:

What constitutes personal data?

Any information related to a natural person or ‘Data Subject’, that can be used to directly or indirectly identify the person. It can be anything from a name, a photo, [...], or a computer IP address.

The hashes generated by ipscrub let you correlate nginx log entries by IP address, without actually storing IP addresses, reducing your GDPR surface area.

YAGNI

Why are you logging IP addresses anyway? You Ain't Gonna Need It. If you want geolocation, just use MaxMind's GeoIP module in conjunction with ipscrub.

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-ipscrub.