Tornevall Networks

← Back to docs

DNSBL / FraudBL API-referens

Language: SV | EN | SV

Endpoint: dnsbl - nuvarande ToolsAPI-modell för DNSBL / FraudBL

Status

Den här sidan dokumenterar den nuvarande ToolsAPI-modellen på tools.tornevall.* tillsammans med hur WordPress-pluginet arbetar idag.

Det historiska gränssnittet DNSBL v5 / API v3 är deprecated, avvecklat och inte längre den aktiva integrationsmodellen. En legacy-referens ligger längst ned för kompatibilitet och migrering.

GDPR-notis

Äldre blacklistflöden kunde spara mer kontext kring varför en värd eller ett meddelande flaggades. Det är inte längre målet.

I dagens ToolsAPI-riktning måste GDPR och dataminimering beaktas innan data publiceras till DNS. Eftersom reputationslagret nu i praktiken distribueras via DNS-zoner och zonfiler måste anonymisering och minimering ske i själva publiceringsflödet. Endast data som behövs för klassificering, abuse-skydd och fraudskydd ska exponeras.

Innehåll

Nuvarande läge

När vi i detta dokument säger vårt API menar vi ToolsAPI på tools.tornevall.*.

Den aktiva modellen idag är:

  • reputationsdata konsumeras i slutänden via DNS-uppslag
  • ToolsAPI exponerar DNS zone API och DNS record API för att läsa och underhålla DNS-baserad data
  • WordPress-pluginet gör direkta DNS-uppslag och håller egen cache/statistik
  • gamla 3.0/dnsbl-semantiker är inte längre det primära publika kontraktet

Viktig konsekvens

Det finns ingen ny publik en-till-en-ersättare för gamla PUT /3.0/dnsbl / DELETE /3.0/dnsbl som aktivt kontrakt.

Istället bygger dagens stack på:

  1. DNS-publicering och zonhantering i ToolsAPI
  2. direkt DNS-resolution hos konsumenter som WordPress-pluginet
  3. internt DNSBL/DNS-lager för specialiserade blacklistflöden, inklusive commerce-publicering

Bitmaskmodellen som används av ToolsAPI och pluginet

Det returnerade reputationsvärdet är ett bitmaskheltal.

Varje bit representerar ett specifikt tillstånd. Flera bitar kan vara aktiva samtidigt.

Bitmaskvärden

Värde Konstant Betydelse Status
1 FREE_SLOT_1_PREVIOUSLY_REPORTED Tidigare använd för äldre reported-IP-flöden. Betraktas som opålitlig. Deprecated
2 IP_CONFIRMED IP-adress verifierad som fungerande proxy. Aktiv
4 IP_PHISHING Värd verifierad som phishing- eller fraudinfrastruktur. Aktiv
8 IP_FRAUDCOMMERCE Reserverad för e-handelsrelaterad fraudklassificering. Får inte återanvändas för annat. Aktiv
16 IP_MAILSERVER_SPAM E-postspammare. Aktiv
32 IP_SECOND_EXIT Sekundär exitpunkt, till exempel TOR-exit eller alternativ abuse-IP. Aktiv
64 IP_ABUSE_NO_SMTP Allmän abuse via webbformulär, attacker, telnet, forum eller liknande kanaler. Aktiv
128 IP_ANONYMOUS Anonym proxy eller anonymiseringstjänst. Aktiv

Hur bitmasken fungerar

Svaret ska tolkas som en summa av aktiva bitar, aldrig som en enum med exakt en status.

Exempel:

4 + 16 + 64 = 84

Det betyder att värden samtidigt är klassad som:

  • phishing / fraudinfrastruktur
  • mailspamkälla
  • generell abuse

Implementationsregler

  • Flera bitar kan vara satta samtidigt.
  • Deprecated bitar ska ignoreras i ny logik.
  • Bitvärde 8 ska använda IP_FRAUDCOMMERCE.
  • Bitvärde 8 får inte återanvändas för något annat.
  • Konsumenter ska kontrollera varje bit individuellt.

Kompatibilitetsnotis

Historisk API v3-kod använde namnet FREE_SLOT_8_PREVIOUSLY_PROXYTIMEOUT för bit 8. Det namnet hör bara till legacy-modellen och ska betraktas som obsolet.

DNS-zoner och publiceringsmodell

Nuvarande DNSBL / FraudBL-stack är DNS-först.

Huvudzoner

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

Normalt beteende

  • Vanlig DNSBL-publicering använder fortsatt ordinarie DNS-modell.
  • Fraud-publicering använder fortsatt bl.fraudbl.org.
  • Commerce-relaterad fraud ska kunna publiceras i både:
    • ordinarie bl.fraudbl.org
    • dedikerade ecom.fraudbl.org

Commerce-publicering

När en commerce-blacklisting publiceras ska den inte bara skapa en vanlig FraudBL-post. Den ska även skapa en särskild commerce-post.

Exempel:

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

Den exakta DNS-namnskonstruktionen ska hanteras av DNSBL/DNS-lagret, inte rekonstrueras manuellt av klienter.

GDPR och anonymisering i DNS

Eftersom systemet publicerar via DNS-zonfiler kan modellen inte behandlas som ett databas-API där data alltid kan anonymiseras i efterhand.

Det innebär att:

  • dataminimering måste ske före publicering
  • endast nödvändig klassificeringsdata ska exponeras
  • commerce-publicering ska designas med anonymisering i åtanke
  • om encoding eller hashing införs ska DNSBL-lagret äga den logiken så den blir konsekvent

Aktiva ToolsAPI-endpoints

Aktiva läs-/skrivytor i kodbasen exponeras nu under både:

/api/dns
/api/dnsbl

DNS-endpoints är fortsatt den låg-nivåbaserade DNS-skrivytan.

DNSBL-endpoints är bekvämlighetsalias för reputationspublicering där klienten skickar IP-adress + bitmask och låter DNSBL-lagret avgöra encoding, zonval och commerce-mirroring.

Autentisering

Nuvarande endpoints stöder:

  • autentiserad webbsession
  • Authorization: Bearer <token>
  • X-API-Key: <token>
  • ?api_key=<token>
  • IP-whitelist när det är aktiverat server-side

Skrivendpoints

Aktiva skrivvägar är:

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

Nuvarande implementation:

  • skrivningar går via DnsUpdateService
  • DNSBL/FraudBL-publicering expanderas först av ett dedikerat DNSBL-publiceringslager
  • lyckade skrivningar triggar zonsynk
  • berörda cacheposter rensas efter lyckad uppdatering
  • delete kräver en specifik target för att undvika farlig rrset-delete

DNSBL-publiceringspayloads

POST /api/dnsbl/records/add

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

Det publicerar idag till både:

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

med target:

127.0.0.12

POST /api/dnsbl/records/delete

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

Vid delete tas den specifika A-recorden bort från varje ägare som DNSBL-publiceringslagret genererar. För commerce betyder det både ordinarie FraudBL-zonen och dedikerade ecom-zonen.

POST /api/dnsbl/records/update

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

Update kräver old_bitmask så DNS-lagret säkert kan ta bort tidigare 127.0.0.X innan den nya targeten läggs till.

TTL-standard i nuvarande skrivväg

Aktiva DNS-uppdateringslagret använder standard-TTL 300 sekunder för nya poster om inget annat anges. Det matchar den korta TTL-nivå som behövs för snabbföränderlig reputationsdata.

Commerce-flöde, removals och TTL

Commerce-flöde

Avsedd arkitektur idag är:

  1. Request kommer in via ToolsAPI DNSBL / commerce-flödet.
  2. ToolsAPI skickar operationen vidare till DNSBL/DNS-lagret.
  3. DNSBL-lagret ansvarar för encoding / anonymisering om det behövs.
  4. DNS/DNS-zonlagret skriver, uppdaterar eller tar bort de publicerade posterna.

Detta håller anonymisering och namnsättning samlat i ett lager.

Nuvarande encodingansvar

Nuvarande implementation använder fortfarande reverse-IP-encoding för publicerade owner-namn.

Det viktiga arkitekturella kravet är att klienten inte ska bygga dessa namn själv. Om hashing eller annan GDPR-driven encoding införs senare ska den förändringen ske i DNSBL-publiceringslagret och inte i klienter eller generiska DNS-endpoints.

Removals

För commerce-relaterade removals ska delete täcka både:

  • ordinarie bl.fraudbl.org
  • dedikerade ecom.fraudbl.org

TTL-policy

Commerce-relaterade poster ska använda kortast säkra TTL i DNS-miljön.

Rekommenderat riktvärde:

300 sekunder

WordPress-pluginets beteende

Nuvarande WordPress-plugin drivs inte längre av gamla API v3-kontraktet.

Pluginet:

  • gör direkta DNS-uppslag mot konfigurerade resolvers
  • tolkar returvärdet som en bitmask
  • lagrar lokal cache i WordPress
  • registrerar lokal statistik
  • använder whitelist för säker testning och dry-run i wp-admin

Legacy: historisk DNSBL v5 / API v3-referens

Deprecated

Allt i detta avsnitt är endast historisk referens och inte längre den aktiva integrationsmodellen för ToolsAPI.

Historiska permissions

Legacy-permissions inkluderade bland annat:

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

Historiska typer

Det gamla API:t beskrev bland annat:

  • dnsbl
  • ecommerce

Även i legacy-koden behandlades commerce som specialfall och refererade till:

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

Historisk flaggnotis

Äldre API v3-kod namngav tidigare bit 8 som:

FREE_SLOT_8_PREVIOUSLY_PROXYTIMEOUT

Det namnet ska inte användas i nya specifikationer.

Relaterad dokumentation

Senast uppdaterad: 2026-03-14