maba/gentle-force

Library for limiting both brute-force attempts and ordinary requests, using leaky/token bucket algorithm, based on Redis

Gentle-force: brute-force, error and request rate limiting

This is a library for rate-limiting both brute-force attempts (like invalid credentials) and ordinary requests., _(*1)

Features

• can be used to limit brute-force attempts;
• can be used for request rate limiting;
• uses leaky / token bucket algorithm. This means that user does not have to wait for next hour or day - additional attempts are possible as time goes by. This also means that requests does not come in big batches when every hour starts;
• handles race-conditions. This is important for brute-force limiting. For example, if 1000 requests are issued at the same time to check same user's password, only configured number of attempts will be possible;
• can have several limits configured for single use-case (for example maximum of 100 requests per minute and 200 per hour);
• does not make assumptions about where and what it's used for - it can be used with user identifiers, API tokens, IP addresses or any other data to group usages.

Installation

composer require maba/gentle-force

Usage

<?php

use Maba\GentleForce\RateLimit\UsageRateLimit;
use Maba\GentleForce\RateLimitProvider;
use Maba\GentleForce\Throttler;
use Maba\GentleForce\Exception\RateLimitReachedException;

$rateLimitProvider = new RateLimitProvider();
$rateLimitProvider->registerRateLimits('credentials_error', [
    // allow 3 errors per hour; 2 additional errors if no errors were made during last hour
    (new UsageRateLimit(3, 3600))->setBucketedUsages(2),
    // allow 10 errors per day
    new UsageRateLimit(10, 3600 * 24),
]);
$rateLimitProvider->registerRateLimits('api_request', [
    // - allow 10 requests each minute;
    // - user can "save up" hour of usage if not using API.
    //   This means up to 610 requests at once, after that - 10 requests per minute,
    //   which could again save-up up to 610.
    (new UsageRateLimit(10, 60))->setBucketedPeriod(3600),
]);

$throttler = new Throttler(new \Predis\Client([
    'host' => '127.0.0.1',
]), $rateLimitProvider);

// rate limiting:
try {
    $result = $throttler->checkAndIncrease('api_request', $_SERVER['REMOTE_ADDR']);
    header('Requests-Available', $result->getUsagesAvailable());

} catch (RateLimitReachedException $exception) {
    header('Wait-For', $exception->getWaitForInSeconds(), 429);
    return;
}

// brute-force limiting:
try {
    // we must increase error count in-advance before even checking credentials
    // this avoids race-conditions with lots of requests
    $credentialsResult = $throttler->checkAndIncrease('credentials_error', $_POST['username']);
} catch (RateLimitReachedException $exception) {
    echo sprintf('Too much password tries for user. Please try after %s seconds', $exception->getWaitForInSeconds());
    return;
}

$credentialsValid = checkCredentials($_POST['username'], $_POST['password']);

if ($credentialsValid) {
    // as we've increased error count in advance, we need to decrease it if everything went fine
    $credentialsResult->decrease();

    // log user into system
}

Alternatives

Actually, there are quite many of them., _(*2)

Unfortunately, as some provide additional features (like different storage methods: file, memcached etc.), none were found with these criteria: - usable for brute-forcing (only on errors), not for all requests; - abstract, so that limiting by user, IP and other identifiers would be possible; - rate limiting algorithm that would not block for too long for a legitimate user; - free of race-conditions where actual limit would not work correctly on high load., _(*3)

Some of reviewed alternatives: RateLimitInterface, rate-limiter, LosRateLimit, Rate-limit, rate-limit, php-ratelimiter, tokenbucket, brute-force, LoginGateBundle, tresholds-governor, throttle, PeerjUserSecurityBundle, php-ratelimiter, RateLimitBundle, CybBotDetectBunble, CCDNUserSecurityBundle, limit-number-calls-bundle, rate-limiter-php, flaps, token-bucket, _(*4)

Semantic versioning

This library follows semantic versioning., _(*5)

See Symfony BC rules for basic information about what can be changed and what not in the API., _(*6)

Running tests

, _(*7)

Functional tests require Redis and several PHP extensions for forking, so that behaviour on high traffic could be tested. So, generally, it's easier to run them in docker., _(*8)

composer update
cd docker
docker-compose up -d
docker exec -it gentle_force_test_php vendor/bin/phpunit
docker-compose down

Contributing

Feel free to create issues and give pull requests., _(*9)

You can fix any code style issues using this command:, _(*10)

vendor/bin/php-cs-fixer fix --config=.php_cs