Blacklist

How Telescope monitors domain reputation across DNS-based blacklists and Google Safe Browsing.

Blacklist monitors check whether a domain is listed on DNS-based blacklists (DNSBLs) or flagged by Google Safe Browsing. Being listed can mean your emails get rejected, your site gets flagged as malicious, or browsers show security warnings.

How a check works

Telescope resolves the domain from the monitor's target field (or parses the hostname from url).
For each configured blacklist, the appropriate check is executed:
- DNS-based lists (Spamhaus, SURBL, SpamCop): A DNS A-record query is constructed (e.g. example.com.dbl.spamhaus.org) and sent via DNS-over-HTTPS to Cloudflare's resolver.
- Google Safe Browsing: A POST request is sent to the Safe Browsing Lookup API v4 with the full URL and all threat types.
All checks run in parallel via Promise.all.
Each response is parsed per list rules. The overall status is determined: listed on any = down, all clean = up.

Checks never hang — every query uses AbortSignal.timeout (5 seconds). If a single list times out, the error is recorded but other lists still complete.

Status classification

Condition	Status	What it means
Not listed on any blacklist	Up	Domain reputation is clean
Listed on one or more blacklists	Down	Domain is blacklisted — take action
All blacklist checks failed	Down	Network errors or timeouts on every list
Partial failure (some lists errored)	Up	Clean on successful checks; errors logged

There is no degraded state — a domain is either listed or not.

Blacklists checked

DNS-based blacklists (default)

List	Query format	What it detects
Spamhaus DBL	`{domain}.dbl.spamhaus.org`	Spam, phishing, malware domains
SURBL	`{domain}.multi.surbl.org`	Phishing, malware, cracked, abuse URIs
SpamCop	`{domain}.bl.spamcop.net`	Spam sources

Google Safe Browsing (opt-in)

List	Method	What it detects
Google Safe Browsing	POST to Lookup API v4	Malware, social engineering, unwanted software, potentially harmful applications

Add google_safe_browsing (or the short name google) to the monitor's check_lists config to enable it. Requires GOOGLE_API_KEY environment variable.

Threat types

Threat type	What it means
`MALWARE`	Sites hosting or distributing malware
`SOCIAL_ENGINEERING`	Phishing and deceptive sites
`UNWANTED_SOFTWARE`	Sites hosting unwanted or harmful software
`POTENTIALLY_HARMFUL_APPLICATION`	Sites hosting apps that may harm devices

Response code reference

Spamhaus DBL

Response	Meaning
`127.0.1.x`	Spam domain
`127.0.2.x`	Phishing domain
`127.0.255.x`	Public resolver error (ignored — not a real listing)

SURBL

Uses bit flags in the last octet of 127.0.0.x:

Bit	Value	Meaning
3	8	Phishing
4	16	Malware
6	64	Abuse
7	128	Cracked

Multiple bits can be set simultaneously (e.g. 127.0.0.24 = phishing + malware).

SpamCop

Only a 127.0.0.2 response indicates a spam listing. Any other 127.x.x.x response is a public resolver block/error code and is ignored (not a real listing).

Configuration options

Setting	Default	Description
Check lists	`spamhaus_dbl`, `surbl`, `spamcop`	Which blacklists to query. Add `google_safe_browsing` for Safe Browsing.
Timeout	30 seconds (monitor-level)	How long to wait for the overall check
DNS query timeout	5 seconds	Per-list DNS-over-HTTPS query timeout
Safe Browsing timeout	5 seconds	Per-call Safe Browsing API timeout

API key

Google Safe Browsing requires a GOOGLE_API_KEY environment variable. This is the same key used by other Google APIs in Telescope (e.g. PageSpeed Insights). If the key is not configured, the Safe Browsing check will return an error entry while DNS-based checks continue normally.

To set up the API key:

Create a Google Cloud project (or use your existing one).
Enable the Safe Browsing API in the Google Cloud Console.
Generate an API key (or reuse your existing GOOGLE_API_KEY).
Set GOOGLE_API_KEY in the worker's environment.

Blacklist

On this page