isIPsafe

isipsafe

Official Python client and command-line tool for isIPsafe, the free IP reputation and abuse reporting service.

• Check whether an IP address is malicious before you trust it
• Report attackers from your logs, one at a time or 10,000 at once
• Download the blocklist in a firewall-ready format (nftables, ipset, nginx, apache, MikroTik, STIX and more)

No dependencies outside the Python standard library. Python 3.9+.

pip install isipsafe

Get an API key

Lookups work without a key (400 per day per address). Reporting, bulk uploads and the blocklist need a free key from isipsafe.com/login. A key also raises the lookup limit to 10,000 per day.

export ISIPSAFE_API_KEY=sl_your_key_here

The client sends the key in an Authorization header, never in the URL, so it stays out of proxy and server logs.

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", )

Report many addresses at once

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)

Blocklist

ips = client.blocklist(confidence_minimum=90, except_countries=["GB"])

nft = client.blocklist_raw(format="nftables")

Everything else

Errors

Every error inherits from isipsafe.IsIPsafeError.

Lookups are retried automatically on network errors and 5xx responses. Reporting the same address twice within 15 minutes is not an error: report() returns a result with duplicate=True.

Command line

$ 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

Add --json to check, report, reports, check-block and categories for machine-readable output.

Use --fail-if-malicious in shell scripts. The command exits with status 1 when the address is malicious:

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

echo "blocking $IP" fi

Exit codes: 0 success, 1 malicious (only with --fail-if-malicious), 2 error.

Categories

Use the slug or the numeric ID. Common ones: ssh, brute-force, port-scan, web-app-attack, sql-injection, vuln-scan, bad-bot, ddos, email-spam, phishing. Run isipsafe categories for the full list, or see isipsafe.com/categories.

Links

• Official Usage Page: isipsafe.com/integrations/python
• Website: isipsafe.com
• API reference: isipsafe.com/api
• Integrations: isipsafe.com/integrations

Licence

The code in this repository is MIT licensed. Data returned by the isIPsafe API is covered by the isIPsafe EULA.