abuseipdb / laravel
包用于轻松集成 AbuseIPDB API 与 Laravel。
Requires
- laravel/framework: ^10.0||^11.0
Requires (Dev)
- laravel/pint: ^1.13
- orchestra/testbench: ^8.0||^9.0
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_KEY
和 BAD_IP_TO_TEST
变量(您可以从AbuseIPDB网站获取,确保它有足够的报告)。ABUSEIPDB_API_BASE_URL
可以保持不变。