sniffcat

Python client for the SniffCat IP reputation and abuse reporting API. https://pypi.org/project/sniffcat/

Features

• Fetch blacklist of suspicious IPs
• Check reputation and abuse score for any IP
• View reports about IP activity
• Report suspicious IPs (e.g., for port scanning, spam, malware, etc.)

Installation

pip install sniffcat

Usage

from sniffcat import SniffCatClient, Category

# Initialize the client with your API token (optional request timeout in seconds, default 15)
client = SniffCatClient("your_api_token", timeout=15)

# Example 1: Get blacklist (JSON) with default confidence (50)
blacklist = client.get_blacklist()
print("Blacklist:", blacklist)

# Example 2: IPv4 addresses from Europe with confidence >= 85, at most 5000 entries
blacklist_eu = client.get_blacklist(
    confidence_min=85,
    ip_version=4,
    include_countries=["PL", "DE", "FR"],
    limit=5000,
)
print("Blacklist (EU):", blacklist_eu)

# Example 3: Plain list of IP strings for port scanners and SSH attackers
ips = client.get_blacklist(confidence_min=70, categories=[Category.PORT_SCAN, Category.SSH], as_text=True)
print("IPs:", ips)

# Example 4: Check reputation and abuse score for an IP (with up to 48 recent reports)
ip_info = client.check_ip("1.1.1.1", with_reports=True)
print("IP info:", ip_info)

# Example 5: Get reports for an IP from the last 90 days, page 2, 50 per page
reports = client.get_ip_reports("1.1.1.1", max_age_in_days=90, per_page=50, page=2)
print("IP reports:", reports)

# Example 6: Report an IP for port scanning with default comment
result = client.report_ip_port_scan("1.1.1.1")
print("Report result:", result)

# Example 7: Report IP for spam (14) and malware hosting (7)
result_multi = client.report_ip("1.2.3.4", [Category.SPAM, Category.MALWARE_HOSTING], comment="Spam and malware activity detected")
print("Multi-category report result:", result_multi)

Notes

• comment in report_ip() must be at least 10 characters. If you leave it empty, one is generated from the category names.
• The same IP can only be reported once every 20 minutes (the API returns HTTP 429 otherwise).
• confidence_min must be between 30 and 100. Invalid arguments raise ValueError.
• API errors are returned as the API's JSON; network failures return {"error": "Request failed", ...}.

Categories

All categories are available as sniffcat.Category, e.g. Category.PORT_SCAN (4), Category.BRUTE_FORCE (17), Category.SSH (18). See descriptions at https://sniffcat.com/documentation/categories

API Documentation

See full API docs at https://sniffcat.com/documentation/api

License

MIT

Changelog

[0.2.0] - 2026-09-29

Added

• Category enum with all 27 report categories.
• get_blacklist(): limit, ip_version, include_countries, exclude_countries, categories and as_text parameters.
• check_ip(): with_reports parameter.
• get_ip_reports(): max_age_in_days, per_page and page parameters.

Fixed

• get_blacklist() always returned {"error": "Invalid JSON"} because the API returns plain text by default; it now requests type=json.
• report_ip() with an empty comment was rejected by the API (min. 10 characters); a comment is now generated from the category names.
• README example used wrong category IDs for spam and malware.
• All requests now use a timeout (default 15s, configurable via SniffCatClient(token, timeout=...)), so calls can no longer hang forever.
• Network errors (connection refused, DNS, timeout) return {"error": "Request failed", ...} instead of raising.
• wrapper.py example used the old category key; it now uses SniffCatClient.
• Broken author field and placeholder url in setup.py.

Changed

• Requests reuse a single requests.Session (connection pooling).
• report_ip() accepts a single category ID as well as a list, and raises ValueError for an empty list.

[0.1.8] - 2025-09-02

Changed

• The payload key for reporting IPs was changed from category to categories in report_ip() to match SniffCat API requirements.

Added

• Custom User-Agent header:
  Now all requests use
  Mozilla/5.0 (compatible; SniffCat.py/{version}; +https://github.com/SniffCatDB/sniffcat.py)
  to help bypass Cloudflare Bot Fight Mode.

Fixed

• Improved error handling for non-JSON responses from the API.
• Documentation and usage examples updated to use SniffCatClient and the new categories parameter.