README

BrutalForce is a lightweight PHP library that helps detect suspicious request cadence per client IP using session-backed timing.

Requirements

PHP 8.2+

Installation

composer require rmanara/brutalforce

Quick Start

<?php

require_once __DIR__ . '/vendor/autoload.php';

use BrutalForce\Initiate;

if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}

$guard = new Initiate();

// Text label based on current cadence profile
$rate = $guard->Rate();

// Numeric score (rounded to 3 decimals)
$score = $guard->predict();

if ($score <= 0.5) {
    http_response_code(429);
    exit('Too many requests');
}

Public API

Initiate::Rate(): string returns the current risk label.
Initiate::predict(): float returns the current average timing score.
Initiate::decision(): array returns blocking decision payload.
Initiate::isBlocked(): bool checks if the client is currently locked.
Initiate::lockRemaining(): int returns seconds left in lockout.
Initiate::policy(): array returns effective policy values.
Initiate::withRedis(object $redis, array $policy = [], array $options = []): Initiate creates an instance backed by Redis.

Blocking Example

$decision = $guard->decision();

if ($decision['blocked']) {
    header('Retry-After: ' . $decision['retry_after']);
    http_response_code(429);
    exit('Too many requests');
}

Policy Configuration

You can configure protection policy per instance:

$guard = new Initiate([
    'threshold' => 0.5,
    'violation_limit' => 5,
    'lock_steps' => [60, 120, 300],
]);

Or using environment variables:

export BRUTALFORCE_THRESHOLD=0.5
export BRUTALFORCE_VIOLATIONS=5
export BRUTALFORCE_LOCK_STEPS=60,120,300

Progressive lockouts increase duration for repeated offenders in the same session.

Policy precedence is: constructor overrides > environment variables > built-in defaults.

Advanced Runtime Options

The second constructor argument accepts runtime integrations:

$guard = new Initiate(
    ['threshold' => 0.5],
    [
        // Session key namespacing/versioning
        'session_namespace' => 'brutalforce',
        'session_version' => 'v1',

        // Trusted proxy strategy
        'trusted_proxies' => ['127.0.0.1'],
        'forwarded_headers' => ['HTTP_X_FORWARDED_FOR', 'HTTP_X_REAL_IP'],

        // Optional distributed backend (phpredis client instance)
        // 'redis' => $redis,
        // 'redis_prefix' => 'brutalforce:v1',

        // Optional deterministic/testing clock (ClockInterface)
        // 'clock' => $clock,
    ]
);

Redis Quick Start

$redis = new Redis();
$redis->connect('127.0.0.1', 6379);

$guard = Initiate::withRedis(
    $redis,
    ['threshold' => 0.5, 'violation_limit' => 5, 'lock_steps' => [60, 120, 300]],
    ['redis_prefix' => 'brutalforce:v1']
);

See examples/redis.php for a complete runnable example.

Rate Labels

The library maps the score to one of the following labels:

VERY LOW
LOW
MEDIUM
MEDIUM HIGH
HIGH
VERY HIGH

Running Tests

vendor/bin/phpunit

Run Simulations

Use the CLI runner to simulate burst and delayed request patterns:

composer simulate

Optional examples:

php scripts/simulate.php --scenario=delay-2s
php scripts/simulate.php --format=json

Redis-backed simulation (local in-memory Redis stub):

composer simulate:redis
php scripts/simulate_redis.php --format=json

Migration Notes (legacy 5.6-era to modern PHP)

Runtime target is now PHP 8.2+.
Core internals use strict return types and safer session access.
Learning history is bounded per IP to avoid unbounded session growth.
Rate() remains backward compatible.

Full Documentation

For behavior details, integration guidance, and upgrade notes, see:

docs/Documentation.md

Project

Package: rmanara/brutalforce
Repository: https://github.com/rodrigomanara/brutalforce
License: MIT

rmanara / brutalforce

Maintainers

Package info

Statistics

Security