Tornevall Networks

← Back to docs

DNSBL / FraudBL API Reference

Language: EN | EN | SV

Endpoint: dnsbl - current ToolsAPI DNSBL / FraudBL model

Status

This page now documents the current ToolsAPI model used on tools.tornevall.* together with the current WordPress DNSBL plugin behaviour.

The historical DNSBL v5 / API v3 interface is deprecated, phased out, and no longer the active integration model. A legacy reference is kept at the bottom of this page for compatibility and migration work.

GDPR notice

Older blacklist workflows sometimes stored more contextual material around why a host or message was flagged. That is no longer the design target.

In the current ToolsAPI direction, GDPR and data minimization must be considered before data is published to DNS. Because the live reputation layer is now distributed through DNS zones and zone files rather than a real-time database API, anonymization and minimization must happen in the publication flow itself. Only data required for classification, abuse mitigation, and fraud protection should be exposed.

Table of contents

Current status

With "our API" in this document, we mean ToolsAPI, hosted on tools.tornevall.*.

Today, the active model is:

  • reputation data is ultimately consumed through DNS lookups
  • ToolsAPI exposes the DNS zone and DNS record APIs used to inspect and maintain DNS-backed data
  • the WordPress plugin performs direct DNS lookups and keeps its own local cache/statistics
  • old 3.0/dnsbl request semantics are no longer the primary public contract

Important consequence

There is not a new public one-to-one replacement for the old PUT /3.0/dnsbl / DELETE /3.0/dnsbl workflow documented here as an active API.

Instead, the current stack is built around:

  1. DNS publication and zone management in ToolsAPI
  2. direct DNS resolution by consumers such as the WordPress plugin
  3. internal DNSBL/DNS handling for specialized blacklist flows, including commerce-related publication

Bitmask model used by ToolsAPI and the plugin

The returned reputation value is a bitmask integer.

Each bit represents a specific reputation state. Multiple bits can be active at the same time.

Bitmask values

Value Constant Meaning Status
1 FREE_SLOT_1_PREVIOUSLY_REPORTED Previously used for older reported-IP flows. Considered unreliable. Deprecated
2 IP_CONFIRMED IP address confirmed as a working proxy. Active
4 IP_PHISHING Host confirmed as phishing or fraud infrastructure. Active
8 IP_FRAUDCOMMERCE Reserved for e-commerce fraud classification. This value is occupied and must not be reused for anything else. Active
16 IP_MAILSERVER_SPAM E-mail spam source. Active
32 IP_SECOND_EXIT Secondary exit point, for example TOR exit or alternate abuse IP. Active
64 IP_ABUSE_NO_SMTP General abuse through web forms, attacks, telnet, forums, or similar channels. Active
128 IP_ANONYMOUS Anonymous proxy or anonymizing service. Active

How the bitmask works

You must treat the response as a sum of active bits, never as a single-status enum.

Example:

4 + 16 + 64 = 84

This means the host is simultaneously classified as:

  • phishing / fraud infrastructure
  • mail spam source
  • general abuse

Implementation rules

  • Multiple bits may be set at once.
  • Deprecated bits should be ignored in new logic.
  • Bit value 8 must use IP_FRAUDCOMMERCE.
  • Bit value 8 must not be recycled for an unrelated meaning.
  • Consumers should check each bit individually.

Compatibility note

Historical API v3 code used the name FREE_SLOT_8_PREVIOUSLY_PROXYTIMEOUT for bit 8. That name belongs to the legacy model only and should be considered obsolete in new documentation and new integration logic.

DNS zones and publication model

The current DNSBL / FraudBL stack is DNS-first.

Main zones

  • dnsbl.tornevall.org
  • bl.fraudbl.org
  • ecom.fraudbl.org

Normal behaviour

  • Standard DNSBL publication continues to use the ordinary DNS-backed model.
  • Fraud-related publication continues to use bl.fraudbl.org.
  • Commerce-related fraud publication must be able to exist in both:
    • the ordinary bl.fraudbl.org zone
    • the dedicated ecom.fraudbl.org zone

Commerce publication

When a commerce blacklist event is published, it should not only create a regular FraudBL-style entry. It should also create a dedicated commerce entry.

Example zone target:

X.X.X.X.ecom.fraudbl.org

The exact DNS name construction for commerce publication should be handled by the DNSBL/DNS layer, not manually reconstructed by external callers.

GDPR and anonymization in DNS

Because the current system publishes through DNS zone files, you cannot treat the data model like a database-driven API that can always be rewritten or anonymized afterward.

Therefore:

  • data minimization must happen before publication
  • only necessary classification data should be exposed
  • e-commerce publication should be designed with anonymization in mind
  • if encoding or hashing is used for commerce publication, the DNSBL component should own that encoding so it is applied consistently

Current ToolsAPI endpoints in active use

The active write/read surfaces in the current codebase are now exposed under both:

/api/dns
/api/dnsbl

The DNS endpoints remain the low-level DNS-backed write surface.

The DNSBL endpoints are convenience aliases for reputation publication where the caller sends an IP address plus a bitmask and lets the DNSBL layer decide owner encoding, zone selection, and commerce mirroring.

Authentication

The current DNS endpoints support these access modes:

  • authenticated web session
  • Authorization: Bearer <token>
  • X-API-Key: <token>
  • ?api_key=<token> query parameter
  • IP whitelist access, when enabled server-side

Zone discovery

GET /api/dns/zones

Lists zones available to the caller.

Possible access types in responses include:

  • authenticated
  • api_key_global
  • ip_whitelist

Example:

{
  "ok": true,
  "count": 2,
  "zones": [
    {
      "zone": "dnsbl.tornevall.org",
      "file": "...",
      "key": "dnsbl.tornevall.org"
    }
  ],
  "access_type": "authenticated"
}

Zone data

GET /api/dns/zones/{zone}

Returns zone data for a specific zone.

Supported read modes in the current controller are:

  • AXFR-based retrieval
  • file-based retrieval
  • cache-assisted UI flow via the dedicated cache endpoints below

The response contains paged zoneData records with fields such as:

  • name
  • type
  • rdata
  • ttl
  • class

GET /api/dns/zones/{zone}/axfr

Forces an AXFR-style fetch path in the current controller flow. AXFR is used because dynamic DNS updates may exist in journal state before they are flushed to local zone files.

GET /api/dns/zones/{zone}/cache

Checks whether a fresh cache entry exists.

Response source values currently include:

  • from_database
  • needs_axfr

If cache is available, the response can include:

  • cached_at
  • cache_age
  • cache_ttl_seconds
  • paged zoneData

GET /api/dns/zones/{zone}/search?q=...

Searches cached zone data only.

Important behaviour in the current implementation:

  • it never triggers AXFR on its own
  • it can use fresh cache or stale cache if no fresh cache exists
  • it supports:
    • exact IP search
    • CIDR search
    • plain text fallback search
  • DNSBL-style reversed owners are decoded back to forward IP form for matching

Possible response source values include:

  • from_database
  • from_database_stale

POST /api/dns/zones/{zone}/cache/clear

Clears the stored cache entry for one zone.

DNS record updates

These endpoints are the active write surface in the public ToolsAPI codebase:

  • POST /api/dns/records/add
  • POST /api/dns/records/delete
  • POST /api/dns/records/update
  • POST /api/dns/records/bulk

The same DNSBL publication logic is also reachable through:

  • POST /api/dnsbl/records/add
  • POST /api/dnsbl/records/delete
  • POST /api/dnsbl/records/update

Current implementation notes:

  • writes go through DnsUpdateService
  • DNSBL/FraudBL publication payloads are expanded by a dedicated DNSBL publication layer before the DNS update service runs
  • updates are sent directly to the DNS master via the DNS update layer
  • successful writes trigger zone sync handling
  • affected zone caches are cleared after successful updates
  • delete operations require a specific target value to avoid dangerous full-RRset deletion

DNSBL publication payloads

When you use the DNSBL-oriented write flow, you send an IP address and a bitmask instead of constructing owner names yourself.

POST /api/dnsbl/records/add

{
  "ip": "1.2.3.4",
  "bitmask": 12,
  "publication_type": "commerce",
  "ttl": 300
}

This currently results in publication to both:

  • 4.3.2.1.bl.fraudbl.org
  • 4.3.2.1.ecom.fraudbl.org

with target:

127.0.0.12

POST /api/dnsbl/records/delete

{
  "ip": "1.2.3.4",
  "bitmask": 12,
  "publication_type": "commerce"
}

Delete requests remove the specific A record target from every owner generated by the DNSBL publication layer. For commerce-related entries that means both the ordinary FraudBL zone and the dedicated ecom zone.

POST /api/dnsbl/records/update

{
  "ip": "1.2.3.4",
  "old_bitmask": 4,
  "bitmask": 12,
  "publication_type": "commerce",
  "ttl": 300
}

Update requests require old_bitmask so the DNS update layer can safely delete the previous 127.0.0.X target before inserting the new one.

TTL defaults in current write path

The active DNS update service uses a default TTL of 300 seconds for new records unless another TTL is supplied. That aligns with the intended low-TTL approach for fast-changing reputation data.

Commerce flow, removals, and TTL

Commerce flow

The intended commerce flow in the current ToolsAPI architecture is:

  1. A request enters through the ToolsAPI DNSBL / commerce flow.
  2. ToolsAPI hands the operation to the DNSBL/DNS handling layer.
  3. The DNSBL layer is responsible for encoding / anonymizing the entry if required.
  4. The DNS/DNS zone layer writes, updates, or removes the published DNS records.

This keeps anonymization and naming logic in one place.

Current encoding responsibility

The current implementation still uses reverse-IP owner encoding for the published DNS owner names.

That is intentional for now: the important architectural rule is that the caller does not construct those names manually. If anonymized hashing or another GDPR-driven encoding model is introduced later, that change belongs in the DNSBL publication layer rather than in clients or in the generic DNS endpoints.

Removals

For commerce-related removals, delete handling should cover both:

  • the regular bl.fraudbl.org entry
  • the dedicated ecom.fraudbl.org entry

TTL policy

Commerce-related records should use the shortest safe TTL in the DNS environment.

Recommended target:

300 seconds

Why this matters:

  • commerce-related classifications must be safe for merchants
  • stale fraud verdicts should not linger longer than necessary
  • removals should propagate quickly

WordPress DNSBL plugin behaviour

The current WordPress plugin is no longer driven by the old API v3 endpoint contract.

What the plugin does today

The current plugin code:

  • performs direct DNS lookups against configured resolvers
  • defaults to:
    • dnsbl.tornevall.org
    • bl.fraudbl.org
  • decodes the returned 127.0.0.X result into a bitmask
  • records request statistics locally in WordPress
  • stores lookup cache locally in WordPress
  • supports safe local testing through a whitelist model

Cache and cleanup

The current plugin cache model now uses:

  • default TTL: 600 seconds
  • minimum TTL: 300 seconds
  • default cleanup interval: 300 seconds

The plugin also includes scheduled cleanup of expired cache entries.

Statistics shown by the plugin

The admin UI now distinguishes between:

  • total cached entries
  • cached blacklisted entries
  • cached clear / non-listed entries

It also records live event statistics such as:

  • total checks
  • unique visitors
  • blacklist hits
  • blocked requests
  • unique blocked visitors
  • 24-hour snapshot

Whitelist model

Whitelisted IPs are still:

  • checked
  • counted in statistics
  • allowed to appear in testing

But they are not:

  • blocked
  • redirected
  • marked as spam by the plugin's blocking logic

This is the intended safe dry-run model for WordPress administration.

Current visitor safety

For new installs, the current visitor IP can be seeded into the whitelist when REMOTE_ADDR is available.

The admin UI also supports:

  • warning notices when the current admin IP would otherwise match active flags
  • a shortcut to add the current visitor address to the whitelist

Optional Tools integration

The plugin also contains an optional Tools-based comment assessment call to:

/api/tools/dnsbl/comment-assess

That path is treated as an optional Tools integration by the plugin. The public DNS documentation on this page focuses on the active DNS-backed read/write model in the current ToolsAPI codebase.

Legacy: historical DNSBL v5 / API v3 reference

Deprecated

Everything in this section is historical reference material only. It is no longer the active integration model for ToolsAPI.

Historical version note

The DNSBL backend used to be described as version 5.0, while the HTTP layer was described as API v2 or API v3.

Historical permissions

Legacy permission names included:

  • allow_cidr
  • allow_cidr_update
  • can_purge
  • dnsbl_update
  • fraudbl_update
  • global_delist
  • local_delist
  • overwrite_flags

Historical API v2 request style

Legacy v2 lookup requests used forms like:

POST https://api.tornevall.net/2.0/dnsbl/ip/
bulk[]=ipaddr1&bulk[]=ipaddr2

The older API also used overloaded suffix syntax for extended info and add/delete operations.

Historical API v3 request style

POST /3.0/dnsbl/

Used to resolve or check whether an IP was listed.

Example:

{"ip":"1.2.3.4"}

PUT /3.0/dnsbl/

Used to insert or update blacklisted IP data.

Example:

{
  "ip": {
    "10.10.10.10": 64
  },
  "type": "dnsbl"
}

DELETE /3.0/dnsbl/

Used to delist or remove an IP.

Example:

{
  "ip": "1.2.3.4"
}

Historical registration types

The old API described:

  • dnsbl
  • ecommerce

In that legacy implementation, commerce registration was already treated as a special case and the old codebase also referenced:

  • dnsbl.tornevall.org
  • bl.fraudbl.org
  • ecom.fraudbl.org

Historical flag note

Older API v3 code still named bit 8 as:

FREE_SLOT_8_PREVIOUSLY_PROXYTIMEOUT

That naming is legacy-only and should not be used in current specifications.

Related documentation

Last Updated: 2026-03-14