Metadata-Version: 2.3
Name: abuse-whois
Version: 0.10.1
Summary: Find where to report a domain for abuse
Project-URL: Homepage, https://github.com/ninoseki/abuse_whois
Project-URL: Repository, https://github.com/ninoseki/abuse_whois
Author-email: Manabu Niseki <manabu.niseki@gmail.com>
License: MIT
Requires-Python: <3.13,>=3.10
Requires-Dist: aiometer<0.6,>=0.5
Requires-Dist: asyncache>=0.3.1
Requires-Dist: asyncer>=0.0.8
Requires-Dist: asyncwhois>=1.1.9
Requires-Dist: azuma>=0.5.1
Requires-Dist: cachetools>=5.5.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.10.3
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: returns>=0.24.0
Requires-Dist: stamina>=24.3.0
Requires-Dist: tld<0.14,>=0.13
Requires-Dist: validators~=0.34
Provides-Extra: api
Requires-Dist: fastapi[all]>=0.115.6; extra == 'api'
Requires-Dist: gunicorn>=23.0.0; extra == 'api'
Description-Content-Type: text/markdown

# abuse_whois

[![PyPI version](https://badge.fury.io/py/abuse-whois.svg)](https://badge.fury.io/py/abuse-whois)
[![Python CI](https://github.com/ninoseki/abuse_whois/actions/workflows/test.yml/badge.svg)](https://github.com/ninoseki/abuse_whois/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/github/ninoseki/abuse_whois/badge.svg?branch=main)](https://coveralls.io/github/ninoseki/abuse_whois?branch=main)

A Sigma and RDAP/Whois based abuse contacts finder.

![img](https://raw.githubusercontent.com/ninoseki/abuse_whois/main/images/overview.jpg)

This tool is highly inspired from the following libraries:

- https://github.com/bradleyjkemp/abwhose
- https://github.com/certsocietegenerale/abuse_finder

## How It Works

- Query a given address via RDAP (fallback to Whois is if RDAP fails)
- Check a query result with Sigma rules and find contacts (fallback to regex if there is no match)

## Requirements

- Python 3.10+

## Installation

```bash
pip install abuse_whois

# or if you want to use built-in REST API
pip install abuse_whois[api]
```

## Usage

### As a library

```python
from abuse_whois import get_abuse_contacts

await get_abuse_contacts("1.1.1.1")
await get_abuse_contacts("github.com")
await get_abuse_contacts("https://github.com")
await get_abuse_contacts("foo@example.com")
```

### As a CLI tool

```bash
abuse_whois 1.1.1.1
abuse_whois example.com
abuse_whois foo@example.com
abuse_whois http://example.com
```

### As a REST API

```bash
$ uvicorn abuse_whois.api.main:app
INFO:     Started server process [2283]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

$ http localhost:8000/api/whois/ address=https://github.com
```

### With Docker

```bash
git clone https://github.com/ninoseki/abuse_whois
cd abuse_whois
docker build . -t abuse-whois
docker run -i -d -p 8000:8000 abuse-whois
```

## Settings

All settings can be done via environment variables or `.env` file.

| Name                                     | Type | Default | Desc.                                                   |
| ---------------------------------------- | ---- | ------- | ------------------------------------------------------- |
| QUERY_TIMEOUT                            | int  | 10      | Timeout value for whois lookup (seconds)                |
| QUERY_CACHE_SIZE                         | int  | 1024    | Cache size for whois lookup                             |
| QUERY_CACHE_TTL                          | int  | 3600    | Cache TTL value for whois lookup (seconds)              |
| QUERY_MAX_RETRIES                        | int  | 3       | Max retries on timeout error                            |
| ADDITIONAL_WHOIS_RULE_DIRECTORY          | str  |         | Additional contains contain whois rule files            |
| ADDITIONAL_SHARED_HOSTING_RULE_DIRECTORY | str  |         | Additional directory contains shared hosting rule files |

## Contributions

`abuse_whois` works based on a combination of static rules and a parsing result of whois response.

- Rules:
  - [Registrar and hosting provider](https://github.com/ninoseki/abuse_whois/wiki/Registrar-and-Hosting-Provider)
  - [Shared hosting provider](https://github.com/ninoseki/abuse_whois/wiki/Shared-Hosting)

Please submit a PR (or submit a feature request) if you find something missing.
