isIPsafe

isipsafe

适用于 isIPsafe 的官方 Python 客户端和命令行工具。isIPsafe 是一项免费的 IP 信誉查询和滥用报告服务。

• 检查 IP 地址是否具有恶意，再决定是否信任它
• 报告 日志中的攻击者，一次报告一个，或一次报告 10,000 个
• 下载封锁列表，格式可直接用于防火墙（nftables、ipset、nginx、apache、MikroTik、STIX 等）

除 Python 标准库外无其他依赖。Python 3.9+。

pip install isipsafe

获取 API 密钥

查询无需密钥（每个地址每天 400 次）。报告、批量上传和封锁列表需要从 isipsafe.com/login 获取免费密钥。使用密钥后，每天的查询限额也会提高到 10,000 次。

export ISIPSAFE_API_KEY=sl_your_key_here

客户端会通过 Authorization 标头发送密钥，而不会将其放在 URL 中，因此密钥不会出现在代理和服务器日志里。

Python

from isipsafe import Client

client = Client()  # reads ISIPSAFE_API_KEY, or pass Client("sl_...")

result = client.check("185.220.101.1")
print(result.abuse_confidence_score, result.total_reports, result.categories)

if result.is_malicious():  # score >= 75, has reports, not allowlisted
    block(result.ip_address)

client.report(
    "203.0.113.50",
    ["ssh", "brute-force"],
    comment="sshd: 212 failed logins in 10 minutes",
)

一次报告多个地址

result = client.bulk_report(
    [
        {"ip": "203.0.113.50", "categories": ["ssh", "brute-force"], "comment": "sshd"},
        {"ip": "198.51.100.4", "categories": "port-scan"},
    ]
)
print(result.saved_reports, result.invalid_reports)

封锁列表

ips = client.blocklist(confidence_minimum=90, except_countries=["GB"])
nft = client.blocklist_raw(format="nftables")

其他功能

方法	功能
check(ip, max_age_in_days=None, verbose=False)	查询一个地址的评分、报告数量、位置和网络信息
is_malicious(ip, threshold=75)	快捷方法，返回 True 或 False
report(ip, categories, comment=None, timestamp=None)	报告一个地址或 CIDR 网络
bulk_report(rows) / bulk_report_csv(text)	在一个请求中提交最多 10,000 条报告
reports(ip, page=1, per_page=25)	针对某个地址提交的报告，按时间从新到旧排列
check_block(network)	查询网络中的已报告地址（最多 /16 或 /48）
blocklist(...) / blocklist_raw(format=...)	置信度最高的地址
clear_address(ip)	删除你为某个地址提交的报告
categories()	所有报告类别及其 slug

错误

所有错误都继承自 isipsafe.IsIPsafeError。

异常	触发条件
AuthenticationError	API 密钥缺失或错误（401）
ValidationError	输入无效，或报告了已加入许可名单的地址（422）
RateLimitError	请求过多（429）；参见 .retry_after
APIError	其他任何错误状态；参见 .status
NetworkError	无法连接 API

网络错误和 5xx 响应会触发自动重试。同一地址在 15 分钟内被报告两次不算错误：report() 会返回 duplicate=True 的结果。

命令行

$ isipsafe check 185.220.101.1
185.220.101.1  not flagged
  score       56/100 (Medium)
  reports     24 from 5 reporters
  categories  port-scan, hacking, vuln-scan, web-app-attack, c2
  network     DE AS60729 Stiftung Erneuerbare Freiheit
  flags       Tor exit
  details     https://isipsafe.com/ip/185.220.101.1

$ isipsafe report 203.0.113.50 -c ssh,brute-force -m "sshd: 212 failed logins"
$ isipsafe bulk-report reports.csv
$ isipsafe blocklist --format nftables --confidence-minimum 90 -o blocklist.nft
$ isipsafe check-block 185.220.101.0/24
$ isipsafe categories

为 check、report、reports、check-block 和 categories 添加 --json，即可获得机器可读的输出。

在 shell 脚本中使用 --fail-if-malicious。如果地址具有恶意，命令会以状态码 1 退出：

if ! isipsafe check "$IP" --fail-if-malicious --threshold 80 > /dev/null; then
    echo "blocking $IP"
fi

退出代码：0 表示成功，1 表示具有恶意（仅在使用 --fail-if-malicious 时），2 表示错误。

类别

使用 slug 或数字 ID。常见类别包括：ssh、brute-force、port-scan、web-app-attack、sql-injection、vuln-scan、bad-bot、ddos、email-spam、phishing。运行 isipsafe categories 查看完整列表，或访问 isipsafe.com/categories。

链接

• 官方使用指南：isipsafe.com/integrations/python
• 网站：isipsafe.com
• API 参考：isipsafe.com/api
• 集成：isipsafe.com/integrations

许可

本仓库中的代码采用 MIT 许可。isIPsafe API 返回的数据受 isIPsafe EULA 约束。