jgxvx/cilician

PHP Client for haveibeenpwned.com APIs

4.0.0 2023-12-25 14:17 UTC

Requires

• php: ^8.2|^8.3
• ext-json: *
• guzzlehttp/guzzle: ^6
• jgxvx/data-types: ^4.0.0
• psr/simple-cache: ^1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.8
• gase/php-cs-fixer: ^3.0
• kodus/mock-cache: ^1.0.1
• mockery/mockery: ^1.4
• phpstan/phpstan: ^1.6
• phpstan/phpstan-mockery: ^1.1
• phpstan/phpstan-phpunit: ^1.1
• phpunit/phpunit: ^10.3
• roave/security-advisories: dev-master

Suggests

• cache/simple-cache-bridge: A PSR-6 bridge to PSR-16. This will make any PSR-6 cache compatible with SimpleCache.
• jgxvx/cilician-runner: A command line interface for this library.

MIT

• Jürg Gutknecht

• security
• api client
• passwords
• privacy
• haveibeenpwned
• data breach
• gdpr
• pwnedpasswords
• cilician

README

Cilician is a PHP client for haveibeenpwned.com APIs (v3).

Installation

The recommended way to install Cilician is by using Composer:

$ composer require "jgxvx/cilician"

Getting Started

Ideally, the Cilician service is used to interact with the APIs. It is an abstraction layer for the specific API clients and will return convenient result objects or throw exceptions in case of failures.

Following the principle of dependency injection, the Cilician service is passed two API client objects and, optionally, a PSR-16 compliant cache implementation.

Both API clients expect a Guzzle HTTP client as their constructor parameter. The HaveIBeenPwnedApiClient also expects a Have I Been Pwned API key.

$hibpClient = new HaveIBeenPwnedApiClient(new \GuzzleHttp\Client(['base_uri' => HaveIBeenPwnedApiClient::BASE_URI]), 'your-api-key');
$ppClient   = new PwnedPasswordsApiClient(new \GuzzleHttp\Client(['base_uri' => PwnedPasswordsApiClient::BASE_URI]));
$cilician   = new Cilician($hibpClient, $ppClient);

Checking Passwords

To check if a password has appeared in a data breach:

$result = $cilician->checkPassword('12345678');

if ($result->isPwned()) {
    // Handle failure case...
    echo "The password you've chosen has appeared {$result->getCount()} times in data breaches. Do not use it.";
} else {
    // Handle success case...
    echo "All good!";
}

API Documentation

Getting All Breaches for an Account

To retrieve a list of all breaches a particular account has been involved in:

$result = $cilician->getBreachesForAccount('[e-mail]');

if ($result->isPwned()) {
    echo "Your account has appeared in the following breaches:" . PHP_EOL;
    
    foreach ($result->getBreaches() as $breach) {
        echo $breach->getName() . PHP_EOL;
    }
}

The getBreachesForAccount method returns an array of BreachModel instances -- value objects representing the API's breach model.

To narrow down the list, a filter object can be passed as a second argument:

$filter = new BreachFilter(['domain' => 'adobe.com']);
$result = $cilician->getBreachesForAccount('[e-mail]', $filter);

API Documentation

Getting All Breached Sites

To retrieve a list of all breached sites:

$result = $cilician->getBreachedSites();

foreach ($result->getBreaches() as $breach) {
    echo $breach->getName() . PHP_EOL;
}

To narrow down the list, a filter object can be passed to the getBreachedSites method:

$filter = new BreachFilter(['domain' => 'adobe.com']);
$result = $cilician->getBreachedSites($filter);

API Documentation

Getting a Single Breached Site

To retrieve a single breached site:

$result = $cilician->getBreachedSite('Adobe');

if ($result->isPwned()) {
    $breach = $result->getBreaches()[0]; // Safe, as isPwned() only returns true if there is at least one breach.
}

API Documentation

Getting All Available Data Classes

To retrieve all data classes:

$result = $cilician->getDataClasses();

foreach ($result->getDataClasses() as $dataClass) {
    echo $dataClass . PHP_EOL; // Data classes are strings
}

API Documentation

Getting All Pastes for an Account

To retrieve all pastes for an account:

$result = $cilician->getPastesForAccount('[e-mail]');

foreach ($result->getPastes() as $paste) {
    echo $paste->getName() . PHP_EOL;
}

The getPastesForAccount method returns an array of PasteModel instances -- value objects representing the API's paste model.

API Documentation

Filtering

When searching for breaches, a filter can specified to narrow down the search.

Currently, the breach filter supports two parameters:

• domain -- A domain name string. Default is null.
• includeUnverified -- Whether unverified breaches should be included. Default is false.

The parameters can either be passed to the filter's constructor as an array, or set by setter methods:

$filter = new BreachFilter(['domain' => 'adobe.com', 'includeUnverified' => true]);

// or

$filter = new BreachFilter();
$filter
    ->setDomain('adobe.com')
    ->setIncludeUnverified(true);

Caching

If the application uses a PSR-16 compliant caching system, the cache can be passed to Cilician as a third constructor parameter. Cilician will then automatically cache responses using the caching system's default TTL.

If a PSR-6 compliant cache is used, it can be converted to PSR-16 with php-cache/simple-cache-bridge or similar.

License

Cilician is open source software published under the MIT license. Please refer to the LICENSE file for further information.

Contributing

We appreciate your help! To contribute, please read the Contribution Guidelines and our Code of Conduct.