概览 — 这个功能做什么
IP 信誉查询是一项通用功能：在安全领域的任何位置点击可疑的来源 IP（src_ip），服务器就会代你查询 AbuseIPDB 的威胁情报，并把结果渲染到应用内弹窗中。你无需离开控制台 — 就在研判现场判断「这个 IP 有多恶名昭著」。
主要特点：
- 纯查询（只读）。 该功能只调用 AbuseIPDB 的
/api/v2/check。它不会向外部举报或公开该 IP — 对外举报（国际协作）属于另行推迟的响应阶段。 - 滥用可信度 0–100 仪表，外加举报数、去重后的举报者数、用途类型、ISP、国家/地区、域名、Tor/白名单标记以及最近的举报历史 — 全部经过归一化处理。
- 多密钥轮询。 在 信誉 API 中登记的 AbuseIPDB 密钥池会被依次消费；遇到 429（配额超限）或 401/403（密钥问题）时，服务会自动切换到下一个密钥（配额池化）。
- 按 IP 缓存 1 小时。 为保护免费版每天 1000 次请求的配额，一小时内重复查询同一个 IP 会返回缓存的结果。
- 共享混入（mixin）。 威胁、检测、安全概览 和 封禁列表 都复用同一个弹窗组件。
本文的实时按钮会打开安全领域（
/security）。信誉查询不是独立页面 — 它是一个共享弹窗，在安全界面点击 IP 旁边的盾牌放大镜符号（.infr-ipsym）或 [查询信誉] 按钮时出现。
何时使用
- 在 威胁 中研判高危攻击者 IP — 它是真正的恶意来源，还是已知的扫描器/僵尸网络？
- 判定 检测 中的 JA3 违规者或 Kitsune 异常 IP 是否构成真实威胁。
- 在 封禁列表与信誉 中执行封禁/解除之前，交叉核对目标在外部的信誉。
- 从 安全概览 的高危威胁 IP / JA3 违规者面板快速浏览 IP 信誉。
界面布局
弹窗（security/partials/abuse-modal.blade.php）会根据查询结果，以三种状态之一进行渲染。
成功 — 信誉卡片
| 区域 | 内容 |
|---|---|
| 可信度仪表 | 0–100 的圆锥渐变环形图 + 居中的 score%。色调随分数变化（参见判定表）。 |
| 判定标签 | No reports（无举报）/ Low risk（低风险）/ Elevated（风险偏高）/ High risk（高风险） |
| 标记 | Tor node（is_tor）· Whitelisted（is_whitelisted）徽章 |
| 两个大数值 | 举报总数 · 去重后的举报者数 |
| 元信息 | 国家/地区 · 用途类型 · ISP · 域名 · 最近举报时间 |
| 最近的举报 | 最多 6 条 — 类别标签 + 举报者所在国家/地区 + 时间 + 备注（最多 200 字符） |
| 查询时间戳 | 服务器执行查询的时间（checked_at） |
可信度分数 → 判定色调
| 分数 | 判定 | 色调 | 含义 |
|---|---|---|---|
| 0 | 无举报（clean） | good | 该时间范围内没有滥用举报 |
| 1–24 | 低风险（low） | info | 少量举报 — 仅供参考 |
| 25–74 | 风险偏高（elevated） | warn | 存在值得重视的滥用历史 |
| 75–100 | 高风险（high） | crit | 强烈的恶意信号 |
未配置 / 失败状态
- 未配置密钥：显示密钥告警图标和提示。请使用底部的 [打开 AbuseIPDB] 按钮直接到外部站点查看。
- 查询失败：配额超限、网络错误等。请稍后重试，或退回到外部链接。
底部操作按钮
| 按钮 | 动作 |
|---|---|
| 复制 IP | 把 IP 复制到剪贴板（在非安全上下文中回退到 execCommand） |
| IP 查询 | 跳转到 IP 连接（/infra/traffic/ips?src_ip=…） |
| 打开 AbuseIPDB | 在新标签页打开外部的 abuseipdb.com/check/{ip} |
| 加入封禁列表 | 以深层链接预填 封禁列表（/security/blocklist?add={ip}） |
使用方法
- 在安全界面（威胁、检测、概览、封禁列表）中，点击 IP 旁边的盾牌放大镜符号或 [查询信誉] 按钮。
- 弹窗随加载动画打开，前端向服务器请求查询：
GET /security/ip-reputation?ip=203.0.113.10
- 服务器严格校验该 IP（
filter_var FILTER_VALIDATE_IP），随后通过 AbuseIpdbService 查询并返回归一化后的 JSON。 - 查看仪表、数值和最近的举报。按需使用底部按钮复制、追踪或封禁。
响应结构（归一化后）
查询成功时，服务器返回供弹窗使用的 JSON：
{
"ok": true,
"configured": true,
"ip": "203.0.113.10",
"score": 84,
"reports": 128,
"distinct_users": 41,
"country": "CN",
"usage": "Data Center/Web Hosting/Transit",
"isp": "Example Hosting Ltd",
"domain": "example-host.net",
"is_tor": false,
"is_whitelisted": false,
"last_reported": "2026-08-12T22:14:07+00:00",
"recent": [
{ "at": "2026-08-12T22:14:07+00:00", "country": "US", "categories": [18, 22], "comment": "SSH brute-force" }
],
"checked_at": "2026-08-13 09:31:20",
"external_url": "https://www.abuseipdb.com/check/203.0.113.10"
}
优雅失败时：
{ "ok": false, "configured": false, "external_url": "https://www.abuseipdb.com/check/203.0.113.10" }
| 字段 | 来源（AbuseIPDB） | 含义 |
|---|---|---|
score |
abuseConfidenceScore | 滥用可信度 0–100 |
reports |
totalReports | 举报总数 |
distinct_users |
numDistinctUsers | 去重后的举报者数量 |
country |
countryCode | 国家/地区代码 |
usage |
usageType | 用途（数据中心 / ISP / …） |
isp / domain |
isp / domain | ISP · 域名 |
is_tor |
isTor | Tor 出口节点标记 |
is_whitelisted |
isWhitelisted | AbuseIPDB 白名单 |
last_reported |
lastReportedAt | 最近举报时间 |
recent[] |
reports[] | 最近的举报（最多 6 条，备注截断到 200 字符） |
举报类别（1–23）
recent[].categories 是数字 ID 的数组。弹窗通过 security.abuse.cat 语言映射渲染标签。
| ID | 标签 | ID | 标签 | ID | 标签 |
|---|---|---|---|---|---|
| 1 | DNS 遭入侵 | 9 | 开放代理 | 17 | 身份伪造 |
| 2 | DNS 投毒 | 10 | Web 垃圾信息 | 18 | 暴力破解 |
| 3 | 欺诈订单 | 11 | 垃圾邮件 | 19 | 恶意 Web 爬虫 |
| 4 | DDoS 攻击 | 12 | 博客垃圾信息 | 20 | 被入侵的主机 |
| 5 | FTP 暴力破解 | 13 | VPN IP | 21 | Web 应用攻击 |
| 6 | Ping of Death | 14 | 端口扫描 | 22 | SSH |
| 7 | 钓鱼 | 15 | 黑客攻击 | 23 | 针对 IoT |
| 8 | VoIP 欺诈 | 16 | SQL 注入 |
数据来源
该功能不新建任何表。 它完全依靠一次外部 API 调用 + 一份密钥登记表 + 一层缓存来工作。
| 组件 | 说明 |
|---|---|
| AbuseIPDB API | https://api.abuseipdb.com/api/v2/check（verbose=1，maxAgeInDays＝提供方设定值·默认 90）。超时 8 秒。 |
AbuseIpdbService |
负责查询、归一化、缓存，并消费轮换的密钥。check($ip)（带缓存）· checkWithKey()（管理员单密钥测试，不带缓存）。 |
ReputationProviderService |
密钥池的唯一事实来源。按 priority·id 排序提供启用的 infr_reputation_provider 行，缓存 30 秒；rotated() 用于轮询；若一个都没登记则回退到 .env ABUSEIPDB_KEY。 |
infr_reputation_provider |
AbuseIPDB 多密钥登记表（迁移 000733）。密钥以 secret_enc（Crypt，只写）存储 — 绝不返回给浏览器。在 信誉 API 中管理。 |
| 缓存 | Cache 键为 infr:sec:abuse:{ip}，TTL 3600 秒（1 小时）。轮询计数器是 infr:reputation:rr。 |
config/services.php |
abuseipdb.key（＝.env ABUSEIPDB_KEY）· abuseipdb.max_age_days（默认 90）。仅在没有任何已登记密钥时作为回退。 |
密钥轮换 / 故障切换流程
check(ip)
├ cache hit? → return
└ miss → iterate providers.rotated()
key#1 → 200? → normalize·cache·return
→ 429/401/403 → fail over to next key (secret never printed)
key#2 → …
all fail → { ok:false, error:"http_429"|"unreachable" }
登记多个免费版密钥，它们的配额就会汇聚成池。当某个密钥用尽当日配额并返回 429 时，服务会自动前进到下一个 — 调查负荷较重的团队应在 信誉 API 中登记 2–3 个密钥。
访问权限
- 查询端点
GET /security/ip-reputation：因为它是纯查询，所以没有二次提权确认，也没有审计日志。它位于安全菜单领域（min_req 2）之后，因此安全人员（staff=5）及以上实际上都能访问。它不会向外部发布任何内容，所以不属于破坏性操作。 - 无效 IP：
filter_var校验失败会返回 HTTP 422{"ok":false,"message":"invalid_ip"}。 - 密钥管理 信誉 API：对
infr_reputation_provider的增删改查、实时测试和优先级拖拽仅限管理员（admin=10，level≥5），并记入审计。密钥加密存储，编辑时只能替换或清除。 - 不泄露机密：API 密钥绝不会泄漏到响应体或错误体中（错误只记录为
http_STATUS字符串）。
排错与常见问题
弹窗提示「未配置 API 密钥」
infr_reputation_provider 中没有登记任何密钥，且 .env ABUSEIPDB_KEY 为空。请在 信誉 API 中添加一个 AbuseIPDB 密钥，或在 .env 中设置 ABUSEIPDB_KEY=YOUR_KEY。在此期间，可使用 [打开 AbuseIPDB] 按钮到外部站点查看。
一直出现「查询失败」
- 429（配额超限）：你可能已经耗尽免费版每天 1000 次的额度。登记更多密钥以汇聚配额，或次日重试。
- 401/403（密钥问题）：密钥已过期、输入有误或未启用。请在 信誉 API 中用 [实时测试] 验证。
- 网络（unreachable）：确认控制台主机到
api.abuseipdb.com（443）的出站访问没有被拦截。
刚封禁的 IP 分数仍然很低
结果会按 IP 缓存 1 小时（infr:sec:abuse:{ip}）。如果需要最新数值，请最多等待一小时后重新查询。这层缓存的存在正是为了保护你的免费配额。
可以从这里向 AbuseIPDB 举报该 IP 吗？
不可以。该功能仅供查询。 举报提交（国际协作）属于另行推迟的响应阶段 — 这里不会向外部发布任何内容。
我只看到 6 条最近的举报
归一化步骤只保留最新的 6 条（MAX_REPORTS=6）。请通过 [打开 AbuseIPDB] 到外部站点查看完整历史。
这是白名单/内部 IP，但查询按钮被隐藏了
安全界面会给已登记实例的 IP（也就是你自己的网络）打上 Internal 徽章并隐藏信誉按钮（SecurityScope） — 这样可以避免 Suricata 的方向标签把我们自己的服务器标为「来源」时造成的困惑。内部网络的定义在 运维策略 中管理。
相关内容
- 信誉 API 管理 — AbuseIPDB 多密钥登记、轮询、实时测试
- 威胁 — 在研判 IDS 威胁实体时查询 IP 信誉
- 检测 · JA3 — 核实 JA3 违规者 / 异常 IP 的信誉
- 封禁列表与信誉 — 封禁列表 + 信誉交叉核对 + 封禁深层链接
- 安全概览 — 防御漏斗与高危威胁 IP
- 白名单 — 封禁豁免与 srct 自动无罪白名单
