Suspicious Credentials Check

This module provides functionality of checking if the credentials being used for login attempt have been compromised in a data breach, in other words ‘pwned’, hence the module’s name.

The credentials typed by the user are transformed into hashes and checked against presence in a local database containing hashes of credentials that have been leaked in a known data breach.

The check is done completely locally, no data is sent outside your application.

Since it is performed on hashes of credentials, not original values, the risk of a password leak is not increased by using this feature.

How Does It Work

The functionality operates on hashes of credentials and uses Bloom filter for doing the check.

The Bloom filter implementation being used offers great performance and can be applied on hot paths, you can read detailed documentation here or see the source code here.

Usage

Data Source

Before using the filter it must be populated with leaked credentials data to be checked against. For this purpose we provide convenient command line utility, bloom-tool, which allows generating, manipulating and testing Bloom filters.

As a data source you can use pwned passwords lists available at haveibeenpwned.com or similar websites, or can be obtained from any credentials breach data you have access to.

For information about transforming the data into Bloom filter please refer to bloom-tool documentation.

Bloom filter is represented by two files:

• filter_name.bloom - metadata file containing filter parameters,
• filter_name.bloom-data - data set file.

Installation

Pwned Check Nixer plugin is distributed through Maven Central. It requires dependency to Core Nixer plugin as well.

dependencies {
    implementation("io.nixer:nixer-plugin-core:0.1.1.3")
    implementation("io.nixer:nixer-plugin-pwned-check:0.1.1.3")
}

Configuration

In order to enable the functionality the following properties are to be set:

nixer.pwned.check.enabled=true
nixer.pwned.check.pwnedFilePath=classpath:PWNED_DATABASE_DIRECTORY/filter_name.bloom

where PWNED_DATABASE_DIRECTORY is expected to contain both Bloom filter files, filter_name.bloom and filter_name.bloom-data.

Results

Pwned check results are written into Spring Boot application metrics, under pwned_check metric name, from where they can be utilized for any mitigation actions.