README

Modern PHP SDK for bad_ip – detect, block and report malicious IPs, TOR traffic, bots and bad queries.

🚀 Installation

composer require bad-ip/bad-ip-php

Requires PHP 8.1+.

⚡️ Quick Start

use BadIp\Config;
use BadIp\Client;
use BadIp\RequestContext;
use BadIp\Detector;

$config = new Config(token: 'your-api-token');
$client = new Client($config);
$detector = new Detector($client);

$ctx = RequestContext::fromGlobals();

if ($detector->isBlockedIp($ctx)) {
    die('Access denied by Bad IP');
}

🔥 Features

Detect and block malicious IPs
Detect and block TOR exit nodes
Basic bot detection
Guard against bad queries
Guard against brute force login attempts
Report suspicious activity back to Bad IP API
Fully extensible and testable

🧑‍💻 Usage Examples

Check if IP should be blocked

if ($detector->isBlockedIp($ctx)) {
    die('Blocked by Bad IP');
}

Block TOR traffic

use BadIp\TorGuard;

$torGuard = new TorGuard($detector);

try {
    $torGuard->enforce($ctx);
    echo "Welcome, not a TOR exit node!";
} catch (\RuntimeException $e) {
    http_response_code(403);
    echo $e->getMessage();
}

Login Guard

use BadIp\Reporter;
use BadIp\LoginGuard;

$reporter = new Reporter($client);
$guard = new LoginGuard($reporter, maxAttempts: 3);

$guard->check($ctx, $success); // $success = true or false

Query Guard

use BadIp\QueryGuard;

$queryGuard = new QueryGuard();
$queryGuard->allowQuery('/status');
$queryGuard->denyIp('1.2.3.4');

if (!$queryGuard->isAllowed($ctx)) {
    $reporter->reportQuery($ctx);
}

Report 404

$reporter->report404($ctx);

Manual report

$client->report('8.8.8.8', 'manual_block', 'my-app');

🧪 Testing

composer test

We recommend Pest or PHPUnit with coverage.

🤝 Contributing

Contributions are welcome! Please see the contributing guide.

📄 License

The MIT License (MIT). See LICENSE for more information.

bad-ip / bad-ip-php

Maintainers

Details