Metadata-Version: 2.4
Name: cymrubogons
Version: 0.1.0
Summary: Team Cymru Bogon Reference Checker for IPv4, IPv6, and ASNs
Author-email: Alex Semenyaka <alex.semenyaka@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/your-username/cymrubogons
Project-URL: Repository, https://github.com/your-username/cymrubogons.git
Project-URL: Issues, https://github.com/your-username/cymrubogons/issues
Keywords: bogon,team-cymru,ipv4,ipv6,asn,security,networking,bgp
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# cymrubogons: Team Cymru Bogon Reference Checker

## Introduction

### Theoretical Background
In the context of Internet routing, a ***Bogon*** refers to an IP address space that should not be visible in the global routing table. These are typically addresses that have not yet been allocated to a Regional Internet Registry (RIR) or are reserved for private, testing, or future use.

There are two primary categories of bogons:
* ***Standard Bogons:*** Unallocated or reserved address space.
* ***Full Bogons:*** Includes standard bogons plus address space that has been allocated to an RIR but has not yet been assigned to an ISP or end-user.

Team Cymru provides real-time and bulk data services to track these prefixes. Using bogon filters helps network operators prevent traffic from spoofed or unassigned addresses, enhancing overall network security.

### Package Purpose
The `cymrubogons` package provides a production-ready, high-performance interface for both synchronous and asynchronous Python applications to verify IP addresses and Autonomous System Numbers (ASNs) against Team Cymru’s datasets via HTTP and DNS (DNSBL).

## Global Configuration

The package behavior is controlled by a global `CONFIG` instance of the `Config` dataclass.

### Class: `Config`
A dataclass containing adjustable constants for timeouts and cache behavior.

| Attribute | Type | Description |
| --- | --- | --- |
| `HTTP_TIMEOUT` | `float` | Timeout for fetching bulk lists via HTTP (default: `15.0`). |
| `HTTP_HEAD_TIMEOUT` | `float` | Timeout for checking `Last-Modified` headers (default: `10.0`). |
| `DNS_LIFETIME` | `float` | Timeout for a single DNS query (default: `3.0`). |
| `DNS_CLEAN_TTL` | `int` | TTL in seconds for negative DNS responses in cache (default: `3600`). |
| `HARD_EXPIRY` | `int` | Force a refresh of the HTTP list regardless of headers (default: `14400`). |
| `MAX_DNS_CACHE_SIZE` | `int` | Maximum number of entries in the global DNS cache (default: `10000`). |

Access the global instance via:
```python
from cymrubogons import CONFIG
CONFIG.HTTP_TIMEOUT = 20.0
```

## IP Checking

### Class: `IPBogonChecker` (Synchronous)
The primary class for checking IP addresses using standard synchronous execution.

#### `__init__`
Initializes a new checker instance.

* ***Arguments:***
  * `mode` (str, optional): The operation mode. Must be ’http'`, ’dns'`, or ’hybrid'`. Default: ’http'`. ’hybrid': combines the high speed of local HTTP caching with the real-time accuracy of DNSBL, automatically falling back to DNS queries if an address is not found in the local lists.
  * `list_type` (str, optional): The list type to track. Must be ’bogons'` or ’full_bogons'`. Default: ’full_bogons'`.
  * `nameservers` (list, optional): A list of DNS server IP addresses to use for race-condition queries. If `None`, system defaults are used.
  * `dns_strict_mode` (bool, optional): If `True`, the address is considered a bogon if **any** server responds positively. If `False` (default), the first `NXDOMAIN` response marks it as clean.

#### `is_bogon`
Checks if a single IP address is a bogon.

* ***Arguments:***
  * `ip` (str or ipaddress object): The IP address to verify.
* ***Returns:*** `str` (the matching prefix or source) if it is a bogon, `""` if clean, `None` on error.
* ***Raises:***
  * ValueError: If the provided ip string is not a valid IPv4 or IPv6 address.

#### `are_bogons`
Batch verification of multiple IP addresses.

* ***Arguments:***
  * `ips` (list): A list of IP addresses (strings or objects).
* ***Returns:*** `list` of strings or `None`.

#### `set_https_cache` (Class Method)
Configures local file caching for HTTP lists.

* ***Arguments:***
  * `cache_file` (str): Path to the local cache file.
  * `threshold` (int, optional): Minimum age in seconds before checking for updates (default: `300`).
  * `offline_mode` (bool, optional): If `True`, the checker will use a stale cache if the network is unavailable (default: `False`).

#### `get_bogon_prefixes` (Class Method)
Fetches the current list of bogon prefixes.

* ***Arguments:***
  * `list_type` (str, optional): ’bogons'` or ’full_bogons'`.
  * `output_format` (str, optional): ’str'` (default) or ’ipaddress'`.
  * `protocols` (tuple, optional): `('v4', 'v6')` by default.

### Class: `aIPBogonChecker` (Asynchronous)
Inherits from `IPBogonChecker`. All methods are `async` coroutines.

#### `is_bogon` (Async)
Same signature as sync version, but must be awaited.

#### `are_bogons` (Async)
Executes batch checks concurrently using `asyncio.gather`.

#### `aio_get_bogon_prefixes` (Async Class Method)
Asynchronous version of `get_bogon_prefixes`.

## ASN Checking

### Class: `ASNBogonChecker` (Synchronous)
Verifies Autonomous System Numbers against predefined bogon ranges (reserved, private, unallocated).

#### `is_bogon`
* ***Arguments:***
  * `asn` (int or str): The ASN to check.
* ***Returns:*** `str` (range description) if bogon, `""` if clean.
* ***Raises:***
  * ValueError: If the provided ip string is not a valid ASN.

#### `are_bogons`
* ***Arguments:***
  * `asns` (list): List of ASNs.

### Class: `aASNBogonChecker` (Asynchronous)
Coroutines for ASN verification. Same signatures as synchronous versions.

## DNS Cache Management

The package maintains a global thread-safe DNS cache.

* `clear_dns_cache()`: A global function to wipe the DNS cache. Use this when switching nameservers or performing diagnostics.

## Logging Management

The library uses the standard Python `logging` module. All internal events are logged using the logger named `cymrubogons.bogons`.

### Log Levels
* ***DEBUG:*** Detailed technical information, including cache hits, DNS query strings, and race conditions.
* ***INFO:*** Major state changes, such as downloading new bogon lists or building searchable structures.
* ***WARNING:*** Recoverable errors, like a failed network fetch where a local cache fallback was available, or a full DNS cache purge.
* ***ERROR:*** Critical failures, such as invalid input formats or total inability to update the bogon state (no network and no cache).

### Configuration Example
```python
import logging

logging.basicConfig(level=logging.INFO)
# Increase verbosity for the checker specifically
logging.getLogger("cymrubogons.bogons").setLevel(logging.DEBUG)
```
All log messages use `%` style formatting for performance and reliability.
