API reference

exception pypdns.ForbiddenError

exception pypdns.PDNSError

class pypdns.PDNSRecord(record: dict[str, str | int | bool | list[str] | dict[Any, Any] | None])

A pythonesque Passive DNS record, see RFC for details: https://www.ietf.org/id/draft-dulaunoy-dnsop-passive-dns-cof-10.html

property bailiwick: str | None

The best estimate of the apex of the zone where this data is authoritative

property count: int | None

How many authoritative DNS answers were received at the Passive DNS Server’s collectors with exactly the given set of values as answers

property origin: str | None

The resource origin of the Passive DNS response

property raw: dict[str, str | int | bool | list[str] | dict[Any, Any] | None]

The raw record

property rdata: str | list[str]

The resource records of the queried resource

property record: TypedPDNSRecord

The record as a python dictionary

property rrname: str

The name of the queried resource

property rrtype: str

The resource record type as seen by the passive DNS

property sensor_id: str | None

The sensor information where the record was seen.

property time_first: int

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS

property time_first_datetime: datetime

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, as a python datetime.

property time_first_ms: int | None

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).

property time_last: int

The last time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS

property time_last_datetime: datetime

The last time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, as a python datetime.

property time_last_ms: int | None

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).

property zone_time_first: int | None

The first time that the unique tuple (rrname, rrtype, rdata) record has been seen via master file import

property zone_time_last: int | None

The last time that the unique tuple (rrname, rrtype, rdata) record has been seen via master file import

exception pypdns.RateLimitError

exception pypdns.ServerError

class pypdns.TypedPDNSRecord

A dict representing a Passive DNS record

exception pypdns.UnauthorizedError

PyPDNS

class pypdns.PyPDNS(url: str = 'https://www.circl.lu/pdns/query', basic_auth: tuple[str, str] | None = None, auth_token: str | None = None, enable_cache: bool = False, cache_expire_after: int = 604800, cache_file: str = '/tmp/pdns.cache', https_proxy_string: str | None = None, useragent: str | None = None, disable_active_query: bool = False, *, proxies: dict[str, str] | None = None)

iter_query(q: str, filter_rrtype: str | None = None, break_on_errors: bool = False) → Generator[PDNSRecord, None, dict[str, str | int] | None]

Iterate over all the recording matching your request, useful if there are a lot. Note: the order is non-deterministic.

Parameters:

• q – The query

• filter_rrtype – The filter, must be a valid RR Type or the response will be empty.

• break_on_errors – If there is an error, stop iterating and break immediately

query(q: str, sort_by: str = 'time_last', timeout: int | None = None) → list[dict[str, Any]]

This method (almost) returns the response from the server but turns the times into python datetime. It was a bad design decision hears ago. Use rfc_query instead for something saner. This method is deprecated.

rfc_query(q: str, /, *, sort_by: str = 'time_last', filter_rrtype: str | None = None, with_errors: Literal[True]) → tuple[list[PDNSRecord], dict[str, str | int]]

rfc_query(q: str, /, *, sort_by: str = 'time_last', filter_rrtype: str | None = None, with_errors: Literal[False]) → list[PDNSRecord]

Triggers a non-paginated query, can be sorted but will raise an error if the response is too big.

Parameters:

• q – The query

• sort_by – The key to use to sort the records

• filter_rrtype – The filter, must be a valid RR Type or the response will be enpty.

• with_errors – Returns the errors (if any)

class pypdns.PDNSRecord(record: dict[str, str | int | bool | list[str] | dict[Any, Any] | None])

A pythonesque Passive DNS record, see RFC for details: https://www.ietf.org/id/draft-dulaunoy-dnsop-passive-dns-cof-10.html

property bailiwick: str | None

The best estimate of the apex of the zone where this data is authoritative

property count: int | None

How many authoritative DNS answers were received at the Passive DNS Server’s collectors with exactly the given set of values as answers

property origin: str | None

The resource origin of the Passive DNS response

property raw: dict[str, str | int | bool | list[str] | dict[Any, Any] | None]

The raw record

property rdata: str | list[str]

The resource records of the queried resource

property record: TypedPDNSRecord

The record as a python dictionary

property rrname: str

The name of the queried resource

property rrtype: str

The resource record type as seen by the passive DNS

property sensor_id: str | None

The sensor information where the record was seen.

property time_first: int

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS

property time_first_datetime: datetime

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, as a python datetime.

property time_first_ms: int | None

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).

property time_last: int

The last time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS

property time_last_datetime: datetime

The last time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, as a python datetime.

property time_last_ms: int | None

The first time that the record / unique tuple (rrname, rrtype, rdata) has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).

property zone_time_first: int | None

The first time that the unique tuple (rrname, rrtype, rdata) record has been seen via master file import

property zone_time_last: int | None

The last time that the unique tuple (rrname, rrtype, rdata) record has been seen via master file import