Metadata-Version: 2.4
Name: sniffcat
Version: 0.2.0
Summary: Python client for SniffCat API.
Home-page: https://github.com/SniffCatDB/sniffcat.py
Author: Dominik 'skiop' S.
Author-email: ntxg@proton.me
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# sniffcat

Python client for the [SniffCat](https://sniffcat.com/documentation/api) 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

```sh
pip install sniffcat
```

## Usage

```python
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](https://sniffcat.com/documentation/categories)

## API Documentation

See full API docs at [https://sniffcat.com/documentation/api](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.

