Giter Club home page Giter Club logo

gentle-force's Introduction

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.

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.

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.

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

Semantic versioning

This library follows semantic versioning.

See Symfony BC rules for basic information about what can be changed and what not in the API.

Running tests

Travis status

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.

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.

You can fix any code style issues using this command:

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

gentle-force's People

Contributors

mariusbalcytis avatar msprunskas avatar rmanibus avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

gentle-force's Issues

Other storages engines?

Hi, gentle-force looks good!
Will you add support for other storage engines than Redis?
Other libraries support doctrine cache, apc, and the likes.

update php requirmeents to allow php8

Hi, I heavily rely on your package to throttle all external api calls in my company and I cannot upgrade my projects to php8 because your composer.json does not allow it

Could you allow php8 anytime soon ?

Get "php_network_getaddresses: getaddrinfo failed" with "rediss" host

Hi!
I'm gettting this error:
"php_network_getaddresses: getaddrinfo failed: Name or service not known [tcp://rediss://authkey@ip:port:6379]"

When trying to set this value as "host" in the bundle config:
"rediss://authkey@ip:port"

Any idea how can well set this bundle to correctly handle TLS REDIS and the Auth Key?

Thanks!

Update composer to allow Predis 2

Hi!
It would be great to update the composer requirements to allow the 2.x version of predis/predis.
It seems there's no specific impact, according to Predis changelog but it still needs some tests.
Is it something you are working on? Thank you!

Consider replacing Travis CI with GitHub workflows

As title, since the Travis CI building changed their policy for the open source projects, it's not friendly for open source contributors from then on.

And I think we should consider migrating to the GitHub workflows at this time :).

If this issue is accepted by this repository owner, I will be happy to work on that.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.