abuseipdb/laravel

包用于轻松集成 AbuseIPDB API 与 Laravel。

1.0.7 2024-07-26 21:06 UTC

This package is auto-updated.

Last update: 2024-09-26 21:33:23 UTC


README

包用于轻松将 AbuseIPDB API 集成到您的 Laravel 项目中。

安装

使用 Composer 安装

composer require abuseipdb/laravel

ABUSEIPDB_API_KEY 添加到您的 .env 文件中。一旦您注册了账户,您可以从 AbuseIPDB 网站 获取一个免费密钥。

ABUSEIPDB_API_KEY=your_key

记住,AbuseIPDB API 密钥应像私钥一样处理 -- 不要让它们公开可访问!

为了您应用的安全性,您的 .env 文件永远不应公开或提交到源代码控制。

用法

使用主包函数

包的主要函数位于 Abuseipdb\AbuseIPDBLaravel.php。访问这些函数的推荐方式是通过包含的 facade。要使用它,请使用

use AbuseIPDB\Facades\AbuseIPDB;

然后可以调用这些函数(非详尽列表)

$checkResponse = AbuseIPDB::check('127.0.0.1');
$reportResponse = AbuseIPDB::report('127.0.0.1', categories: [18, 22]);
$reportsResponse = AbuseIPDB::reports('127.0.0.1', maxAgeInDays:10);
$blacklistResponse = AbuseIPDB::blacklist(limit: 1000);

这是访问 AbuseIPDB 包功能的首选方法。

报告 SuspiciousOperationException 的快速入门

此包支持自动报告 Laravel 项目中 Symfony 的 SuspiciousOperationException 实例。要使用此功能,请在项目的 app\Exceptions\Handler.php 中包含以下代码

在文件顶部

use Symfony\Component\HttpFoundation\Exception\SuspiciousOperationException;
use AbuseIPDB\AbuseIPDBExceptionReporter;

在 Handler 的 register() 函数内部

 $this->stopIgnoring(SuspiciousOperationException::class);

在注册函数的 $this->reportable(function (Throwable $e) {} 内部

if ($e instanceof SuspiciousOperationException) {
    AbuseIPDBExceptionReporter::reportSuspiciousOperationException();
}

如果您的 Handler 的 register() 不包含上述 $this->reportable

 $this->reportable(function (Throwable $e) {
    if ($e instanceof SuspiciousOperationException) {
        AbuseIPDBExceptionReporter::reportSuspiciousOperationException();
    }    
});

现在,当抛出 SuspiciousOperationException 时,您的项目将自动报告给 AbuseIPDB。

主要函数

此包实现了与 AbuseIPDB API 端点的简单交互函数。这些函数位于 AbuseIPDBLaravel.php 中,可以通过 AbuseIPDB facade 静态调用。

父响应对象

所有自定义响应对象都扩展了自定义的 AbuseResponse 类,该类从响应中提取某些头部并使它们可以通过程序访问。见下文

use AbuseIPDB\ResponseObjects\AbuseResponse; 
$response = new AbuseResponse($httpResponse);

$response->x_ratelimit_limit
$response->x_ratelimit_remaining;
$response->content_type;
$response->cache_control;
$response->cf_cache_status;

当处理调用具有自定义响应的端点的响应时,在请求代码的顶部包含以下内容

use AbuseIPDB\ResponseObjects;

然后可以按照以下方式引用这些对象类型

ResponseObjects\AbuseResponse
ResponseObjects\CheckResponse
ResponseObjects\ReportResponse

等等。

特定端点的函数

截至当前版本,此包提供了访问所有公共 APIv2 端点的方法。当对这些端点发出请求时,将返回特定端点的响应对象,这些对象扩展了 Illuminate\Http\Client\Response 对象。如果发生错误,将抛出自定义异常。请参阅我们的 APIv2 文档,以获取每个端点返回值的列表。

check

check() 方法向 AbuseIPDB API 的 check 端点 发出请求。其签名是

public function check(string $ipAddress, int $maxAgeInDays = 30, bool $verbose = false): ResponseObjects\CheckResponse

string $ipAddress 要检查的 IP 地址

int $maxAgeInDays 要返回的报告的最大年龄(1-365),默认为 30

bool $verbose 是否包含详细信息(报告),默认为 false

report

report() 方法向 AbuseIPDB API 的 report 端点 发出请求。其签名是

public function report(string $ip, array|int $categories, string $comment = null, DateTime $timestamp = null): ResponseObjects\ReportResponse

string $ip 要报告的 IP 地址

array|int $categories 要报告IP地址的一个或多个分类

string|null $comment 可选的评论,可以包括报告,例如攻击的日志指标

DateTime|null $timestamp 可选的时间戳,用于报告攻击发生的时间

reports

reports() 方法会对AbuseIPDB API的 reports endpoint 发送请求。它的签名是

public function reports(string $ipAddress, int $maxAgeInDays = 30, int $page = 1, int $perPage = 25): ResponseObjects\ReportsPaginatedResponse

string $ipAddress 要获取报告的IP地址

int $maxAgeInDays 要返回的报告的最大年龄(1-365),默认为 30

int $page 要获取的分页响应的页码

int $perPage 每页要获取的报告数量

blacklist

blacklist() 方法会对AbuseIPDB API的 blacklist endpoint 发送请求。它的签名是

public function blacklist(int $confidenceMinimum = 100, int $limit = 10000, bool $plaintext = false, $onlyCountries = [], $exceptCountries = [], int $ipVersion = null): ResponseObjects\BlacklistResponse|ResponseObjects\BlacklistPlaintextResponse

int $confidenceMinimum 包含IP在黑名单中的最小置信度分数

int $limit 返回的黑名单IP的最大数量,默认为10000

bool $plaintext 是否以纯文本形式返回黑名单(IP的纯数组),默认为false

array $onlyCountries 仅包括这些国家的IP(使用两位字母的国家代码)

array $exceptCountries 排除这些国家的IP(使用两位字母的国家代码)

int|null $ipVersion 要返回的IP版本(4或6),默认为两者都返回

checkBlock

checkBlock() 方法会对AbuseIPDB API的 check-block endpoint 发送请求。它的签名是

public function checkBlock(string $network, int $maxAgeInDays = 30): ResponseObjects\CheckBlockResponse

string $network 以CIDR表示法检查的网络(例如,127.0.0.1/28)

int $maxAgeInDays 要返回的报告的最大年龄(1-365),默认为 30

bulkReport

bulkReport() 方法会对AbuseIPDB API的 bulk-report endpoint 发送请求。它的签名是

public function bulkReport(string $csvFileContents): ResponseObjects\BulkReportResponse

string $csvFileContents 要上传的csv文件内容

clearAddress

clearAddress() 方法会对AbuseIPDB API的 clear-address endpoint 发送请求。它的签名是

public function clearAddress(string $ipAddress): ResponseObjects\ClearAddressResponse

string $ipAddress 要清除报告的IP地址

Exceptions

在出现错误的情况下,此包将从 Abuseipdb\Exceptions 命名空间抛出异常。这些异常包括以下内容

InvalidParameterException   // Parameter passed in was invalid for the API.
MissingAPIKeyException  // Your API key in your .env file was not found or invalid.
PaymentRequiredException    // 402 error was thrown by API, indicating feature needs a higher subscription.
TooManyRequestsException    // 429 error was thrown by API, indicating request limit has been exceeded.
UnprocessableContentException   // 422 error was thrown by API, indicating request parameters could not be handled, either missing or incorrect.
UnconventionalErrorException    // Error code other than 402, 422, or 429 was returned by the API.

如果您想处理这些异常

use AbuseIPDB\Exceptions; 

try {
    /* some code */
}
catch(Throwable $e) {
    if($e instanceof Exceptions\TooManyRequestsException) {
        //429 was thrown, do something to address issue
    }
}

Testing (for package developers)

如果使用提供的测试套件,请注意,测试将每15分钟无错误运行一次。AbuseIPDB API会在15分钟内对同一IP地址进行多次报告时抛出错误,因此任何报告端点测试都会抛出错误。不使用报告端点的任何测试仍将在没有任何等待期的情况下正常工作。

要为测试添加您的API密钥,请将 .env.testing.example 文件复制到 .env.testing 并填写 ABUSEIPDB_API_KEYBAD_IP_TO_TEST 变量(您可以从AbuseIPDB网站获取,确保它有足够的报告)。ABUSEIPDB_API_BASE_URL 可以保持不变。