Skip to content

ipscrub: IP address anonymizer module for NGINX

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-ipscrub provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-ipscrub

Warning

This module is not yet published as nginx-module-ipscrub in the APT repositories. Stay tuned, or email [email protected] to request it.

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.