cymrubogons 0.1.0

Team Cymru Bogon Reference Checker for IPv4, IPv6, and ASNs

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:

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

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.