Tornevall Networks

← Back to docs

DNSBL TXT metadata

DNSBL TXT metadata

The DNSBL A record contains the stable bitmask. TXT records carry more detailed, source-specific information that does not need its own bit.

The A-record bitmask is the compatibility contract for clients. Clients do not need to read or parse TXT records to use the DNSBL.

Visibility

TXT records published under dnsbl.tornevall.org and opm.tornevall.org are public DNS data. They must therefore only contain information intended for public visibility.

The following must not be published in these TXT records:

  • API tokens or other secrets
  • internal user or database IDs
  • internal debugging information
  • private notes
  • personal data not required for the public classification

Tools owns and updates the source-specific TXT namespaces below without modifying unrelated TXT records on the same DNSBL owner.

Tools-owned TXT and caller-defined TXT

The allow_custom_txt / can_custom_txt permission allows a caller to add its own TXT metadata. It does not allow the caller to replace or suppress TXT generated by Tools itself.

For normal DNSBL/FraudBL publication:

  • Tools always publishes its source-registration TXT on add/update.
  • Public site provenance supplied through source_site_host and source_site_url is included in the Tools-owned source-registration TXT.
  • Internal site/database IDs are not published in DNS TXT.
  • source_note / note, when the caller has permission to use it, is published as a separate additional TXT record.
  • Tools-owned Proxy verification: and Tor exit: records are separate namespaces and are not affected by caller-defined TXT.
  • API responses distinguish publication.source_txt, publication.custom_txt, and the combined publication.txt_records list.

Example with caller-defined TXT and WordPress provenance:

Source registration: DNSBL API publication. [source: wordpress/comment_report; site=example.org; url=https://example.org/]
Comment spam reported by site owner. [source: wordpress/comment_report]

Both records are expected to exist at the same time. Site host/URL belongs to the Tools-owned source registration; the caller's free-form TXT remains separate.

Proxy verification

Prefix:

Proxy verification:

Example:

Proxy verification: 203.0.113.10:8080; protocol=http; verified=yes; anonymous=yes; proxy_bitmask=130; proxy_flags=IP_CONFIRMED,IP_ANONYMOUS; schema=1; source=Tools proxy checker

proxy_bitmask and proxy_flags describe only what the proxy checker itself verified. Other reputation flags on the same IP, such as spam or fraud, must not be copied into this TXT record.

Bit 2 (IP_CONFIRMED) remains the active flag for a verified working proxy. Bit 1 remains deprecated and is not reused.

Tor exit

Prefix:

Tor exit:

Example:

Tor exit: 203.0.113.20; current=yes; tor_bitmask=160; tor_flags=IP_SECOND_EXIT,IP_ANONYMOUS; schema=1; source=Tor Project

The Tor TXT record describes the authoritative Tor Project classification and is separate from Proxy verification:. A Tor exit does not need to be verified as an open proxy endpoint.

When Tor synchronization owns the Tor state for an IP:

  • a current exit adds or retains the managed Tor exit: record
  • an IP missing from a later successful Tor snapshot has the managed Tor exit: record removed
  • if the same IP is still a working ordinary proxy, its separate Proxy verification: record is retained
  • if the Tor source cannot be refreshed, no negative Tor cleanup is performed

Schema and stability

schema=1 makes the format versionable. Fields should remain stable and machine-readable.

Do not add volatile timestamps to TXT values. Proxy/Tor synchronization compares exact values, and a timestamp would otherwise force unnecessary DNS updates on every sweep.